# API Reference



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



- Human page: https://mailrith.com/developers/api-reference

- Markdown page: https://mailrith.com/developers/api-reference.md

- Category: API Reference

- Reading time: 8 min read

- Last updated: 2026-07-13

- Related keywords: API Reference, API Reference developer docs, Mailrith developer docs, Mailrith public API, Generated Reference, Quickstart, Authentication, Testing the API



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

Browse generated endpoint details and download the exact OpenAPI contract for tooling.



## Generated Reference

The API reference is generated from the same public contract used by the API worker, SDK generation, and the downloadable OpenAPI document. This keeps the endpoint documentation aligned with the versioned `/v1` API.

Use the reference when you need exact paths, HTTP methods, operation IDs, request fields, response fields, parameters, and schemas.

The narrative guides explain how each feature works. The reference gives you the exact contract your integration must implement against.

1. Start with the narrative guide for the feature you are building, such as [Subscribers API](https://mailrith.com/developers/subscribers.md), [Broadcasts API](https://mailrith.com/developers/broadcasts.md), or [Import and Export Jobs](https://mailrith.com/developers/jobs.md).
2. Open [API Reference](https://mailrith.com/developers/api-reference.md) when you need exact paths, methods, operation IDs, parameters, or schemas.
3. Download `mailrith-openapi-v1.json` if your tooling needs a local copy.
4. Generate or update client code from the same OpenAPI version your service calls.
5. Use request schemas to validate payloads before you send them to Mailrith.
6. Use response schemas to decide which API response fields your integration stores.
7. After implementation, send one small request to Mailrith. When possible, verify that the API response matches the expected user-facing workflow in the docs.

- Use operation IDs when building generated clients or agent tools.
- Use request body schemas when validating payloads before sending them to Mailrith.
- Use response schemas when deciding what your integration stores.
- Download `mailrith-openapi-v1.json` when your tooling needs a local copy of the schema.
- When field names or data shapes are unclear, use the OpenAPI document as the source of truth.



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