Limits & errors

Request limits

Every plan is eligible when integrations are enabled. Existing account storage, sending, and resource limits continue to apply.

Inspect rate-limit headers and honor Retry-After on a 429 response. Use IMAP for reading messages larger than 10 MiB.

Cursor pagination

Resource lists return an opaque next_cursor. Pass that exact value as the next request’s cursor query parameter. Do not decode or construct cursors yourself.

Message lists use numeric nextCursor and return uidValidity. Keep both values when continuing a message listing. The default page size is 25, with a maximum of 100.

Make retries safe

Mutation requests require an Idempotency-Key: 8–128 letters, digits, underscores, periods, or hyphens. Use a different key for each intentional action; repeat the same key with an identical request after an interruption.

Idempotency-Key: order-confirmation-1042

Reusing a key with different input returns a conflict. Creation and change responses include a durable operation ID for progress checks.

Preserve message identity

A message reference combines mailbox ID, folder, uidValidity, and uid. Preserve all four. A stale reference returns 409; list the folder again rather than reusing the UID against a changed mailbox state.

Message deletion moves email to Trash by default. Permanent deletion requires permanent: true. Use the deletion endpoint to move to Trash; the move endpoint cannot bypass deletion permissions.

Handle errors consistently

{
  "error": {
    "code": "forbidden",
    "message": "Insufficient permission.",
    "request_id": "example-request-id"
  }
}

Include error.request_id when contacting support. An uncertain send result must be treated as potentially accepted.