Current public contract

Errors

Use the HTTP status and JSON error envelope together. Error details vary by operation; the OpenAPI response table is authoritative.

Error envelope

Representative error shapeJSON

{
  "error": {
    "code": "agent_scope_denied",
    "message": "Agent credential is not authorized."
  }
}

Select the snippet to copy it manually. Copy buttons appear when browser scripting is available.

Send exception: POST /outbox/send can return 503 with an OutboundReceipt instead of the error envelope when the command state is outcome_unknown. Inspect the response body before classifying the failure.

Statuses in the current schema

Status	Documented meanings
`200`	Company address, counts, and caller capabilities; triage is true for an admitted company member. {entries,next_cursor,retention_days} with bounded owner-mail search semantics. Retention days has incoming and owner fields. {entry}, with body_text, body_state, html_omitted, and attachment_bytes_omitted inside entry.
`202`	{command} durable send receipt.
`400`	Invalid folder, filter, or cursor. Invalid triage fields. Invalid mail request.
`401`	Credential denied or expired. Owner authentication required. Bearer authentication is missing, malformed, expired, or otherwise denied.
`403`	Current membership or inbox:read denied. This mailbox is not owned by the caller. The Agent credential is for another inbox, lacks `inbox:read`, or the caller is not the owner.
`404`	Company mailbox disabled. Message not found in the company partition. Mail item not found.
`409`	Draft revision or idempotency conflict. The idempotency key was already used with a different payload.
`413`	The JSON request exceeds the endpoint limit. The request or outbound text exceeds its size limit.
`429`	Daily external send limit reached. The per-inbox daily outbound attempt limit is reached.
`503`	Current organization projection unavailable or invalid. Projection or encrypted message unavailable. Encrypted mail or provider unavailable.
`507`	Mailbox storage or search work capacity reached. The retained outbound-command capacity is reached.

Retry discipline

Correct authentication, scope, route, or input errors before retrying.
Retry read-only operations with backoff after a transient network failure or qualifying 503.
Honor 429; do not loop or create a new idempotency key to bypass a retained send.
Persist the exact outbound payload and key before sending. If the response is lost, reconcile that key first.
An outcome_unknown receipt means the mail may have been sent. Keep the same key and never issue a speculative replacement send.

Need the earlier hosted reference? Open the previous public API docs .