API versioning

Date-based versioning: pin your version and upgrade on your own schedule, with a clear deprecation policy.

SendIt uses date-based versioning. When you create your account, your organization is pinned to the current version. Nothing breaks on its own: you decide when to adopt changes.

Current version

2026-05-01

Pin a version

Three mechanisms, in priority order:

1. Request header (highest priority, ideal for testing)

SendIt-Version: 2026-05-01

Useful for verifying your code against a new version before permanently upgrading.

2. API key pin

curl -X PATCH https://api.sendit.mx/v1/api-keys/{id} \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "apiVersion": "2026-05-01" }'

Requests on that key always use the specified version, overriding the organization pin.

3. Organization pin (default)

curl -X PUT https://api.sendit.mx/v1/organizations/me \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "apiVersion": "2026-05-01" }'

Every key without its own pin inherits this version.

Upgrade without surprises

Test the new version with the SendIt-Version header in your staging environment.
Adjust your code for the documented breaking changes.
Update your organization pin (or individual key pins) once everything is verified.

Deprecation policy

Timeline	What happens
6 months before	The `SendIt-Version-Deprecated` header is added to every response
1 month before	Email notification to the organization’s OWNERs
After sunset	Requests return `400 API_VERSION_UNSUPPORTED`

Every version is supported for at least 18 months.

What requires a new version

New versions are rare. Only a breaking change requires one:

Renaming or removing response fields
Changing a field’s type (e.g. string → object)
Removing enum values
Changing required request fields
Changing default behavior

Adding fields, endpoints, optional parameters, or event types does not require a new version. Your integration must tolerate unknown fields.

Webhook payloads carry no version field, and webhook endpoints are not pinned to a version of their own. There is one API version today, so every event has the same shape across all your endpoints. Your handler does not need to branch on version.