> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendpost.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Versioning & Migration

> How the SendPost response contract is versioned, how to migrate from the legacy shape to v1, and the deprecation timeline.

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.

<Note>
  **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.
</Note>

## 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:

```
X-SendPost-Public-Contract: v1
```

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:

| Header                       | Meaning                                                  |
| ---------------------------- | -------------------------------------------------------- |
| `X-SendPost-Public-Contract` | the contract applied to this response — `legacy` or `v1` |
| `Deprecation`                | `true` while `legacy` is still served by default         |
| `Sunset`                     | the date after which **`v1` becomes the default**        |
| `Link`                       | a link to this migration guide (`rel="deprecation"`)     |

## Timeline

<Warning>
  **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.
</Warning>

* **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).

<Info>
  The request body format is unchanged. Versioning applies to **response** shapes only.
</Info>

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](/api-reference/changelog).

## How to migrate

<Steps>
  <Step title="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.

    ```bash theme={null}
    curl https://api.sendpost.io/api/v1/subaccount/suppression \
      -H "X-SubAccount-ApiKey: YOUR_API_KEY" \
      -H "X-SendPost-Public-Contract: v1"
    ```
  </Step>

  <Step title="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](/api-reference/changelog) lists every change per resource.
  </Step>

  <Step title="Verify against the API Reference">
    Confirm your parsing matches the `v1` schemas documented on each endpoint page.
  </Step>

  <Step title="Pin v1 in production">
    Send `X-SendPost-Public-Contract: v1` on all production requests, and watch the `Deprecation` / `Sunset` headers to track the timeline.
  </Step>
</Steps>

## Questions

Reach us at [dev@sendpost.io](mailto:dev@sendpost.io) if you need help planning your migration.