SDKs

Mailrith ships official TypeScript and Python SDKs generated from the same public contract that drives the OpenAPI document and capability map.

4 min read

TypeScript SDK

The official TypeScript SDK wraps the versioned public API and exposes stable resource namespaces like client.subscribers, client.broadcasts, and client.webhookSubscriptions.

Use it when you want Mailrith's REST surface with typed operation metadata, a shared fetch layer, and predictable request construction.

Install @mailrith/sdk in any Node.js or edge runtime that already supports fetch.
Create one client per API key or clone a client with withApiKey() when you rotate credentials.

Install and call Mailrith from TypeScript

import { createMailrithClient } from "@mailrith/sdk";

const client = createMailrithClient({
  apiKey: process.env.MAILRITH_API_KEY,
});

const capabilities = await client.discovery.getCapabilities();
const subscriber = await client.subscribers.upsert({
  body: {
    email: "ada@example.com",
    name: "Ada Lovelace",
    new_tags: ["Website Signup"],
  },
});

const draft = await client.broadcasts.create({
  body: {
    subject: "Welcome to Mailrith",
    preview_text: "A quick hello from the team",
    body: "<p>Hello {{ subscriber.name }}</p>",
    status: "draft",
  },
});

Python SDK

The official Python SDK is generated from the same Mailrith SDK manifest and exposes snake_case namespaces and methods that fit Python callers naturally.

It ships with a stdlib transport by default, so you can use it in simple scripts and automation workers without another HTTP dependency.

Install mailrith-sdk in Python 3.10+ environments.
Pass api_key once when you construct the client, then call resource methods with path=, query=, and body= dictionaries.

Install and call Mailrith from Python

import os
from mailrith_sdk import MailrithClient

client = MailrithClient(api_key=os.environ["MAILRITH_API_KEY"])

capabilities = client.discovery.get_capabilities()
subscribers = client.subscribers.list(query={"limit": 25})
broadcast = client.broadcasts.create(
    body={
        "subject": "Welcome to Mailrith",
        "preview_text": "A quick hello from the team",
        "body": "<p>Hello {{ subscriber.name }}</p>",
        "status": "draft",
    }
)

Generated from the public contract

Both SDKs are generated from Mailrith's versioned public API contract so the SDK surface stays aligned with the served OpenAPI document and authenticated capability model.

When the public contract changes in this repo, regenerate the shared SDK artifacts before you ship or test the updated packages.

Regenerate SDK artifacts from the public contract

pnpm generate:agent-artifacts

Need help shipping an integration?

Reach the Mailrith team if you need help planning a sync, validating a webhook flow, or troubleshooting a request.

Contact Mailrith

Related guides

4 min read

Agents

Discover Mailrith from agent runtimes with llms files, API metadata, OpenAPI, and authenticated capability discovery.

5 min read

MCP Server

Connect Mailrith to agent runtimes through the official remote MCP server and streamable HTTP transport.

4 min read

Quickstart

Create a workspace key and make the first authenticated request against Mailrith's public API.

Agents

MCP Server