# Mailrith Developer Documentation

> Developer guidance for Mailrith's public API, OpenAPI contract, official SDKs, remote MCP server, and AI-agent discovery flow.

Use these guides when building integrations or agent tools. Use OpenAPI for exact schemas and authenticated capabilities for workspace-specific permissions.

## Developer Categories
- [Getting Started](https://mailrith.com/developers/category/getting-started.md): Create workspace keys, make your first authenticated request, and test the public API locally. Includes 7 guides.
- [API Concepts](https://mailrith.com/developers/category/api-concepts.md): Learn how pagination, errors, idempotency, and versioning work before you wire Mailrith into a sync flow. Includes 4 guides.
- [API Resources](https://mailrith.com/developers/category/resources.md): Work with subscribers, tags, custom fields, forms, landing pages, segments, and asynchronous import or export jobs. Includes 13 guides.
- [API Reference](https://mailrith.com/developers/category/reference.md): Browse the generated endpoint reference and download the machine-readable OpenAPI contract. Includes 1 guides.

## Developer Guides
- [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.
- [Authentication](https://mailrith.com/developers/authentication.md): Every protected `v1` request resolves through a workspace-scoped API key. This page covers the header shape, workspace scoping behavior, and authentication failure handling.
- [Testing the API](https://mailrith.com/developers/testing-the-api.md): Mailrith's public API can be tested manually with local curl requests and automatically through the integration suite. This page shows the repo-native commands for both paths.
- [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.
- [SDKs](https://mailrith.com/developers/sdks.md): Mailrith ships official TypeScript and Python SDKs generated from the same public contract that drives the OpenAPI document and capability map.
- [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.
- [Zapier](https://mailrith.com/developers/zapier.md): Mailrith's Zapier package maps the public API into OAuth authentication, instant REST Hook triggers, Kit-style subscriber actions, raw authenticated API requests, and subscriber search. This page explains the code shape, local validation, and publish process.
- [Pagination](https://mailrith.com/developers/pagination.md): Mailrith uses cursor pagination across list endpoints. This guide explains how to request the first page, continue with `next_cursor`, resume interrupted syncs, and reuse the same pattern across subscribers, tags, custom fields, forms, and segments.
- [Errors](https://mailrith.com/developers/errors.md): Non-2xx responses carry stable error codes and plain-language messages. This guide explains how to log errors, avoid message matching, map status codes to user or system actions, and retry only when the same request may succeed later.
- [Idempotency](https://mailrith.com/developers/idempotency.md): Import and export job creation endpoints accept idempotency keys so network retries do not queue duplicate work. This guide explains when to use a key, how to choose one, and how to store it with your own job record.
- [Versioning](https://mailrith.com/developers/versioning.md): Mailrith versions the public API in the path. This guide explains the `/v1` contract boundary, which base URLs to call, how to avoid unversioned paths, and how to compare future API versions before upgrading.
- [Subscribers API](https://mailrith.com/developers/subscribers.md): The subscribers resource is the core subscriber write surface in `v1`. This guide explains when to list, when to upsert, how Mailrith chooses the workspace, what to include in an upsert body, and when to use async imports instead of many single requests.
- [Tags API](https://mailrith.com/developers/tags.md): The tags surface gives integrations a lightweight way to manage subscriber labels. This guide explains when tags are the right choice, when custom fields are better, how to list or create tags, and how to name tags so real workspace users understand them.
- [Custom Fields API](https://mailrith.com/developers/custom-fields.md): Custom fields define the typed workspace schema shared by subscribers, forms, and segments. This guide explains how to choose field types, map external data, create definitions, and avoid breaking forms or reports with unsafe schema changes.
- [Forms API](https://mailrith.com/developers/forms.md): The forms surface lets integrations manage capture points outside the app. This guide explains when to list, create, update, or delete forms, how forms depend on fields and tags, and how to change live forms without breaking website signups.
- [Landing Pages API](https://mailrith.com/developers/landing-pages.md): The landing pages surface lets integrations manage hosted capture pages outside the app. This guide explains when to list, create, update, or delete landing pages, how page definitions depend on tags and fields, and how to change public pages safely.
- [Broadcasts API](https://mailrith.com/developers/broadcasts.md): The broadcasts resource is the public campaign control plane for one-off messages. This guide explains draft management, test sends, live-send safety, and why send actions should be treated as high-impact operations in integrations and agents.
- [Email Templates API](https://mailrith.com/developers/email-templates.md): The email templates resource supports migration, governance, and external template sync. This guide explains when to use templates, how to preserve structured editor content, and how to keep template names and descriptions useful for workspace users.
- [Sequences API](https://mailrith.com/developers/sequences.md): The sequences resource lets external systems prepare, migrate, or synchronize time-based email series. This guide explains how to think about sequence definitions, when to update or delete them, and what to check before migrated journeys reach real subscribers.
- [Automations API](https://mailrith.com/developers/automations.md): The automations resource exposes Mailrith workflow definitions for tools that create or synchronize automations outside the app. This guide explains what automations can affect, how to use the public schema, and what to review before trusting a generated workflow.
- [Magic Links API](https://mailrith.com/developers/magic-links.md): The magic links resource lets external tools create and maintain subscriber action links. This guide explains where to use magic links, how to align actions with destinations, and how to test links before live campaigns.
- [Segments API](https://mailrith.com/developers/segments.md): The segments surface supports saved subscriber definitions, imported subscriber rules, and previews for unsaved logic. This guide explains how segments behave, when to save them, and why preview is the safest step before using complex subscriber rules.
- [Import and Export Jobs](https://mailrith.com/developers/jobs.md): Imports and exports are asynchronous in `v1`. This guide explains when to queue a job, how import mappings and export filters work at a high level, how to use idempotency, and how to monitor final results without confusing queued work with completed work.
- [Webhook Subscriptions API](https://mailrith.com/developers/webhook-subscriptions.md): Webhook subscriptions let external systems receive Mailrith events for syncs, dashboards, fulfillment, and audit trails. This guide explains when to use webhooks, how to manage subscriptions, why the signing secret must be stored immediately, and how receivers should verify and deduplicate deliveries.
- [API Reference](https://mailrith.com/developers/api-reference.md): The full API reference is generated from the same public contract used by the API worker and SDK tooling. Use it for exact paths, methods, parameters, request schemas, response schemas, operation IDs, and the downloadable OpenAPI document.