# API Reference



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



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

- Category: API Reference

- Reading time: 8 min read



## 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 endpoint documentation aligned with the versioned `/v1` surface.

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

The narrative guides explain how to think about each feature. The reference gives you the exact contract to 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 sending them to Mailrith.
6. Use response schemas to decide what your integration stores.
7. After implementation, test one small request in Mailrith and verify the result in the user-facing docs workflow when possible.

- 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 in doubt, trust the OpenAPI document for field names and data shapes.



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