Versioning and deprecation

The API is path-versioned. The version is part of the URL, so an integration that keeps calling the same paths keeps getting the same contract:

https://api.emailvalidator.ai/api/v1/verify

v1 is the current and only version. Nothing in the API is deprecated today.

On this page

• Additive changes ship without a version bump
• What counts as breaking
• Breaking changes ship as a new path version
• The sunset window
• Where changes are announced

Additive changes ship without a version bump

We add to v1 continuously, and those additions do not change the version. An additive change is one that cannot break a client that ignores what it does not recognise:

• a new field in a response body
• a new optional request field or query parameter
• a new endpoint
• a new value in an existing enum (for example a new sub_status)
• a new response header

What this asks of your client: tolerate unknown fields and unknown enum values. Deserialize permissively — do not fail on an unexpected property — and treat an enum value you do not know as "something else" rather than as an error. Most JSON libraries already ignore unknown properties by default; enum handling is the one that usually needs a deliberate fallback branch.

What counts as breaking

These are the changes we will not make to v1:

• removing or renaming a response field
• changing a field's type (for example a number becoming a string)
• removing a value from an enum, or changing what an existing value means
• removing an endpoint, or changing its path or method
• tightening validation so a request that used to be accepted is rejected
• changing a success status code, or the shape of an error body

Two things are deliberately not on that list, because they are operational rather than contractual: rate-limit ceilings, and the exact human-readable error prose in an error body. Branch on the machine-readable code field, never on the message text. See Errors.

Breaking changes ship as a new path version

When a breaking change is necessary it arrives as a new prefix — /api/v2 — served alongside /api/v1. Your existing integration keeps working, unchanged, on the version it already calls.

The retiring version is then marked deprecated in the OpenAPI specification and every one of its responses starts carrying deprecation headers:

Deprecation: Tue, 01 Sep 2026 00:00:00 GMT
Sunset: Mon, 01 Mar 2027 00:00:00 GMT
Link: <https://api.emailvalidator.ai/docs/get-started/versioning>; rel="deprecation"

• Deprecation — when the version became (or becomes) deprecated. A date in the future is an advance notice.
• Sunset — when the version stops answering. This is the date to plan against.
• Link — the migration guide for that version.

Both dates are HTTP-dates (RFC 9110 / IMF-fixdate), the same format as Date, so any HTTP date parser reads them.

The sunset window

A deprecated version keeps serving for at least six months after its Deprecation date before its Sunset. The headers state the exact dates for the version you are calling; six months is the floor, not the plan — a widely used version gets longer.

Practically: log the Sunset header if you see one. A single deployment that surfaces it in your monitoring turns a version retirement from a surprise into a scheduled task.

Where changes are announced

Every change — additive or breaking — is published on the changelog, which is the authoritative record of what the API did and when. Deprecations are announced there on the same day the headers start being sent.