# SDKs



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



- Human page: https://mailrith.com/developers/sdks

- Markdown page: https://mailrith.com/developers/sdks.md

- Category: Getting Started

- Reading time: 6 min read

- Last updated: 2026-07-13

- Related keywords: SDKs, SDKs developer docs, Getting Started, Getting Started developer docs, Mailrith developer docs, Mailrith public API, TypeScript SDK, Python SDK, Generated From the Public Contract, Agents, MCP Server, Quickstart



## AI Agent Notes

- Use this page as implementation guidance, then validate exact endpoint fields against the OpenAPI document.

- Keep API keys server-side and workspace-scoped unless a guide explicitly says otherwise.

- Do not invent privacy, consent, or lawful-basis evidence. Send only fields that appear in the OpenAPI schema for the endpoint you are using.



## What this guide covers

Use the official TypeScript and Python SDKs generated from Mailrith's public contract.



## TypeScript SDK

Use the TypeScript SDK when your integration runs in Node.js, a serverless runtime, or an edge runtime with `fetch`. The SDK wraps the public API into resource namespaces such as `client.subscribers`, `client.broadcasts`, and `client.webhookSubscriptions`.

The SDK does not replace the need to understand Mailrith concepts. It uses the same workspace-scoped credentials, request bodies, pagination rules, error envelopes, and idempotency behavior described in these docs.

Create one client for each workspace API key. If a service talks to several Mailrith workspaces, keep those clients clearly separated so subscriber data and other workspace records cannot cross from one workspace to another.

1. Create a workspace API key by following [Quickstart](https://mailrith.com/developers/quickstart.md).
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](https://mailrith.com/developers/errors.md).

- 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.

**Install and Call Mailrith from TypeScript**

```ts
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

Use the Python SDK for migration scripts, scheduled sync jobs, data pipelines, and backend services written in Python. The SDK exposes Python-friendly resource namespaces and method names while still calling the same public `/v1` API.

The SDK uses a standard-library transport by default, so it works well for simple scripts and controlled automation environments without another HTTP client dependency.

Store the API key outside the script. Use a local `.env`, CI secret, cloud secret manager, or container environment variable instead of hard-coding the key.

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](https://mailrith.com/developers/pagination.md).
7. For import or export jobs, send an idempotency key as explained in [Idempotency](https://mailrith.com/developers/idempotency.md).

- 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.

**Install and Call Mailrith from Python**

```py
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. This keeps SDK method names, schemas, operation metadata, and the served OpenAPI document aligned.

When the public contract changes in the repo, regenerate the shared SDK artifacts before you publish packages or rely on new operations in docs and examples.

Generated SDKs make common workflows easier, but the OpenAPI document remains the source of truth for exact request and response shapes.

**Regenerate SDK Artifacts From the Public Contract**

```bash
pnpm generate:agent-artifacts
```



## Related Guides

- [Agents](https://mailrith.com/developers/agents.md): Mailrith exposes a compact discovery stack for AI agents: llms files on the marketing site, version metadata on the API root, the versioned OpenAPI contract, authenticated capability discovery, and official SDK and MCP entry points after a workspace key is available.

- [MCP Server](https://mailrith.com/developers/mcp.md): Mailrith's official MCP server is the highest-level interface for agent runtimes. This page covers the remote endpoint and includes copy-paste examples for OpenAI, Claude, n8n, and Pipedream.

- [Quickstart](https://mailrith.com/developers/quickstart.md): Start with one workspace API key, one authenticated request, and the generated response envelope. This page covers the minimum steps needed to create a working subscriber sync.