# Versioning and deprecation

> How the isBusinessEmail API is versioned, which changes are non-breaking, and how deprecations are announced with Deprecation and Sunset headers.

Source: https://isbusinessemail.com/docs/changelog-policy

## Versioning

The API version is in the path: `/v1/…`. Within a major version we don't make breaking changes.

### Non-breaking (can happen any time in `/v1`)

- New optional request fields and query parameters
- New response fields
- New values in open sets: `reasons` codes, `mail.provider`, `workspace.other_suite`, `identity_provider`, evidence tags
- New endpoints
- New error `code`s for new situations
- Better verdicts: list updates, engine improvements and re-tuned confidence

Write clients that **ignore unknown fields** and treat unknown reason codes as informational.

### Breaking (only in a new major version)

- Removing or renaming a field, endpoint or parameter
- Changing a field's type or meaning
- Adding a new `category` or `recommendation` value
- Changing the default `policy`

## Verdicts change; the contract doesn't

The engine improves continuously: lists refresh nightly, reviewed domains get overrides, and DNS signals are re-weighted against our evaluation set. The same domain can therefore get a different `category` or `confidence` next month. That's an improvement, not a contract change. If you depend on a stable decision for a user, store the verdict you acted on.

## Deprecation process

When something in `/v1` is going away (usually because `/v2` replaces it):

1. **Announcement** on the [changelog](https://isbusinessemail.com/changelog) and by email to account owners whose keys used the feature in the last 90 days.
2. **`Deprecation` header** on affected responses from the day of the announcement.
3. **`Sunset` header** ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) with the removal date, plus a `Link` to the migration guide.
4. **At least 6 months** between announcement and removal for anything with active usage.
5. After the sunset date the endpoint returns `410 Gone` with a link to the docs.

```http
HTTP/1.1 200 OK
Deprecation: @1798761600
Sunset: Sat, 01 Jan 2028 00:00:00 GMT
Link: <https://isbusinessemail.com/docs/changelog-policy>; rel="deprecation"
```

Watch for these headers in your logs or monitoring; they're the earliest warning you'll get.

## The legacy `/api/check`

The original prototype endpoint, `isbusinessemail.com/api/check`, had no authentication and no limits. It now returns `410 Gone` with a link to these docs. Move to [`/v1/check`](https://isbusinessemail.com/docs/check-endpoint) with a [free key](https://isbusinessemail.com/signup).

## Where changes are announced

- [Changelog](https://isbusinessemail.com/changelog): every API, engine and docs change worth knowing
- Email to account owners: deprecations, material changes to the Terms or Privacy Policy (30 days ahead), and security notices
- [`/openapi.json`](https://api.isbusinessemail.com/openapi.json): always matches production