# 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, send your first authenticated request, and test the public API in your local environment. Includes 7 guides.
- [API Concepts](https://mailrith.com/developers/category/api-concepts.md): Learn how pagination, errors, idempotency, and versioning work before you connect Mailrith to a sync flow. Includes 5 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 steps needed to create a working subscriber sync.
- [Authentication](https://mailrith.com/developers/authentication.md): Every protected `v1` request is authorized through a workspace-scoped API key. This page covers the required header shape, workspace scoping behavior, and authentication failure handling.
- [Testing the API](https://mailrith.com/developers/testing-the-api.md): You can test Mailrith's public API manually with local curl requests or automatically with the integration suite. This page shows the repo-native commands for both testing 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 after 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 powers 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 and includes 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 structure, local validation, and publishing 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 pagination pattern across subscribers, tags, custom fields, forms, and segments.
- [Errors](https://mailrith.com/developers/errors.md): Non-2xx responses include stable error codes and plain-language messages. This guide explains how to log errors, avoid matching on message text, 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 the key 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 you upgrade.
- [Consent And Privacy API Boundaries](https://mailrith.com/developers/consent-and-lawful-basis.md): The public Subscriber API stores profile and list-management data, not separate consent-evidence fields. This guide explains the API boundary, safe Subscriber upserts, imports, webhooks, and when to use Mailrith-hosted GDPR consent workflows.
- [Subscribers API](https://mailrith.com/developers/subscribers.md): The subscribers resource is the main way integrations write Subscriber data in `v1`. This guide explains when to list subscribers, when to upsert subscribers, 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 API gives integrations a lightweight way to manage subscriber labels. This guide explains when to use tags, when to use custom fields instead, how to list or create tags, and how to name tags so workspace users understand each label.
- [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 sources, create field definitions, and avoid schema changes that break forms or reports.
- [Forms API](https://mailrith.com/developers/forms.md): The forms API lets integrations manage capture forms outside the app. This guide explains when to list, create, update, or delete forms, how forms depend on fields and tags, and how to update live forms without breaking website signups.
- [Landing Pages API](https://mailrith.com/developers/landing-pages.md): The landing pages API 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 update 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 integrations and agents should treat send actions as high-impact operations.
- [Email Templates API](https://mailrith.com/developers/email-templates.md): The email templates resource supports migrations, 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 plan sequence definitions, when to update or delete sequences, 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 you trust 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 match each action with the correct destination, and how to test links before live campaigns.
- [Segments API](https://mailrith.com/developers/segments.md): The segments API supports saved segment definitions, imported subscriber rules, and previews for unsaved logic. This guide explains how segments behave, when to save segments, 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 job status 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 you must store the signing secret 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 the API reference to find exact paths, methods, parameters, request schemas, response schemas, operation IDs, and the downloadable OpenAPI document.