Log inGet API keyDashboard

api reference

Versioning and deprecation

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

View as Markdown

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 codes 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 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) 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/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 with a free key.

Where changes are announced

  • 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: always matches production