Versioning

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.

5 min read

Use the Path Version as the Contract Boundary

Mailrith's public API version is part of the path. The current public API contract is under /v1, so include /v1 in every API call.

Path versioning gives your integration a clear contract boundary. If a future release has a breaking change, Mailrith will put that change behind a new versioned path instead of silently changing the version your code already uses.

Do not build clients with unversioned paths such as /subscribers or /api/subscribers. In every environment, use the documented base URL and the documented versioned path.

In production, set your base URL to https://api.mailrith.com/v1.
When you test the worker locally, set your local base URL to http://localhost:8787/v1.
Use the same versioned base URL in REST calls, SDK configuration, generated clients, and agent tools.
Download or load the OpenAPI document for the same API version that your integration calls.
Do not use unversioned paths and /v1 paths in the same integration.
Record the API version in your integration README, runbook, or customer setup notes so future maintainers know which contract the integration uses.

Production API base: https://api.mailrith.com/v1.
Local API base when the worker is running locally: http://localhost:8787/v1.
Use the same versioned path in REST calls, SDK configuration, generated clients, and agent tooling.
Use the OpenAPI document for the API version you call as the source of truth for request and response shapes.

Version Metadata

curl https://api.mailrith.com/v1

Plan Upgrades Deliberately

When Mailrith adds a future API version, handle the upgrade like any other production integration change. Read the new docs, compare the OpenAPI document, update your client in a test environment, and then roll out the change deliberately.

The generated OpenAPI document is machine-readable. Your team can use schema diff tooling in CI before adopting a future API version to catch renamed fields, new required fields, removed enum values, or changed response shapes.

If you use an SDK, update the SDK only after you confirm which public API version the SDK targets. Generated SDKs make calls easier, but the versioned API contract still defines what the server accepts.

Record which API version each integration uses.
Keep one upgrade branch or test environment where you can compare old API behavior with new API behavior.
Run real examples from your integration, not only generated schema checks.
Deploy upgrades gradually when the integration affects subscriber imports, sends, automations, or webhooks.

Download the developer-site copy of the OpenAPI document or call the public GET /v1/openapi.json endpoint directly from your tooling.