Versioning

Agent Mail uses URI versioning: every path is prefixed /v1, and the version number is the only compatibility signal — there is no Accept header negotiation and no per-field opt-in.

Before general availability

Until Agent Mail reaches general availability, /v1 may still change in ways that are not strictly additive, because there are no external integrations depending on it beyond the ones Ackuna is actively working with. Any such change is announced to affected organizations directly.

At general availability

The day Agent Mail reaches general availability, /v1 is frozen and additive-only. From that point on, within /v1:

• New endpoints, new optional request fields, and new response fields may be added at any time without notice.
• New values may be added to open-ended enumerations (for example, a new webhook event_types entry) without notice — treat unknown values as "ignore or fall back", never as an error.
• Existing fields never change type or meaning, existing endpoints never change their required parameters, and nothing that currently returns a value stops returning it.

Breaking changes go to /v2

Anything that would break an existing integration — removing a field, changing a field's type or semantics, tightening a validation rule, changing an error code for an existing failure — ships as /v2 instead of altering /v1 in place. /v1 keeps working unchanged alongside it; there is no forced migration deadline announced as part of this policy.

What this means for an integration

Read fields you use by name and ignore fields you do not recognize; do not assume a response object is exhaustively described by what you saw in testing. Treat every string enum (status, direction, event_types, error code) as open-ended unless Errors states otherwise for that specific field. This is the same posture the OpenAPI description and every page in this tree are written to support.