Learn
Versioning
The version is part of the URL, and a version that is going away tells you so in its own response headers.
The current version
v1 is current and is the only supported version. Pin your integration to an explicit version in the path; there is no unversioned alias, and there will not be one.
The policy
When a new major version ships, the previous one keeps working alongside it. Withdrawal is announced at least 183 days in advance, and every account whose key called the outgoing version in the previous 90 days is emailed directly.
183 days of notice is a floor, not a target. It exists so that an integration nobody has touched in a year still has two calendar quarters to react after the first email lands.
What counts as a breaking change
Breaking changes require a new version. Everything else ships into the current one, which is why your client has to tolerate additions.
Requires a version bump
- Removing or renaming a response field
- Tightening validation on an existing parameter
- Changing which error code a condition returns
Ships without a bump
- Adding an optional request or response field
- Adding a value to an existing enum
- Adding a new endpoint
Two obligations on your client
Ignore fields you do not recognise rather than rejecting the response, and handle unknown enum values with a default branch rather than throwing. SMSend relies on both when shipping non-breaking changes — a client that crashes on a new status value will break on a day nothing was announced.
Deprecation headers
While a version is on its way out, every response it serves carries the date it was deprecated, the date it will stop working, and a link to the notice.
These headers never appear on the current version. Stamping them on a version that is not going anywhere would train every client to ignore them, which is exactly what you do not want on the day they matter.
Calling a version that does not exist
A request to a version that is not supported returns 400 with UNSUPPORTED_VERSION and the list of versions that do work — never a bare 404. A 404 reads as "you have the URL wrong" and sends people looking for a typo instead of at the deprecation notice they missed.