Versioning and deprecation
The API version is part of the URL: https://shipmail.to/api/v1. Code written against v1 keeps working. Nothing is removed or changed in a way that breaks it without at least 12 months of notice.
Last updated
Changes that ship without notice
These changes are compatible with existing code, so v1 gets them at any time:
- New endpoints and new API key scopes.
- New optional request parameters and fields.
- New fields in responses and in webhook payloads.
- New webhook event types, new error codes and new values in enum fields.
- Longer or differently formatted IDs and cursors. Treat them as opaque strings.
Write clients that ignore fields they do not know and handle enum values they do not know.
Breaking changes
A breaking change removes or renames an endpoint or a field, changes the type or meaning of a field, makes an optional parameter required, or asks for a different scope. A breaking change ships only in a new version, such as /api/v2, or after the deprecation process below. The same rules apply to webhook payloads, the SDKs, the CLI and the MCP tools.
How a deprecation works
- The deprecation is announced in the changelog and on this page, with what replaces the feature.
- Responses from a deprecated endpoint carry the headers below until it is removed.
- The feature keeps working for at least 12 months after the announcement. When a new version replaces an old one, the old version also keeps working for at least 12 months.
A security problem or a legal requirement can force a shorter notice. Then the announcement says why.
Deprecation headers
| Header | Example | Meaning |
|---|---|---|
Deprecation | Deprecation: @1798761600 | The date the feature was deprecated, as a Unix timestamp (RFC 9745). |
Sunset | Sunset: Fri, 01 Oct 2027 00:00:00 GMT | The earliest date the feature can stop working (RFC 8594). |
Link | Link: <https://shipmail.to/docs/api/versioning>; rel="deprecation" | This page, which says what replaces the feature. |
Log a warning when a response carries Deprecation, so you find out before the Sunset date.
Current deprecations
| Feature | Use instead | Announced | Earliest removal |
|---|---|---|---|
| Setting a primary mailbox password with mailboxes:write alone, for API keys created before 2026-09-29 | mailbox_credentials:write | 2026-09-29 | 2027-09-29 |