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. 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 ```

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 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" ```

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

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> ```

Attach a browser enrollment intent to the inbox. Requires `api_key_create`. Before submitting `transaction_jti`, independently verify that the browser page's final origin is exactly `https://auth.agentid.com`. This endpoint is available to every organization using US production. It is not available in EU production. Select `inbox_id` from trusted AgentMail configuration. An AgentID `login_hint` is not authoritative for selecting the inbox; when the transaction includes one, it must match the path inbox. **AgentMail API keys are sent only to `https://api.agentmail.to`; AgentID never requests them.** A new intent returns `202`; an idempotent retry for the same pending transaction, inbox, and bearer key returns `200` with the same receipt. An intent lasts at most five minutes. An activated credential lasts at most 30 days and cannot outlive its authorizing bearer API key. Creation is limited to 20 intents per bearer API key per hour, 100 per organization per hour, and five live unused intents per bearer API key. Browser activation is separately limited to 20 activations per authorizing bearer API key per UTC day. Either kind of limit can return `429`; honor the `Retry-After` header. Cancelling an enrollment releases its live-intent slot but does not reset the daily activation counter.

**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.

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 delete --inbox-id <inbox_id> --api-key-id <api_key_id> ```

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.

**CLI:** ```bash agentmail api-keys list ```

**CLI:** ```bash agentmail api-keys create --name "My Key" ```

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

List only public-key credentials visible to the bearer caller's scope. Bearer credentials are never returned, even though both credential types share storage and pagination indexes. Requires `api_key_read`.

Register a public P-256 JWK using an existing AgentMail bearer API key with `api_key_create`. Re-registering the same JWK creates a new credential ID; it does not replace or recover an earlier credential. The private key must never be sent to AgentMail.

Rename the credential. All security-relevant fields are immutable. Requires `api_key_update`.

Permanently revoke one public-key credential. This hard-deletes the credential; repeating the request returns not found. Requires `api_key_delete`.

Invalidate every current public-key credential in the caller's organization by advancing its AgentID key generation. The caller must be organization-scoped and either have `api_key_delete` or, for a verified self-serve agent organization, use an unrestricted unmanaged bearer credential. No request body is accepted. `Idempotency-Key` is required and must be a UUID. Reusing the same UUID returns the original permanent receipt without advancing the generation again. A new UUID performs a new generation advance.

List active browser credentials visible to the caller's scope. Requires `api_key_read`.

List owner-facing browser credential and consent lifecycle events. Requires `api_key_read`.

Permanently revoke one active browser credential. Requires `api_key_delete`.

Cancel one pending, unexpired browser enrollment intent. Requires `api_key_delete`.

List remembered AgentID client approvals for one live inbox. Requires `api_key_read`.

Revoke one remembered AgentID client approval. Requires `api_key_delete`.

Lists providers, most popular first.

Searches providers by name prefix.

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

Starts signing an inbox in to a provider. Returns a `magic_url` valid for five minutes; open it in the browser that will hold the sign-in. Requires `api_key_create` and an `Idempotency-Key` header.

Lists accounts across all providers.

**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.

**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 delete --pod-id <pod_id> --api-key-id <api_key_id> ```

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 ```