SDKs

TypeScript SDK

1. Create a workspace API key by following Quickstart.
2. Install @mailrith/sdk in the server-side project that will call Mailrith.
3. Store the API key in MAILRITH_API_KEY or another server-side secret.
4. Create the client once for the workspace key.
5. Call client.discovery.getCapabilities() before you build a large workflow so you know what the key can access.
6. Build and test one low-risk request, such as a subscriber upsert, before you add sends, deletes, or import jobs.
7. Handle errors with the same rules described in Errors.

• Install @mailrith/sdk in any Node.js or edge runtime that already supports fetch.
• Pass the key through an environment variable or secret manager, not a checked-in config file.
• Use withApiKey() when you rotate credentials or when a service needs to switch between workspace keys intentionally.
• Handle SDK errors the same way you handle raw API errors: inspect the status and error code, then decide whether to retry, alert, or ask for corrected input.

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

1. Create a workspace API key for the Mailrith workspace the script will use.
2. Install mailrith-sdk in the Python environment.
3. Store the key in an environment variable such as MAILRITH_API_KEY.
4. Create MailrithClient(api_key=...) at the start of the script.
5. Call one list endpoint with a small limit to confirm that authentication works and the key has the expected workspace scope.
6. For large syncs, loop through cursor pages as explained in Pagination.
7. For import or export jobs, send an idempotency key as explained in Idempotency.

• 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.
• Use pagination loops for list operations instead of assuming a single page contains every record.
• Use idempotency keys for import and export jobs so script retries do not create duplicate background work.

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

pnpm generate:agent-artifacts