# SDKs



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



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

- Category: Getting Started

- Reading time: 6 min read



## 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 is written 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 remove the need to understand Mailrith concepts. It still 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 data 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 building 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 adding 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 rotating 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. It 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, which makes it suitable for simple scripts and controlled automation environments without adding another HTTP client dependency.

Store the API key outside the script. A local `.env`, CI secret, cloud secret manager, or container environment variable is safer than 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 authentication and 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 publishing packages or relying on new operations in docs and examples.

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

**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 once 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 plus 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 needed to go from zero to a working subscriber sync.