Skip to main content
SendPost is introducing a versioned response contract for the public REST API. This page explains what is changing, how to opt in, and the timeline.
Nothing changes for your integration today. The legacy response shape stays the default until the sunset date below, so existing integrations keep working unchanged. You migrate to v1 on your own schedule.

​
The two contracts

  • legacy (default) — the exact response shape SendPost returns today. Requests that do not opt in keep receiving this until the sunset date.
  • v1 — the new, normalized public contract: consistent camelCase field names, internal-only fields removed, and a few additive fields.
Select the contract per request with a header:
Omit the header (or send legacy) to keep today’s shape. The header works on every public /api/v1/... endpoint.

​
Deprecation headers

Every response advertises the contract state so your client and SDKs can track the migration:

​
Timeline

Sunset: 31 March 2027, 23:59:59 UTC. After this date, requests that do not send X-SendPost-Public-Contract receive the v1 shape by default. Migrate your integration and pin v1 before then.
  • Now → sunset — legacy is the default. Opt into v1 any time with the header.
  • After sunset — v1 becomes the default. Sending X-SendPost-Public-Contract: v1 explicitly is still recommended so your integration is pinned and unaffected by future defaults.

​
What changes in v1

v1 normalizes the public response shape. The changes fall into three categories:
  1. Consistent camelCase. Several fields used non-standard casing; v1 normalizes them. Examples:
    • IP / message / event: publicIP → publicIp, messageID → messageId, eventID → eventId
    • Provider stats: email_type → emailType
    (Suppression’s smtpError is already camelCase and is not renamed.)
  2. Internal fields removed. Fields that were never part of the public contract — internal identifiers, infrastructure details, and any sensitive values — are not returned in v1.
  3. Additive fields. v1 surfaces new public fields, for example reasonText (suppression), dnsProvider (domain), and autoWarmupEnabled (IP).
The request body format is unchanged. Versioning applies to response shapes only.
The schemas shown on each endpoint page in this API Reference are the v1 contract. Use them as the source of truth for the exact response of every endpoint under v1. For the complete field-by-field diff of every resource — added, renamed, and removed fields — see the Changelog.

​
How to migrate

1

Opt in on a test integration

Add X-SendPost-Public-Contract: v1 to your requests in a staging or test environment and inspect the responses.
2

Update field names and parsing

Adjust for the camelCase renames (e.g. publicIP → publicIp, messageID → messageId) and remove any code that depended on internal fields v1 no longer returns. The Changelog lists every change per resource.
3

Verify against the API Reference

Confirm your parsing matches the v1 schemas documented on each endpoint page.
4

Pin v1 in production

Send X-SendPost-Public-Contract: v1 on all production requests, and watch the Deprecation / Sunset headers to track the timeline.

​
Questions

Reach us at dev@sendpost.io if you need help planning your migration.