API Reference

Create a new agent organization with an inbox and API key. This endpoint is for signing up for the first time. If you've already signed up, you're all set — just use your existing API key. A 6-digit OTP is sent to the human's email for verification. `human_email` is optional. Without it, the inbox can receive email but cannot send to anyone until a human is attached with the attach human endpoint or, for a US-region inbox, claims it in the AgentMail Console with the API key (see [How do I claim my agent's inbox?](https://docs.agentmail.to/knowledge-base/claiming-agent-inbox)). There is also no way to recover the API key, so store it durably. Calling sign-up again without `human_email` creates a new organization, which needs a different `username`: the original username stays with the lost organization's inbox. This endpoint is idempotent. Calling it again with the same `human_email` will rotate the API key and resend the OTP if expired. The returned API key has limited permissions until the organization is verified via the verify endpoint. **CLI:** ```bash agentmail agent sign-up --human-email user@example.com --username my-agent ```

Attach a human to an unverified agent organization. A 6-digit OTP is sent to the human's email, which you then submit to the verify endpoint. Use it after signing up without a `human_email`. Once the human is attached, the organization can send email to that human only, and verification lifts the remaining restrictions. For up to 5 minutes after attaching, sends to the human can still be rejected with a `429` daily send limit error while the API key's cached limits catch up. Wait and retry. Calling it again with the same `human_email` does not rotate the API key. It resends the OTP if it was never delivered, or issues a new one if it expired. While the current OTP is still valid, calling it again keeps that OTP and its attempt count. If all 10 attempts are used up, wait until the OTP expires, 24 hours after it was issued, then call it again for a new one. Calling it with a different `human_email` replaces the attached human and sends the new human an OTP. An organization can replace its human at most 2 times. Only available until the organization is verified. **CLI:** ```bash agentmail agent attach-human --human-email user@example.com ```

Verify an agent organization using the 6-digit OTP sent to the human's email during sign-up. On success, the organization is upgraded from `agent_unverified` to `agent_verified`, the send allowlist is removed, and free plan entitlements are applied. The OTP expires after 24 hours and allows a maximum of 10 attempts. If the OTP expired, call the attach human endpoint with the same `human_email` to get a new one without rotating the API key. Once all 10 attempts are used, even the correct OTP is rejected, and attach human keeps returning the same OTP until it expires, so wait for it to expire before asking for a new one. An organization that signed up without a `human_email` has no OTP until a human is attached. If you run into any difficulties receiving the OTP code, you can also create an account on [console.agentmail.to](https://console.agentmail.to) using the human email address you provided to verify your account. **CLI:** ```bash agentmail agent verify --otp-code 123456 ```

**CLI:** ```bash agentmail inboxes list ```

**CLI:** ```bash agentmail inboxes create --display-name "My Agent" --username myagent --domain agentmail.to ```

Searches inboxes in the organization by address or display name, ranked by relevance. Each word in the query matches the start of a word in the address or display name, so `sup` matches `support@example.com` but `port` does not. An exact address match always ranks first. `limit` cannot exceed 100. A page can be empty and still carry a `next_page_token`; keep paging until the token is absent.

**CLI:** ```bash agentmail inboxes get --inbox-id <inbox_id> ```

**CLI:** ```bash agentmail inboxes update --inbox-id <inbox_id> --display-name "Updated Name" ``` To pause an inbox, set `status` to `paused`; set it back to `active` to resume. See [Pausing an inbox](/inboxes#pausing-an-inbox).

**CLI:** ```bash agentmail inboxes delete --inbox-id <inbox_id> ```

Authorizes the AgentID sign-in a client is already waiting in, for the inbox in the path, and returns the ID of the pending public key it will activate. Read the key with Get API Key. A repeat for the same token, inbox, and bearer returns the same key ID. A `403` `AppSignupLimitError` means the app accepts no more sign-ups from your organization.

Lists threads in the inbox, most recent first. Pass `senders`, `recipients`, or `subject` to filter by substring. Filtered requests are served by search, which caps `limit` at 100. For relevance-ranked full-text search, use `Search Threads`. **CLI:** ```bash agentmail inboxes threads list --inbox-id <inbox_id> ```

Full-text search across threads in the inbox, ranked by relevance. The query is matched against senders, recipients, and subject (substring) and the message body (tokenized full text). Spam, trash, blocked, and unauthenticated threads are always excluded. `limit` cannot exceed 100.

**CLI:** ```bash agentmail inboxes threads get --inbox-id <inbox_id> --thread-id <thread_id> ```

Updates thread labels. Cannot add or remove system labels (sent, received, bounced, etc.). Rejects requests with a `422` for threads with 100 or more messages.

Permanently deletes a thread and all of its messages. **CLI:** ```bash agentmail inboxes threads delete --inbox-id <inbox_id> --thread-id <thread_id> ```

**CLI:** ```bash agentmail inboxes threads get-attachment --inbox-id <inbox_id> --thread-id <thread_id> --attachment-id <attachment_id> ```

Lists messages in the inbox, most recent first. Pass `from`, `to`, or `subject` to filter by substring. Filtered requests are served by search, which caps `limit` at 100. For relevance-ranked full-text search across sender, recipients, subject, and message body, use `Search Messages`. **CLI:** ```bash agentmail inboxes messages list --inbox-id <inbox_id> ```

Full-text search across messages in the inbox, ranked by relevance. The query is matched against the sender, recipients, and subject (substring) and the message body (tokenized full text). Spam, trash, blocked, and unauthenticated messages are always excluded. `limit` cannot exceed 100.

**CLI:** ```bash agentmail inboxes messages get --inbox-id <inbox_id> --message-id <message_id> ```

**CLI:** ```bash agentmail inboxes messages update --inbox-id <inbox_id> --message-id <message_id> --add-labels read --remove-labels unread ```

Permanently deletes a message. **CLI:** ```bash agentmail inboxes messages delete --inbox-id <inbox_id> --message-id <message_id> ```

Fetch metadata for up to 500 messages in one request. Missing or restricted IDs are silently omitted; compare `count` against `limit` to detect misses. **CLI:** ```bash agentmail inboxes messages batch-get --inbox-id <inbox_id> --message-ids <id1> --message-ids <id2> ```

Apply one label change to up to 50 messages in a single request. The same add_labels and remove_labels apply to every message id, and at least one of them must be provided. The update is atomic: either all resolved messages are updated or none are. Missing or restricted ids are silently excluded; compare `count` against `limit` to detect exclusions. **CLI:** ```bash agentmail inboxes messages batch-update --inbox-id <inbox_id> --message-ids <id1> --message-ids <id2> --add-labels read --remove-labels unread ```

**CLI:** ```bash agentmail inboxes messages get-attachment --inbox-id <inbox_id> --message-id <message_id> --attachment-id <attachment_id> ```

**CLI:** ```bash agentmail inboxes messages get-raw --inbox-id <inbox_id> --message-id <message_id> ```

**CLI:** ```bash agentmail inboxes messages send --inbox-id <inbox_id> --to recipient@example.com --subject "Hello" --text "Body" ```

**CLI:** ```bash agentmail inboxes messages reply --inbox-id <inbox_id> --message-id <message_id> --text "Reply text" ```

**CLI:** ```bash agentmail inboxes messages reply-all --inbox-id <inbox_id> --message-id <message_id> --text "Reply text" ```

**CLI:** ```bash agentmail inboxes messages forward --inbox-id <inbox_id> --message-id <message_id> --to recipient@example.com ```

**CLI:** ```bash agentmail inboxes drafts list --inbox-id <inbox_id> ```

Create a draft. Supply `in_reply_to` to create a reply draft (with `reply_all` to address the whole thread), whose recipients, subject, and threading are derived from the referenced message, or `forward_of` to create a forward draft, which derives the subject, threading, and forwarded content from the source but keeps recipients caller-supplied. **CLI:** ```bash agentmail inboxes drafts create --inbox-id <inbox_id> --to recipient@example.com --subject "Draft subject" --text "Draft body" ```

**CLI:** ```bash agentmail inboxes drafts get --inbox-id <inbox_id> --draft-id <draft_id> ```

Edit fields on an existing draft. Passing `null` clears a field (or `[]` for a recipient field); `send_at: null` un-schedules a scheduled draft. A draft that is already being sent cannot be edited. **CLI:** ```bash agentmail inboxes drafts update --inbox-id <inbox_id> --draft-id <draft_id> --subject "Updated subject" ```

**CLI:** ```bash agentmail inboxes drafts delete --inbox-id <inbox_id> --draft-id <draft_id> ```

**CLI:** ```bash agentmail inboxes drafts get-attachment --inbox-id <inbox_id> --draft-id <draft_id> --attachment-id <attachment_id> ```

**CLI:** ```bash agentmail inboxes drafts send --inbox-id <inbox_id> --draft-id <draft_id> ```

**CLI:** ```bash agentmail inboxes webhooks list --inbox-id <inbox_id> ```

Create a webhook scoped to this inbox. **CLI:** ```bash agentmail inboxes webhooks create --inbox-id <inbox_id> --url https://example.com/webhook --event-types message.received ```

**CLI:** ```bash agentmail inboxes webhooks get --inbox-id <inbox_id> --webhook-id <webhook_id> ```

**CLI:** ```bash agentmail inboxes webhooks update --inbox-id <inbox_id> --webhook-id <webhook_id> --event-types message.received ```

**CLI:** ```bash agentmail inboxes webhooks delete --inbox-id <inbox_id> --webhook-id <webhook_id> ```

List the names of custom HTTP headers included with deliveries to this inbox-scoped webhook. Header values are write-only and are never returned.

Atomically set, replace, or remove custom HTTP headers included with deliveries to this inbox-scoped webhook. Header values remain write-only.

**CLI:** ```bash agentmail inboxes lists list --inbox-id <inbox_id> --direction <direction> --type <type> ```

**CLI:** ```bash agentmail inboxes lists create --inbox-id <inbox_id> --direction <direction> --type <type> --entry user@example.com ```

**CLI:** ```bash agentmail inboxes lists get --inbox-id <inbox_id> --direction <direction> --type <type> --entry <entry> ```

**CLI:** ```bash agentmail inboxes lists delete --inbox-id <inbox_id> --direction <direction> --type <type> --entry <entry> ```

Counts of email events (sent, delivered, bounced, etc.) over time for the inbox. Defaults to the last 24 hours; `start` must be within the last 90 days, and a future `end` is clamped to now. Omit `period` for individual event counts, or set it to sum counts into buckets of that many seconds. **CLI:** ```bash agentmail inboxes metrics query-events --inbox-id <inbox_id> ```

Cumulative usage series for the inbox. Each point is the running total of the usage type at that timestamp, not the change within the bucket. Inbox-scoped queries carry `storage_bytes`, `message_count`, and `thread_count`; requested types that don't apply to the scope are ignored. Defaults to the last 24 hours; `start` must be within the last 90 days, and a future `end` is clamped to now. The range divided by `period` must not exceed 1000 buckets.

Rolling bounce and complaint rates for the inbox. At each `period` grid point, the bounced (or complained) messages over the preceding `window` divided by the messages sent over the same window, with the send count alongside. Account moderation evaluates the organization-wide rate, so use the organization endpoint to see the number it acts on; the inbox view shows which inboxes contribute. Defaults to the rolling 24-hour rate sampled hourly over the last day; `start` must be within the last 90 days, `window` must be a whole multiple of `period`, and the range plus window divided by `period` must not exceed 1000 buckets. **CLI:** ```bash agentmail inboxes metrics query-rates --inbox-id <inbox_id> ```

List label change events for an inbox. Returns events in reverse chronological order by default. Use for IMAP UID projection or audit logging. **CLI:** ```bash agentmail inboxes events list --inbox-id <inbox_id> ```

**CLI:** ```bash agentmail inboxes api-keys list --inbox-id <inbox_id> ```

**CLI:** ```bash agentmail inboxes api-keys create --inbox-id <inbox_id> --name "My Key" ```

**CLI:** ```bash agentmail inboxes api-keys update --inbox-id <inbox_id> --api-key-id <api_key_id> --name "Renamed" ```

**CLI:** ```bash agentmail inboxes api-keys delete --inbox-id <inbox_id> --api-key-id <api_key_id> ```

Lists accounts held by the inbox, across all apps. Requires `inbox_read`.

Returns one account held by the inbox. An account elsewhere is a 404. Requires `inbox_read`.

Gets the inbox's calendar. Every inbox has one calendar, so this works before any event is created. Its `etag` (also the `ETag` response header) is the value to send in `If-Match` to make an update conditional. Requires the `calendar_read` permission. Calendar is in private beta in US production (`api.agentmail.to`) and is unavailable in EU production (`api.agentmail.eu`). Organizations without access receive a `403`.

Updates the calendar's default time zone. Existing events keep their own `timezone`; only events created later without a `timezone` use the new default. Requires the `calendar_update` permission. To make the update conditional, send the calendar's current `etag` in `If-Match`: a stale value returns `412`. Without `If-Match` the update applies to the calendar as it is. Calendar is in private beta in US production (`api.agentmail.to`). It is unavailable in EU production (`api.agentmail.eu`). Organizations without access receive a `403`.

Lists the events stored on the calendar: one item per one-off or recurring event, plus one item for each edited date of a recurring event (as that dated event, with `is_exception: true`). Ordered by most recently updated, and cancelled events are included. Use it to sync or manage what you created. To see what is on the calendar in a time window, use Get Agenda. The list is always read in the region that serves the request, so it can trail a change made moments earlier by a few seconds. Requires the `calendar_event_read` permission. Calendar is in private beta in US production (`api.agentmail.to`). It is unavailable in EU production (`api.agentmail.eu`). Organizations without access receive a `403`.

Creates a one-off or recurring event on the inbox's calendar. Times are wall-clock values in `timezone` (the calendar's default time zone if omitted); the response also gives each boundary as a UTC instant in `start_at` and `end_at`. `calendar.event.created` is sent once the event is stored, then `calendar.event.starting` and `calendar.event.ending` as each date begins and ends. With `send_invites: true` the inbox also emails an invitation to every attendee. Pass `client_id` to make retries safe: repeating the request with the same `client_id` and body returns the original event with status `200` instead of `201`, for as long as the event exists. With `send_invites: true`, each attendee counts as one send against the organization, pod and inbox send limits, charged before the event is stored. An over-limit request returns `429` `rate_limit_exceeded` and creates nothing. A replay of an earlier create is not charged again. The event's `etag` is the value to send in `If-Match` to make a later update or delete conditional. Requires the `calendar_event_create` permission. Calendar is in private beta in US production (`api.agentmail.to`). It is unavailable in EU production (`api.agentmail.eu`). Organizations without access receive a `403`.

Lists every date on the calendar in a time window, ordered by start time: one-off events, and recurring events expanded into their individual dates, with cancelled dates left out. Use it to answer "what is on the calendar". The window defaults to now through 90 days from now and can be at most 366 days. Items omit `description`, `metadata` and `attendees`; get an event by ID for the full object. An item the inbox is invited to still carries `response_status`, so `needs_action` marks an invitation waiting for a reply. Dates of recurring events appear only up to about 90 days from now; use List Event Instances for a recurring event's later dates. While a recurring event's dates are being regenerated after a schedule change, which takes a few seconds, the agenda can briefly leave out some of them; dates that have already started or ended stay as they ran. The agenda is read in the region that serves the request, so it can trail a change made moments earlier by a few seconds. Pass `consistency=primary` to read your own change right away. Requires the `calendar_event_read` permission. Calendar is in private beta in US production (`api.agentmail.to`). It is unavailable in EU production (`api.agentmail.eu`). Organizations without access receive a `403`.

Gets an event by its UUID, or one date of a recurring event by its dated ID (`<uuid>_<slot>`). A dated ID returns the date as it currently stands, including any edit to it, with `kind: instance`. The response's `etag` (also the `ETag` header) is the value to send in `If-Match` to make an update, delete or response to this event or date conditional. Treat it as opaque. Reads can trail a change made moments earlier by a few seconds; pass `consistency=primary` to read the latest state of an event or a date. A date that has already started or ended reads back as it ran, even if a later change to the series no longer produces it. Requires the `calendar_event_read` permission. Calendar is in private beta in US production (`api.agentmail.to`). It is unavailable in EU production (`api.agentmail.eu`). Organizations without access receive a `403`.

Updates an event. Send only the fields to change. To make the update conditional, send the event's current `etag` in `If-Match`: a stale value returns `412`. Without `If-Match` the update applies to the event as it is; a change that lands while it runs returns `409` `race_condition`, so retry. Send `If-Match` when replacing `attendees`, so you don't overwrite a response that arrived in the meantime. - **One-off or series UUID:** changes the event itself. For a series, the change applies to every date that has not been edited individually. - **Dated ID (`<uuid>_<slot>`):** changes one date (`mode=single`, the default) or that date and every later date (`mode=future`). `all_day`, `timezone` and `recurrence` cannot be sent for a dated ID. Once a date has started, its start can no longer change (409 `event_already_started`), but its end and status can; for a one-off or series UUID, send the unchanged `start` with the new `end`. Once it has ended, only `title`, `description`, `location`, `metadata` and `attendees` can change. During the few seconds a date is starting, schedule changes return 409 `event_starting`; retry shortly. Sends `calendar.event.updated`. With `send_invites: true` the organizer inbox also emails the updated invitation to every attendee. Requires the `calendar_event_update` permission. Emailing attendees counts one send per attendee against the organization, pod and inbox send limits, charged before the change is saved; an over-limit request returns `429` `rate_limit_exceeded` and changes nothing. Calendar is in private beta in US production (`api.agentmail.to`). It is unavailable in EU production (`api.agentmail.eu`). Organizations without access receive a `403`.

Deletes an event, or cancels dates of a recurring event. - **One-off or series UUID:** deletes the event and every date of it. The event disappears from reads immediately and is removed in the background; the response is `202` with a `deletion_id`. A retry returns the same `deletion_id` while removal runs (send the same `Idempotency-Key`, or none and the same `send_invites`); once it has finished, the event no longer exists and a retry returns `404`. No `calendar.event.starting` or `calendar.event.ending` webhook is sent for the event after the delete is accepted. - **Dated ID (`<uuid>_<slot>`):** cancels that date (`mode=single`, the default) or that date and every later date (`mode=future`). Returns `202` with the cancelled date. A `mode=future` delete from the first date deletes the whole series and returns a `deletion_id` instead. A date that is already running still gets its `calendar.event.ending`. Deleting a one-off or series event sends `calendar.event.deleted`. Cancelling dates sends `calendar.event.updated` with the cancelled date. With `send_invites=true` the organizer inbox also emails a cancellation to every attendee. Requires the `calendar_event_delete` permission. To make the delete conditional, send the current `etag` in `If-Match`. Emailing cancellations counts one send per attendee against the organization, pod and inbox send limits, charged before the delete; an over-limit request returns `429` `rate_limit_exceeded` and deletes nothing. Calendar is in private beta in US production (`api.agentmail.to`). It is unavailable in EU production (`api.agentmail.eu`). Organizations without access receive a `403`.

Lists the dates of one recurring event in a time window, in start order, with each date's edits applied. Dates are computed from the rule, so this works for any window up to 366 days, including dates far in the future. Cancelled dates are left out. The window defaults to now through 90 days from now. Items omit `description`, `metadata` and `attendees`; get a date by its ID for the full object. Like other reads, the list can trail a change made moments earlier by a few seconds; pass `consistency=primary` to read your own change right away. Requires the `calendar_event_read` permission. Calendar is in private beta in US production (`api.agentmail.to`). It is unavailable in EU production (`api.agentmail.eu`). Organizations without access receive a `403`.

Accepts, declines or tentatively accepts an invitation the inbox received by email. Pass the event's UUID to respond for every date, or a dated ID to respond for one date only. Only works on `email` events where the inbox is an attendee; anything else returns 409 `calendar_response_invalid`. Updates the inbox's attendee entry and sends `calendar.event.responded`. With `send_reply` (default `true`) the inbox emails the response to the organizer. Requires the `calendar_event_update` permission. To make the response conditional, send the current `etag` in `If-Match`. A reply email counts as one send against the organization, pod and inbox send limits, charged before the response is saved; an over-limit request returns `429` `rate_limit_exceeded` and changes nothing. Calendar is in private beta in US production (`api.agentmail.to`). It is unavailable in EU production (`api.agentmail.eu`). Organizations without access receive a `403`.

Lists threads, most recent first. Pass `senders`, `recipients`, or `subject` to filter by substring. Filtered requests are served by search, which caps `limit` at 100. For relevance-ranked full-text search across senders, recipients, subject, and message body, use `Search Threads`. **CLI:** ```bash agentmail threads list ```

Full-text search across threads in the organization, ranked by relevance. The query is matched against senders, recipients, and subject (substring) and the message body (tokenized full text). Spam, trash, blocked, and unauthenticated threads are always excluded. `limit` cannot exceed 100.

**CLI:** ```bash agentmail threads get --thread-id <thread_id> ```

Updates thread labels. Cannot add or remove system labels (sent, received, bounced, etc.). Rejects requests with a `422` for threads with 100 or more messages.

Permanently deletes a thread and all of its messages. **CLI:** ```bash agentmail threads delete --thread-id <thread_id> ```

**CLI:** ```bash agentmail threads get-attachment --thread-id <thread_id> --attachment-id <attachment_id> ```

**CLI:** ```bash agentmail drafts list ```

**CLI:** ```bash agentmail drafts get --draft-id <draft_id> ```

**CLI:** ```bash agentmail drafts get-attachment --draft-id <draft_id> --attachment-id <attachment_id> ```

**CLI:** ```bash agentmail webhooks list ```

**CLI:** ```bash agentmail webhooks create --url https://example.com/webhook --event-types message.received ```

**CLI:** ```bash agentmail webhooks get --webhook-id <webhook_id> ```

Update inbox or pod subscriptions, or replace the webhook's `event_types` in full when you pass a non-empty `event_types` array (see request field docs). Inbox and pod changes use add/remove lists. **CLI:** ```bash agentmail webhooks update --webhook-id <webhook_id> --add-inbox-ids <inbox_id> ```

**CLI:** ```bash agentmail webhooks delete --webhook-id <webhook_id> ```

List the names of custom HTTP headers included with deliveries to this webhook. Header values are write-only and are never returned.

Atomically set, replace, or remove custom HTTP headers included with deliveries to this webhook. Header values remain write-only.

**CLI:** ```bash agentmail domains list ```

**CLI:** ```bash agentmail domains create --domain example.com ```

**CLI:** ```bash agentmail domains get --domain-id <domain_id> ```

**CLI:** ```bash agentmail domains update --domain-id <domain_id> ```

**CLI:** ```bash agentmail domains delete --domain-id <domain_id> ```

**CLI:** ```bash agentmail domains get-zone-file --domain-id <domain_id> ```

**CLI:** ```bash agentmail domains verify --domain-id <domain_id> ```

Build a one-click DNS setup link for the domain via the Domain Connect standard. When the domain's DNS provider supports Domain Connect and carries the AgentMail template, the response contains a signed URL: opening it lets the domain owner approve the required DNS records at their provider, which writes them automatically — no copy-paste. When the provider does not support it, `supported` is `false` and the domain's `records` should be added manually instead.

**CLI:** ```bash agentmail lists list --direction <direction> --type <type> ```

**CLI:** ```bash agentmail lists create --direction <direction> --type <type> --entry user@example.com ```

**CLI:** ```bash agentmail lists get --direction <direction> --type <type> --entry <entry> ```

**CLI:** ```bash agentmail lists delete --direction <direction> --type <type> --entry <entry> ```

Counts of email events (sent, delivered, bounced, etc.) over time for the organization. Defaults to the last 24 hours; `start` must be within the last 90 days, and a future `end` is clamped to now. Omit `period` for individual event counts, or set it to sum counts into buckets of that many seconds. **CLI:** ```bash agentmail metrics query-events ```

Cumulative usage series for the organization. Each point is the running total of the usage type at that timestamp, not the change within the bucket. Defaults to the last 24 hours; `start` must be within the last 90 days, and a future `end` is clamped to now. The range divided by `period` must not exceed 1000 buckets.

Rolling bounce and complaint rates for the organization. At each `period` grid point, the bounced (or complained) messages over the preceding `window` divided by the messages sent over the same window, with the send count alongside so you can see the volume behind it. This is the number AgentMail's account moderation acts on: a warning at a 5% bounce rate and suspension at 10%, evaluated over a rolling 24 hours once at least 1,000 messages were sent in that window. Defaults to the rolling 24-hour rate sampled hourly over the last day; `start` must be within the last 90 days, `window` must be a whole multiple of `period`, and the range plus window divided by `period` must not exceed 1000 buckets. **CLI:** ```bash agentmail metrics query-rates ```

Lists every credential, newest first. Filter one family with `type`. Page to token exhaustion: a page can be empty and still carry a `next_page_token`. **CLI:** ```bash agentmail api-keys list ```

Creates a bearer key, or registers a public key when the body carries `public_key`. The route selects the scope. Bearer secrets are returned once. **CLI:** ```bash agentmail api-keys create --name "My Key" ```

Returns one credential of any family. Public keys also resolve by `client_id`. Poll a sign-in key until `status` is `active`.

Renames a credential or changes its permissions. Public keys also resolve by `client_id`; a sign-in key accepts only `app_connect` and `app_share_owner`.

Deletes one credential of any family. A pending sign-in key is cancelled; an active one is revoked. Public keys also resolve by `client_id`. **CLI:** ```bash agentmail api-keys delete --api-key-id <api_key_id> ```

Lists apps, most popular first.

Searches apps by name prefix.

Gets one app by ID or slug. A catalog app returns its full entry. A registered app that the catalog does not list returns its ID and name only, without `updated_at`, so anyone holding its ID can still look it up; a slug finds catalog apps only. List Apps and Search Apps show catalog entries only.

Lists accounts at one app, most recent sign-in first.

Starts signing an inbox in to an app. Returns a single-use `magic_url`, valid for five minutes, to open in the client that will hold the sign-in; the client enrolls as the inbox and continues to the app. An app in the catalog can be named by its `slug`, as in `POST /v0/apps/firecrawl/connect`. A `404` names the missing resource: `App` or `Inbox`. A `403` `AppSignupLimitError` means the app accepts no more sign-ups from your organization; sign in with an inbox that already has an account there.

Lists accounts across all apps, scoped to the API key: an organization key sees every account, a pod key its pod's, an inbox key its inbox's. Requires `inbox_read`.

Returns one account by ID. An account outside the key's scope is a 404. Requires `inbox_read`.

Updates one account. Set `status` to `disabled` to stop the inbox from signing in at the app again, or to `enabled` to re-enable it. Idempotent: disabling an already disabled account keeps its original `disabled_at`, and enabling an enabled account is a no-op. Find the `account_id` with List Accounts. An account exists only after an inbox's first sign-in at an app, so it cannot be disabled in advance. A disable applies to that inbox at that app whichever sign-in key is used: the app's next authorization ends in `access_denied`, and a code issued earlier is refused with `invalid_grant`. Access tokens already issued stay valid until they expire, and the app's own session is unaffected. Requires `account_update`, which sign-in keys (`type: public_key`) cannot hold, so call this with a bearer API key. An account outside the key's scope is a 404. A 409 means the account changed during the write; read it again and retry.

**CLI:** ```bash agentmail pods list ```

**CLI:** ```bash agentmail pods create --client-id my-pod ```

**CLI:** ```bash agentmail pods get --pod-id <pod_id> ```

**CLI:** ```bash agentmail pods delete --pod-id <pod_id> ```

**CLI:** ```bash agentmail pods inboxes list --pod-id <pod_id> ```

**CLI:** ```bash agentmail pods inboxes create --pod-id <pod_id> --username myagent --domain example.com ```

Searches inboxes in the pod by address or display name, ranked by relevance. Each word in the query matches the start of a word in the address or display name, so `sup` matches `support@example.com` but `port` does not. An exact address match always ranks first. `limit` cannot exceed 100. A page can be empty and still carry a `next_page_token`; keep paging until the token is absent.

**CLI:** ```bash agentmail pods inboxes get --pod-id <pod_id> --inbox-id <inbox_id> ```

**CLI:** ```bash agentmail pods inboxes update --pod-id <pod_id> --inbox-id <inbox_id> ```

**CLI:** ```bash agentmail pods inboxes delete --pod-id <pod_id> --inbox-id <inbox_id> ```

Lists threads in the pod, most recent first. Pass `senders`, `recipients`, or `subject` to filter by substring. Filtered requests are served by search, which caps `limit` at 100. For relevance-ranked full-text search, use `Search Threads`. **CLI:** ```bash agentmail pods threads list --pod-id <pod_id> ```

Full-text search across threads in the pod, ranked by relevance. The query is matched against senders, recipients, and subject (substring) and the message body (tokenized full text). Spam, trash, blocked, and unauthenticated threads are always excluded. `limit` cannot exceed 100.

**CLI:** ```bash agentmail pods threads get --pod-id <pod_id> --thread-id <thread_id> ```

Updates thread labels. Cannot add or remove system labels (sent, received, bounced, etc.). Rejects requests with a `422` for threads with 100 or more messages.

Permanently deletes a thread and all of its messages. **CLI:** ```bash agentmail pods threads delete --pod-id <pod_id> --thread-id <thread_id> ```

**CLI:** ```bash agentmail pods threads get-attachment --pod-id <pod_id> --thread-id <thread_id> --attachment-id <attachment_id> ```

**CLI:** ```bash agentmail pods drafts list --pod-id <pod_id> ```

**CLI:** ```bash agentmail pods drafts get --pod-id <pod_id> --draft-id <draft_id> ```

**CLI:** ```bash agentmail pods drafts get-attachment --pod-id <pod_id> --draft-id <draft_id> --attachment-id <attachment_id> ```

**CLI:** ```bash agentmail pods webhooks list --pod-id <pod_id> ```

Create a webhook scoped to this pod. **CLI:** ```bash agentmail pods webhooks create --pod-id <pod_id> --url https://example.com/webhook --event-types message.received ```

**CLI:** ```bash agentmail pods webhooks get --pod-id <pod_id> --webhook-id <webhook_id> ```

**CLI:** ```bash agentmail pods webhooks update --pod-id <pod_id> --webhook-id <webhook_id> --add-inbox-ids <inbox_id> ```

**CLI:** ```bash agentmail pods webhooks delete --pod-id <pod_id> --webhook-id <webhook_id> ```

List the names of custom HTTP headers included with deliveries to this pod-scoped webhook. Header values are write-only and are never returned.

Atomically set, replace, or remove custom HTTP headers included with deliveries to this pod-scoped webhook. Header values remain write-only.

**CLI:** ```bash agentmail pods domains list --pod-id <pod_id> ```

**CLI:** ```bash agentmail pods domains create --pod-id <pod_id> --domain example.com ```

**CLI:** ```bash agentmail pods domains get --pod-id <pod_id> --domain-id <domain_id> ```

**CLI:** ```bash agentmail pods domains update --pod-id <pod_id> --domain-id <domain_id> ```

**CLI:** ```bash agentmail pods domains delete --pod-id <pod_id> --domain-id <domain_id> ```

**CLI:** ```bash agentmail pods domains get-zone-file --pod-id <pod_id> --domain-id <domain_id> ```

**CLI:** ```bash agentmail pods domains verify --pod-id <pod_id> --domain-id <domain_id> ```

**CLI:** ```bash agentmail pods lists list --pod-id <pod_id> --direction <direction> --type <type> ```

**CLI:** ```bash agentmail pods lists create --pod-id <pod_id> --direction <direction> --type <type> --entry user@example.com ```

**CLI:** ```bash agentmail pods lists get --pod-id <pod_id> --direction <direction> --type <type> --entry <entry> ```

**CLI:** ```bash agentmail pods lists delete --pod-id <pod_id> --direction <direction> --type <type> --entry <entry> ```

Counts of email events (sent, delivered, bounced, etc.) over time for the pod. Defaults to the last 24 hours; `start` must be within the last 90 days, and a future `end` is clamped to now. Omit `period` for individual event counts, or set it to sum counts into buckets of that many seconds. **CLI:** ```bash agentmail pods metrics query-events --pod-id <pod_id> ```

Cumulative usage series for the pod. Each point is the running total of the usage type at that timestamp, not the change within the bucket. Pod-scoped queries carry every usage type except `pod_count`; requested types that don't apply to the scope are ignored. Defaults to the last 24 hours; `start` must be within the last 90 days, and a future `end` is clamped to now. The range divided by `period` must not exceed 1000 buckets.

Rolling bounce and complaint rates for the pod. At each `period` grid point, the bounced (or complained) messages over the preceding `window` divided by the messages sent over the same window, with the send count alongside. Account moderation evaluates the organization-wide rate, so use the organization endpoint to see the number it acts on; the pod view shows which pods contribute. Defaults to the rolling 24-hour rate sampled hourly over the last day; `start` must be within the last 90 days, `window` must be a whole multiple of `period`, and the range plus window divided by `period` must not exceed 1000 buckets. **CLI:** ```bash agentmail pods metrics query-rates --pod-id <pod_id> ```

**CLI:** ```bash agentmail pods api-keys list --pod-id <pod_id> ```

**CLI:** ```bash agentmail pods api-keys create --pod-id <pod_id> --name "My Key" ```

**CLI:** ```bash agentmail pods api-keys update --pod-id <pod_id> --api-key-id <api_key_id> --name "Renamed" ```

**CLI:** ```bash agentmail pods api-keys delete --pod-id <pod_id> --api-key-id <api_key_id> ```

Lists accounts held by inboxes in the pod, across all apps. Requires `inbox_read`.

Returns one account held by inboxes in the pod. An account elsewhere is a 404. Requires `inbox_read`.

Returns the organization for the authenticated API key (usage limits, counts, and billing metadata). **CLI:** ```bash agentmail organizations get ```

Returns the identity and scope of the authenticated credential. Useful when a client holds a pod-scoped or inbox-scoped API key and needs to discover the parent organization, pod, or inbox without prior knowledge. **CLI:** ```bash agentmail auth me ```