---
title: AgentMailer API versioning and deprecation policy
description: Compatibility, deprecation, and sunset guarantees for AgentMailer API clients.
canonical: https://agentmailer.ai/api-policy.md
last-updated: 2026-09-01
---

# AgentMailer API versioning and deprecation policy

The public REST API is versioned in its URL. The current stable base path is `/v1`. Additive fields and endpoints may be introduced within a stable version; clients must ignore response fields they do not recognize. AgentMailer does not silently repurpose or remove a documented field within the same stable version.

## Deprecation signals

When a public endpoint is deprecated, its response will carry the HTTP `Deprecation` header. Once a removal date is known, it will also carry an RFC 8594 `Sunset` header and a `Link` header with `rel="deprecation"` pointing to migration guidance. The OpenAPI operation will be marked `deprecated: true`.

AgentMailer aims to provide at least 180 days between a public deprecation announcement and removal, except when an urgent security or legal issue makes continued operation unsafe. Authentication failures, plan limits, and abuse controls are not API deprecations.

## Client guidance

Generate clients from https://api.agentmailer.ai/openapi.json, use stable idempotency keys on retried writes, and monitor response headers. Contact support@agentmailer.ai if a migration cannot be completed during the published window.