Skip to content

reference.md

Latest commit

 

History

History
2860 lines (2078 loc) · 92.7 KB

reference.md

File metadata and controls

2860 lines (2078 loc) · 92.7 KB
Raw

AgentMail CLI Reference

Full command reference for agentmail.

Commands

agentmail accounts

agentmail accounts get

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

GET /v0/accounts/{account_id}

Flag Type Required Description
--account-id AccountId Yes

agentmail accounts list

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.

GET /v0/accounts

Flag Type Required Description
--limit Limit No
--page-token PageToken No
--ascending Ascending No

agentmail accounts update

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.

PATCH /v0/accounts/{account_id}/update

Flag Type Required Description
--account-id AccountId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail agent

agentmail agent attach-human

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:

agentmail agent attach-human --human-email user@example.com

POST /v0/agent/human

Flag Type Required Description
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail agent sign-up

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?). 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:

agentmail agent sign-up --human-email user@example.com --username my-agent

POST /v0/agent/sign-up

Flag Type Required Description
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail agent verify

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 using the human email address you provided to verify your account.

CLI:

agentmail agent verify --otp-code 123456

POST /v0/agent/verify

Flag Type Required Description
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail api-keys

agentmail api-keys create

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:

agentmail api-keys create --name "My Key"

POST /v0/api-keys

Flag Type Required Description
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail api-keys delete

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:

agentmail api-keys delete --api-key-id <api_key_id>

DELETE /v0/api-keys/{api_key_id}

Flag Type Required Description
--api-key-id ApiKeyId Yes

agentmail api-keys get

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

GET /v0/api-keys/{api_key_id}

Flag Type Required Description
--api-key-id ApiKeyId Yes

agentmail api-keys list

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:

agentmail api-keys list

GET /v0/api-keys

Flag Type Required Description
--type ApiKeyType No Restrict the list to one credential family. Omit for every family.
--limit Limit No
--page-token PageToken No
--ascending Ascending No

agentmail api-keys update

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.

PATCH /v0/api-keys/{api_key_id}

Flag Type Required Description
--api-key-id ApiKeyId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail apps

agentmail apps connect

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.

POST /v0/apps/{app_id}/connect

Flag Type Required Description
--app-id string Yes ID of app, or the slug of an app in the catalog. A slug ignores case, spaces and punctuation.
--idempotency-key string No Unique key that makes the connect idempotent. The endpoint requires one; the CLI generates a UUID when the flag is omitted and reuses it across retries, so a transient failure cannot start a second sign-in. Pass a value to make a manual re-run resolve to the same attempt.
--json JSON No Request body as JSON (or use individual body-field flags)

agentmail apps get

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.

GET /v0/apps/{app_id}

Flag Type Required Description
--app-id string Yes ID of app, or the slug of an app in the catalog. A slug ignores case, spaces and punctuation.

agentmail apps list

Lists apps, most popular first.

GET /v0/apps

Flag Type Required Description
--limit Limit No
--page-token PageToken No
--category AppCategory No Only apps in this category. A filtered page can hold fewer than limit apps while more remain, so page until next_page_token is absent. A page_token works only with the category it was returned for.

agentmail apps list-accounts

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

GET /v0/apps/{app_id}/accounts

Flag Type Required Description
--app-id string Yes ID of app, or the slug of an app in the catalog. A slug ignores case, spaces and punctuation.
--limit Limit No
--page-token PageToken No

agentmail apps search

Searches apps by name prefix.

GET /v0/apps/search

Flag Type Required Description
--q string Yes Name prefix to search for.
--limit Limit No

agentmail auth

agentmail auth me

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:

agentmail auth me

GET /v0/auth/me

agentmail domains

agentmail domains create

CLI:

agentmail domains create --domain example.com

POST /v0/domains

Flag Type Required Description
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail domains delete

CLI:

agentmail domains delete --domain-id <domain_id>

DELETE /v0/domains/{domain_id}

Flag Type Required Description
--domain-id DomainId Yes

agentmail domains get

CLI:

agentmail domains get --domain-id <domain_id>

GET /v0/domains/{domain_id}

Flag Type Required Description
--domain-id DomainId Yes

agentmail domains get-setup-link

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.

GET /v0/domains/{domain_id}/setup-link

Flag Type Required Description
--domain-id DomainId Yes

agentmail domains get-zone-file

CLI:

agentmail domains get-zone-file --domain-id <domain_id>

GET /v0/domains/{domain_id}/zone-file

Flag Type Required Description
--domain-id DomainId Yes

agentmail domains list

CLI:

agentmail domains list

GET /v0/domains

Flag Type Required Description
--limit Limit No
--page-token PageToken No
--ascending Ascending No

agentmail domains update

CLI:

agentmail domains update --domain-id <domain_id>

PATCH /v0/domains/{domain_id}

Flag Type Required Description
--domain-id DomainId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail domains verify

CLI:

agentmail domains verify --domain-id <domain_id>

POST /v0/domains/{domain_id}/verify

Flag Type Required Description
--domain-id DomainId Yes

agentmail drafts

agentmail drafts get

CLI:

agentmail drafts get --draft-id <draft_id>

GET /v0/drafts/{draft_id}

Flag Type Required Description
--draft-id DraftId Yes

agentmail drafts get-attachment

CLI:

agentmail drafts get-attachment --draft-id <draft_id> --attachment-id <attachment_id>

GET /v0/drafts/{draft_id}/attachments/{attachment_id}

Flag Type Required Description
--draft-id DraftId Yes
--attachment-id AttachmentId Yes

agentmail drafts list

CLI:

agentmail drafts list

GET /v0/drafts

Flag Type Required Description
--limit Limit No
--page-token PageToken No
--labels Labels No
--before Before No
--after After No
--ascending Ascending No

agentmail inboxes

agentmail inboxes authorize

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.

POST /v0/inboxes/{inbox_id}/authorize

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail inboxes create

CLI:

agentmail inboxes create --display-name "My Agent" --username myagent --domain agentmail.to

POST /v0/inboxes

Flag Type Required Description
--json JSON No Request body as JSON (or use individual body-field flags)

agentmail inboxes delete

CLI:

agentmail inboxes delete --inbox-id <inbox_id>

DELETE /v0/inboxes/{inbox_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes

agentmail inboxes get

CLI:

agentmail inboxes get --inbox-id <inbox_id>

GET /v0/inboxes/{inbox_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes

agentmail inboxes list

CLI:

agentmail inboxes list

GET /v0/inboxes

Flag Type Required Description
--limit Limit No
--page-token PageToken No
--ascending Ascending No

agentmail inboxes search

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.

GET /v0/inboxes/search

Flag Type Required Description
--q string Yes Address or display name to search for. Matches word prefixes. Must be 2 to 256 characters.
--limit Limit No
--page-token PageToken No

agentmail inboxes update

CLI:

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.

PATCH /v0/inboxes/{inbox_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail inboxes accounts

agentmail inboxes accounts get

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

GET /v0/inboxes/{inbox_id}/accounts/{account_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--account-id AccountId Yes

agentmail inboxes accounts list

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

GET /v0/inboxes/{inbox_id}/accounts

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--limit Limit No
--page-token PageToken No
--ascending Ascending No

agentmail inboxes api-keys

agentmail inboxes api-keys create

CLI:

agentmail inboxes api-keys create --inbox-id <inbox_id> --name "My Key"

POST /v0/inboxes/{inbox_id}/api-keys

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail inboxes api-keys delete

CLI:

agentmail inboxes api-keys delete --inbox-id <inbox_id> --api-key-id <api_key_id>

DELETE /v0/inboxes/{inbox_id}/api-keys/{api_key_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--api-key-id ApiKeyId Yes

agentmail inboxes api-keys list

CLI:

agentmail inboxes api-keys list --inbox-id <inbox_id>

GET /v0/inboxes/{inbox_id}/api-keys

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--limit Limit No
--page-token PageToken No

agentmail inboxes api-keys update

CLI:

agentmail inboxes api-keys update --inbox-id <inbox_id> --api-key-id <api_key_id> --name "Renamed"

PATCH /v0/inboxes/{inbox_id}/api-keys/{api_key_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--api-key-id ApiKeyId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail inboxes calendar

agentmail inboxes calendar create-event [PRE RELEASE]

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: organizations without access receive a 403.

POST /v0/inboxes/{inbox_id}/calendar/events

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail inboxes calendar delete-event [PRE RELEASE]

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: organizations without access receive a 403.

DELETE /v0/inboxes/{inbox_id}/calendar/events/{event_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--event-id CalendarEventId Yes
--mode InstanceMutationMode No
--send-invites boolean No When true, emails a cancellation (iCalendar CANCEL) to every attendee. Only the organizer can send. Defaults to false.
--if-match string No The event's or date's current etag. Optional; makes the delete conditional; * matches any current version.
--idempotency-key string No 1 to 128 visible ASCII characters. Optional. Retrying a delete with the same key
returns the original result; without a key, retries of the same delete share one
derived from the event and send_invites, so a keyless retry that changes
send_invites is a different delete and returns 404 while removal runs. Keys are
unique across your organization: reusing one to delete a different event returns
409 idempotency_conflict.

agentmail inboxes calendar get [PRE RELEASE]

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: organizations without access receive a 403.

GET /v0/inboxes/{inbox_id}/calendar

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--consistency CalendarConsistency No

agentmail inboxes calendar get-agenda [PRE RELEASE]

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. 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: organizations without access receive a 403.

GET /v0/inboxes/{inbox_id}/calendar/agenda

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--consistency CalendarConsistency No
--after WindowAfter No
--before WindowBefore No
--include-overlapping IncludeOverlapping No
--limit CalendarLimit No
--page-token PageToken No

agentmail inboxes calendar get-event [PRE RELEASE]

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: organizations without access receive a 403.

GET /v0/inboxes/{inbox_id}/calendar/events/{event_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--event-id CalendarEventId Yes
--consistency CalendarConsistency No

agentmail inboxes calendar list-event-instances [PRE RELEASE]

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: organizations without access receive a 403.

GET /v0/inboxes/{inbox_id}/calendar/events/{event_id}/instances

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--event-id string Yes UUID of the recurring event.
--consistency CalendarConsistency No
--after WindowAfter No
--before WindowBefore No
--include-overlapping IncludeOverlapping No
--limit CalendarLimit No
--page-token PageToken No

agentmail inboxes calendar list-events [PRE RELEASE]

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: organizations without access receive a 403.

GET /v0/inboxes/{inbox_id}/calendar/events

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--limit CalendarLimit No
--page-token PageToken No

agentmail inboxes calendar respond-to-event [PRE RELEASE]

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: organizations without access receive a 403.

POST /v0/inboxes/{inbox_id}/calendar/events/{event_id}/respond

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--event-id CalendarEventId Yes
--if-match string No The event's or date's current etag. Optional; makes the response conditional; * matches any current version.
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail inboxes calendar update [PRE RELEASE]

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: organizations without access receive a 403.

PATCH /v0/inboxes/{inbox_id}/calendar

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--if-match string No The calendar's current etag, for example "rv-0". Optional; makes the update conditional; * matches any current version.
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail inboxes calendar update-event [PRE RELEASE]

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: organizations without access receive a 403.

PATCH /v0/inboxes/{inbox_id}/calendar/events/{event_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--event-id CalendarEventId Yes
--mode InstanceMutationMode No
--if-match string No The event's or date's current etag, from the latest read or write response. Optional; makes the update conditional; * matches any current version.
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail inboxes drafts

agentmail inboxes drafts create

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:

agentmail inboxes drafts create --inbox-id <inbox_id> --to recipient@example.com --subject "Draft subject" --text "Draft body"

POST /v0/inboxes/{inbox_id}/drafts

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail inboxes drafts delete

CLI:

agentmail inboxes drafts delete --inbox-id <inbox_id> --draft-id <draft_id>

DELETE /v0/inboxes/{inbox_id}/drafts/{draft_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--draft-id DraftId Yes

agentmail inboxes drafts get

CLI:

agentmail inboxes drafts get --inbox-id <inbox_id> --draft-id <draft_id>

GET /v0/inboxes/{inbox_id}/drafts/{draft_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--draft-id DraftId Yes

agentmail inboxes drafts get-attachment

CLI:

agentmail inboxes drafts get-attachment --inbox-id <inbox_id> --draft-id <draft_id> --attachment-id <attachment_id>

GET /v0/inboxes/{inbox_id}/drafts/{draft_id}/attachments/{attachment_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--draft-id DraftId Yes
--attachment-id AttachmentId Yes

agentmail inboxes drafts list

CLI:

agentmail inboxes drafts list --inbox-id <inbox_id>

GET /v0/inboxes/{inbox_id}/drafts

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--limit Limit No
--page-token PageToken No
--labels Labels No
--before Before No
--after After No
--ascending Ascending No

agentmail inboxes drafts send

CLI:

agentmail inboxes drafts send --inbox-id <inbox_id> --draft-id <draft_id>

POST /v0/inboxes/{inbox_id}/drafts/{draft_id}/send

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--draft-id DraftId Yes
--idempotency-key string No Unique key that makes a send idempotent. A retry carrying the same key returns the original message instead of sending a second email; reusing a key with a different request returns a 409 conflict. Keys expire 24 hours after the send completes.
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail inboxes drafts update

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:

agentmail inboxes drafts update --inbox-id <inbox_id> --draft-id <draft_id> --subject "Updated subject"

PATCH /v0/inboxes/{inbox_id}/drafts/{draft_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--draft-id DraftId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail inboxes events

agentmail inboxes events list

List label change events for an inbox. Returns events in reverse chronological order by default. Use for IMAP UID projection or audit logging.

CLI:

agentmail inboxes events list --inbox-id <inbox_id>

GET /v0/inboxes/{inbox_id}/events

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--limit Limit No
--page-token PageToken No
--ascending Ascending No

agentmail inboxes lists

agentmail inboxes lists create

CLI:

agentmail inboxes lists create --inbox-id <inbox_id> --direction <direction> --type <type> --entry user@example.com

POST /v0/inboxes/{inbox_id}/lists/{direction}/{type}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--direction Direction Yes
--type ListType Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail inboxes lists delete

CLI:

agentmail inboxes lists delete --inbox-id <inbox_id> --direction <direction> --type <type> --entry <entry>

DELETE /v0/inboxes/{inbox_id}/lists/{direction}/{type}/{entry}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--direction Direction Yes
--type ListType Yes
--entry string Yes Email address or domain.

agentmail inboxes lists get

CLI:

agentmail inboxes lists get --inbox-id <inbox_id> --direction <direction> --type <type> --entry <entry>

GET /v0/inboxes/{inbox_id}/lists/{direction}/{type}/{entry}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--direction Direction Yes
--type ListType Yes
--entry string Yes Email address or domain.

agentmail inboxes lists list

CLI:

agentmail inboxes lists list --inbox-id <inbox_id> --direction <direction> --type <type>

GET /v0/inboxes/{inbox_id}/lists/{direction}/{type}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--direction Direction Yes
--type ListType Yes
--limit Limit No
--page-token PageToken No

agentmail inboxes messages

agentmail inboxes messages batch-get

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:

agentmail inboxes messages batch-get --inbox-id <inbox_id> --message-ids <id1> --message-ids <id2>

POST /v0/inboxes/{inbox_id}/messages/batch-get

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail inboxes messages batch-update

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:

agentmail inboxes messages batch-update --inbox-id <inbox_id> --message-ids <id1> --message-ids <id2> --add-labels read --remove-labels unread

POST /v0/inboxes/{inbox_id}/messages/batch-update

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail inboxes messages delete

Permanently deletes a message.

CLI:

agentmail inboxes messages delete --inbox-id <inbox_id> --message-id <message_id>

DELETE /v0/inboxes/{inbox_id}/messages/{message_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--message-id MessageId Yes

agentmail inboxes messages forward

CLI:

agentmail inboxes messages forward --inbox-id <inbox_id> --message-id <message_id> --to recipient@example.com

POST /v0/inboxes/{inbox_id}/messages/{message_id}/forward

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--message-id MessageId Yes
--idempotency-key string No Unique key that makes a send idempotent. A retry carrying the same key returns the original message instead of sending a second email; reusing a key with a different request returns a 409 conflict. Keys expire 24 hours after the send completes.
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail inboxes messages get

CLI:

agentmail inboxes messages get --inbox-id <inbox_id> --message-id <message_id>

GET /v0/inboxes/{inbox_id}/messages/{message_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--message-id MessageId Yes

agentmail inboxes messages get-attachment

CLI:

agentmail inboxes messages get-attachment --inbox-id <inbox_id> --message-id <message_id> --attachment-id <attachment_id>

GET /v0/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--message-id MessageId Yes
--attachment-id AttachmentId Yes

agentmail inboxes messages get-raw

CLI:

agentmail inboxes messages get-raw --inbox-id <inbox_id> --message-id <message_id>

GET /v0/inboxes/{inbox_id}/messages/{message_id}/raw

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--message-id MessageId Yes

agentmail inboxes messages list

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:

agentmail inboxes messages list --inbox-id <inbox_id>

GET /v0/inboxes/{inbox_id}/messages

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--limit Limit No
--page-token PageToken No
--labels Labels No
--before Before No
--after After No
--ascending Ascending No
--include-spam IncludeSpam No
--include-blocked IncludeBlocked No
--include-unauthenticated IncludeUnauthenticated No
--include-trash IncludeTrash No
--from string[] No Filter to messages whose sender contains this value (substring match). Repeatable; all values must match.
--to string[] No Filter to messages whose recipients (to, cc, or bcc) contain this value (substring match). Repeatable; all values must match.
--subject string[] No Filter to messages whose subject contains this value (substring match). Repeatable; all values must match.

agentmail inboxes messages reply

CLI:

agentmail inboxes messages reply --inbox-id <inbox_id> --message-id <message_id> --text "Reply text"

POST /v0/inboxes/{inbox_id}/messages/{message_id}/reply

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--message-id MessageId Yes
--idempotency-key string No Unique key that makes a send idempotent. A retry carrying the same key returns the original message instead of sending a second email; reusing a key with a different request returns a 409 conflict. Keys expire 24 hours after the send completes.
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail inboxes messages reply-all

CLI:

agentmail inboxes messages reply-all --inbox-id <inbox_id> --message-id <message_id> --text "Reply text"

POST /v0/inboxes/{inbox_id}/messages/{message_id}/reply-all

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--message-id MessageId Yes
--idempotency-key string No Unique key that makes a send idempotent. A retry carrying the same key returns the original message instead of sending a second email; reusing a key with a different request returns a 409 conflict. Keys expire 24 hours after the send completes.
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail inboxes messages search

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.

GET /v0/inboxes/{inbox_id}/messages/search

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--q Query Yes
--limit Limit No
--page-token PageToken No
--before Before No
--after After No

agentmail inboxes messages send

CLI:

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

POST /v0/inboxes/{inbox_id}/messages/send

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--idempotency-key string No Unique key that makes a send idempotent. A retry carrying the same key returns the original message instead of sending a second email; reusing a key with a different request returns a 409 conflict. Keys expire 24 hours after the send completes.
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail inboxes messages update

CLI:

agentmail inboxes messages update --inbox-id <inbox_id> --message-id <message_id> --add-labels read --remove-labels unread

PATCH /v0/inboxes/{inbox_id}/messages/{message_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--message-id MessageId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail inboxes metrics

agentmail inboxes metrics query-events

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:

agentmail inboxes metrics query-events --inbox-id <inbox_id>

GET /v0/inboxes/{inbox_id}/metrics/events

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--event-types MetricEventTypes No
--start Start No
--end End No
--period Period No
--limit MetricLimit No
--descending Descending No

agentmail inboxes metrics query-rates

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:

agentmail inboxes metrics query-rates --inbox-id <inbox_id>

GET /v0/inboxes/{inbox_id}/metrics/rates

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--rate-types RateTypes No
--start Start No
--end End No
--period RatePeriod No
--window Window No
--limit MetricLimit No
--descending Descending No

agentmail inboxes metrics query-usage

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.

GET /v0/inboxes/{inbox_id}/metrics/usage

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--usage-types UsageTypes No
--start Start No
--end End No
--period Period No
--limit MetricLimit No
--descending Descending No

agentmail inboxes threads

agentmail inboxes threads delete

Permanently deletes a thread and all of its messages.

CLI:

agentmail inboxes threads delete --inbox-id <inbox_id> --thread-id <thread_id>

DELETE /v0/inboxes/{inbox_id}/threads/{thread_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--thread-id ThreadId Yes

agentmail inboxes threads get

CLI:

agentmail inboxes threads get --inbox-id <inbox_id> --thread-id <thread_id>

GET /v0/inboxes/{inbox_id}/threads/{thread_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--thread-id ThreadId Yes
--limit Limit No Maximum number of messages to return. Cannot exceed 100.
--page-token PageToken No Token returned by the previous response for retrieving the next, older page.

agentmail inboxes threads get-attachment

CLI:

agentmail inboxes threads get-attachment --inbox-id <inbox_id> --thread-id <thread_id> --attachment-id <attachment_id>

GET /v0/inboxes/{inbox_id}/threads/{thread_id}/attachments/{attachment_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--thread-id ThreadId Yes
--attachment-id AttachmentId Yes

agentmail inboxes threads list

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:

agentmail inboxes threads list --inbox-id <inbox_id>

GET /v0/inboxes/{inbox_id}/threads

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--limit Limit No
--page-token PageToken No
--labels Labels No
--before Before No
--after After No
--ascending Ascending No
--include-spam IncludeSpam No
--include-blocked IncludeBlocked No
--include-unauthenticated IncludeUnauthenticated No
--include-trash IncludeTrash No
--senders string[] No Filter to threads whose senders contain this value (substring match). Repeatable; all values must match.
--recipients string[] No Filter to threads whose recipients contain this value (substring match). Repeatable; all values must match.
--subject string[] No Filter to threads whose subject contains this value (substring match). Repeatable; all values must match.

agentmail inboxes threads search

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.

GET /v0/inboxes/{inbox_id}/threads/search

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--q Query Yes
--limit Limit No
--page-token PageToken No
--before Before No
--after After No

agentmail inboxes threads update

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.

PATCH /v0/inboxes/{inbox_id}/threads/{thread_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--thread-id ThreadId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail inboxes webhooks

agentmail inboxes webhooks create

Create a webhook scoped to this inbox.

CLI:

agentmail inboxes webhooks create --inbox-id <inbox_id> --url https://example.com/webhook --event-types message.received

POST /v0/inboxes/{inbox_id}/webhooks

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail inboxes webhooks delete

CLI:

agentmail inboxes webhooks delete --inbox-id <inbox_id> --webhook-id <webhook_id>

DELETE /v0/inboxes/{inbox_id}/webhooks/{webhook_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--webhook-id webhooksWebhookId Yes

agentmail inboxes webhooks get

CLI:

agentmail inboxes webhooks get --inbox-id <inbox_id> --webhook-id <webhook_id>

GET /v0/inboxes/{inbox_id}/webhooks/{webhook_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--webhook-id webhooksWebhookId Yes

agentmail inboxes webhooks get-headers

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

GET /v0/inboxes/{inbox_id}/webhooks/{webhook_id}/headers

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--webhook-id webhooksWebhookId Yes

agentmail inboxes webhooks list

CLI:

agentmail inboxes webhooks list --inbox-id <inbox_id>

GET /v0/inboxes/{inbox_id}/webhooks

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--limit Limit No
--page-token PageToken No
--ascending Ascending No

agentmail inboxes webhooks update

CLI:

agentmail inboxes webhooks update --inbox-id <inbox_id> --webhook-id <webhook_id> --event-types message.received

PATCH /v0/inboxes/{inbox_id}/webhooks/{webhook_id}

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--webhook-id webhooksWebhookId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail inboxes webhooks update-headers

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

PATCH /v0/inboxes/{inbox_id}/webhooks/{webhook_id}/headers

Flag Type Required Description
--inbox-id inboxesInboxId Yes
--webhook-id webhooksWebhookId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail lists

agentmail lists create

CLI:

agentmail lists create --direction <direction> --type <type> --entry user@example.com

POST /v0/lists/{direction}/{type}

Flag Type Required Description
--direction Direction Yes
--type ListType Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail lists delete

CLI:

agentmail lists delete --direction <direction> --type <type> --entry <entry>

DELETE /v0/lists/{direction}/{type}/{entry}

Flag Type Required Description
--direction Direction Yes
--type ListType Yes
--entry string Yes Email address or domain.

agentmail lists get

CLI:

agentmail lists get --direction <direction> --type <type> --entry <entry>

GET /v0/lists/{direction}/{type}/{entry}

Flag Type Required Description
--direction Direction Yes
--type ListType Yes
--entry string Yes Email address or domain.

agentmail lists list

CLI:

agentmail lists list --direction <direction> --type <type>

GET /v0/lists/{direction}/{type}

Flag Type Required Description
--direction Direction Yes
--type ListType Yes
--limit Limit No
--page-token PageToken No

agentmail metrics

agentmail metrics query-events

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:

agentmail metrics query-events

GET /v0/metrics/events

Flag Type Required Description
--event-types MetricEventTypes No
--start Start No
--end End No
--period Period No
--limit MetricLimit No
--descending Descending No

agentmail metrics query-rates

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:

agentmail metrics query-rates

GET /v0/metrics/rates

Flag Type Required Description
--rate-types RateTypes No
--start Start No
--end End No
--period RatePeriod No
--window Window No
--limit MetricLimit No
--descending Descending No

agentmail metrics query-usage

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.

GET /v0/metrics/usage

Flag Type Required Description
--usage-types UsageTypes No
--start Start No
--end End No
--period Period No
--limit MetricLimit No
--descending Descending No

agentmail organizations

agentmail organizations get

Returns the organization for the authenticated API key (usage limits, counts, and billing metadata).

CLI:

agentmail organizations get

GET /v0/organizations

agentmail pods

agentmail pods create

CLI:

agentmail pods create --client-id my-pod

POST /v0/pods

Flag Type Required Description
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail pods delete

CLI:

agentmail pods delete --pod-id <pod_id>

DELETE /v0/pods/{pod_id}

Flag Type Required Description
--pod-id podsPodId Yes

agentmail pods get

CLI:

agentmail pods get --pod-id <pod_id>

GET /v0/pods/{pod_id}

Flag Type Required Description
--pod-id podsPodId Yes

agentmail pods list

CLI:

agentmail pods list

GET /v0/pods

Flag Type Required Description
--limit Limit No
--page-token PageToken No
--ascending Ascending No

agentmail pods accounts

agentmail pods accounts get

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

GET /v0/pods/{pod_id}/accounts/{account_id}

Flag Type Required Description
--pod-id podsPodId Yes
--account-id AccountId Yes

agentmail pods accounts list

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

GET /v0/pods/{pod_id}/accounts

Flag Type Required Description
--pod-id podsPodId Yes
--limit Limit No
--page-token PageToken No
--ascending Ascending No

agentmail pods api-keys

agentmail pods api-keys create

CLI:

agentmail pods api-keys create --pod-id <pod_id> --name "My Key"

POST /v0/pods/{pod_id}/api-keys

Flag Type Required Description
--pod-id podsPodId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail pods api-keys delete

CLI:

agentmail pods api-keys delete --pod-id <pod_id> --api-key-id <api_key_id>

DELETE /v0/pods/{pod_id}/api-keys/{api_key_id}

Flag Type Required Description
--pod-id podsPodId Yes
--api-key-id ApiKeyId Yes

agentmail pods api-keys list

CLI:

agentmail pods api-keys list --pod-id <pod_id>

GET /v0/pods/{pod_id}/api-keys

Flag Type Required Description
--pod-id podsPodId Yes
--limit Limit No
--page-token PageToken No

agentmail pods api-keys update

CLI:

agentmail pods api-keys update --pod-id <pod_id> --api-key-id <api_key_id> --name "Renamed"

PATCH /v0/pods/{pod_id}/api-keys/{api_key_id}

Flag Type Required Description
--pod-id podsPodId Yes
--api-key-id ApiKeyId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail pods domains

agentmail pods domains create

CLI:

agentmail pods domains create --pod-id <pod_id> --domain example.com

POST /v0/pods/{pod_id}/domains

Flag Type Required Description
--pod-id podsPodId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail pods domains delete

CLI:

agentmail pods domains delete --pod-id <pod_id> --domain-id <domain_id>

DELETE /v0/pods/{pod_id}/domains/{domain_id}

Flag Type Required Description
--pod-id podsPodId Yes
--domain-id DomainId Yes

agentmail pods domains get

CLI:

agentmail pods domains get --pod-id <pod_id> --domain-id <domain_id>

GET /v0/pods/{pod_id}/domains/{domain_id}

Flag Type Required Description
--pod-id podsPodId Yes
--domain-id DomainId Yes

agentmail pods domains get-zone-file

CLI:

agentmail pods domains get-zone-file --pod-id <pod_id> --domain-id <domain_id>

GET /v0/pods/{pod_id}/domains/{domain_id}/zone-file

Flag Type Required Description
--pod-id podsPodId Yes
--domain-id DomainId Yes

agentmail pods domains list

CLI:

agentmail pods domains list --pod-id <pod_id>

GET /v0/pods/{pod_id}/domains

Flag Type Required Description
--pod-id podsPodId Yes
--limit Limit No
--page-token PageToken No
--ascending Ascending No

agentmail pods domains update

CLI:

agentmail pods domains update --pod-id <pod_id> --domain-id <domain_id>

PATCH /v0/pods/{pod_id}/domains/{domain_id}

Flag Type Required Description
--pod-id podsPodId Yes
--domain-id DomainId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail pods domains verify

CLI:

agentmail pods domains verify --pod-id <pod_id> --domain-id <domain_id>

POST /v0/pods/{pod_id}/domains/{domain_id}/verify

Flag Type Required Description
--pod-id podsPodId Yes
--domain-id DomainId Yes

agentmail pods drafts

agentmail pods drafts get

CLI:

agentmail pods drafts get --pod-id <pod_id> --draft-id <draft_id>

GET /v0/pods/{pod_id}/drafts/{draft_id}

Flag Type Required Description
--pod-id podsPodId Yes
--draft-id DraftId Yes

agentmail pods drafts get-attachment

CLI:

agentmail pods drafts get-attachment --pod-id <pod_id> --draft-id <draft_id> --attachment-id <attachment_id>

GET /v0/pods/{pod_id}/drafts/{draft_id}/attachments/{attachment_id}

Flag Type Required Description
--pod-id podsPodId Yes
--draft-id DraftId Yes
--attachment-id AttachmentId Yes

agentmail pods drafts list

CLI:

agentmail pods drafts list --pod-id <pod_id>

GET /v0/pods/{pod_id}/drafts

Flag Type Required Description
--pod-id podsPodId Yes
--limit Limit No
--page-token PageToken No
--labels Labels No
--before Before No
--after After No
--ascending Ascending No

agentmail pods inboxes

agentmail pods inboxes create

CLI:

agentmail pods inboxes create --pod-id <pod_id> --username myagent --domain example.com

POST /v0/pods/{pod_id}/inboxes

Flag Type Required Description
--pod-id podsPodId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail pods inboxes delete

CLI:

agentmail pods inboxes delete --pod-id <pod_id> --inbox-id <inbox_id>

DELETE /v0/pods/{pod_id}/inboxes/{inbox_id}

Flag Type Required Description
--pod-id podsPodId Yes
--inbox-id inboxesInboxId Yes

agentmail pods inboxes get

CLI:

agentmail pods inboxes get --pod-id <pod_id> --inbox-id <inbox_id>

GET /v0/pods/{pod_id}/inboxes/{inbox_id}

Flag Type Required Description
--pod-id podsPodId Yes
--inbox-id inboxesInboxId Yes

agentmail pods inboxes list

CLI:

agentmail pods inboxes list --pod-id <pod_id>

GET /v0/pods/{pod_id}/inboxes

Flag Type Required Description
--pod-id podsPodId Yes
--limit Limit No
--page-token PageToken No
--ascending Ascending No

agentmail pods inboxes search

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.

GET /v0/pods/{pod_id}/inboxes/search

Flag Type Required Description
--pod-id podsPodId Yes
--q string Yes Address or display name to search for. Matches word prefixes. Must be 2 to 256 characters.
--limit Limit No
--page-token PageToken No

agentmail pods inboxes update

CLI:

agentmail pods inboxes update --pod-id <pod_id> --inbox-id <inbox_id>

PATCH /v0/pods/{pod_id}/inboxes/{inbox_id}

Flag Type Required Description
--pod-id podsPodId Yes
--inbox-id inboxesInboxId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail pods lists

agentmail pods lists create

CLI:

agentmail pods lists create --pod-id <pod_id> --direction <direction> --type <type> --entry user@example.com

POST /v0/pods/{pod_id}/lists/{direction}/{type}

Flag Type Required Description
--pod-id podsPodId Yes
--direction Direction Yes
--type ListType Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail pods lists delete

CLI:

agentmail pods lists delete --pod-id <pod_id> --direction <direction> --type <type> --entry <entry>

DELETE /v0/pods/{pod_id}/lists/{direction}/{type}/{entry}

Flag Type Required Description
--pod-id podsPodId Yes
--direction Direction Yes
--type ListType Yes
--entry string Yes Email address or domain.

agentmail pods lists get

CLI:

agentmail pods lists get --pod-id <pod_id> --direction <direction> --type <type> --entry <entry>

GET /v0/pods/{pod_id}/lists/{direction}/{type}/{entry}

Flag Type Required Description
--pod-id podsPodId Yes
--direction Direction Yes
--type ListType Yes
--entry string Yes Email address or domain.

agentmail pods lists list

CLI:

agentmail pods lists list --pod-id <pod_id> --direction <direction> --type <type>

GET /v0/pods/{pod_id}/lists/{direction}/{type}

Flag Type Required Description
--pod-id podsPodId Yes
--direction Direction Yes
--type ListType Yes
--limit Limit No
--page-token PageToken No

agentmail pods metrics

agentmail pods metrics query-events

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:

agentmail pods metrics query-events --pod-id <pod_id>

GET /v0/pods/{pod_id}/metrics/events

Flag Type Required Description
--pod-id podsPodId Yes
--event-types MetricEventTypes No
--start Start No
--end End No
--period Period No
--limit MetricLimit No
--descending Descending No

agentmail pods metrics query-rates

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:

agentmail pods metrics query-rates --pod-id <pod_id>

GET /v0/pods/{pod_id}/metrics/rates

Flag Type Required Description
--pod-id podsPodId Yes
--rate-types RateTypes No
--start Start No
--end End No
--period RatePeriod No
--window Window No
--limit MetricLimit No
--descending Descending No

agentmail pods metrics query-usage

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.

GET /v0/pods/{pod_id}/metrics/usage

Flag Type Required Description
--pod-id podsPodId Yes
--usage-types UsageTypes No
--start Start No
--end End No
--period Period No
--limit MetricLimit No
--descending Descending No

agentmail pods threads

agentmail pods threads delete

Permanently deletes a thread and all of its messages.

CLI:

agentmail pods threads delete --pod-id <pod_id> --thread-id <thread_id>

DELETE /v0/pods/{pod_id}/threads/{thread_id}

Flag Type Required Description
--pod-id podsPodId Yes
--thread-id ThreadId Yes

agentmail pods threads get

CLI:

agentmail pods threads get --pod-id <pod_id> --thread-id <thread_id>

GET /v0/pods/{pod_id}/threads/{thread_id}

Flag Type Required Description
--pod-id podsPodId Yes
--thread-id ThreadId Yes
--limit Limit No Maximum number of messages to return. Cannot exceed 100.
--page-token PageToken No Token returned by the previous response for retrieving the next, older page.

agentmail pods threads get-attachment

CLI:

agentmail pods threads get-attachment --pod-id <pod_id> --thread-id <thread_id> --attachment-id <attachment_id>

GET /v0/pods/{pod_id}/threads/{thread_id}/attachments/{attachment_id}

Flag Type Required Description
--pod-id podsPodId Yes
--thread-id ThreadId Yes
--attachment-id AttachmentId Yes

agentmail pods threads list

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:

agentmail pods threads list --pod-id <pod_id>

GET /v0/pods/{pod_id}/threads

Flag Type Required Description
--pod-id podsPodId Yes
--limit Limit No
--page-token PageToken No
--labels Labels No
--before Before No
--after After No
--ascending Ascending No
--include-spam IncludeSpam No
--include-blocked IncludeBlocked No
--include-unauthenticated IncludeUnauthenticated No
--include-trash IncludeTrash No
--senders string[] No Filter to threads whose senders contain this value (substring match). Repeatable; all values must match.
--recipients string[] No Filter to threads whose recipients contain this value (substring match). Repeatable; all values must match.
--subject string[] No Filter to threads whose subject contains this value (substring match). Repeatable; all values must match.

agentmail pods threads search

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.

GET /v0/pods/{pod_id}/threads/search

Flag Type Required Description
--pod-id podsPodId Yes
--q Query Yes
--limit Limit No
--page-token PageToken No
--before Before No
--after After No

agentmail pods threads update

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.

PATCH /v0/pods/{pod_id}/threads/{thread_id}

Flag Type Required Description
--pod-id podsPodId Yes
--thread-id ThreadId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail pods webhooks

agentmail pods webhooks create

Create a webhook scoped to this pod.

CLI:

agentmail pods webhooks create --pod-id <pod_id> --url https://example.com/webhook --event-types message.received

POST /v0/pods/{pod_id}/webhooks

Flag Type Required Description
--pod-id podsPodId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail pods webhooks delete

CLI:

agentmail pods webhooks delete --pod-id <pod_id> --webhook-id <webhook_id>

DELETE /v0/pods/{pod_id}/webhooks/{webhook_id}

Flag Type Required Description
--pod-id podsPodId Yes
--webhook-id webhooksWebhookId Yes

agentmail pods webhooks get

CLI:

agentmail pods webhooks get --pod-id <pod_id> --webhook-id <webhook_id>

GET /v0/pods/{pod_id}/webhooks/{webhook_id}

Flag Type Required Description
--pod-id podsPodId Yes
--webhook-id webhooksWebhookId Yes

agentmail pods webhooks get-headers

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

GET /v0/pods/{pod_id}/webhooks/{webhook_id}/headers

Flag Type Required Description
--pod-id podsPodId Yes
--webhook-id webhooksWebhookId Yes

agentmail pods webhooks list

CLI:

agentmail pods webhooks list --pod-id <pod_id>

GET /v0/pods/{pod_id}/webhooks

Flag Type Required Description
--pod-id podsPodId Yes
--limit Limit No
--page-token PageToken No
--ascending Ascending No

agentmail pods webhooks update

CLI:

agentmail pods webhooks update --pod-id <pod_id> --webhook-id <webhook_id> --add-inbox-ids <inbox_id>

PATCH /v0/pods/{pod_id}/webhooks/{webhook_id}

Flag Type Required Description
--pod-id podsPodId Yes
--webhook-id webhooksWebhookId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail pods webhooks update-headers

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

PATCH /v0/pods/{pod_id}/webhooks/{webhook_id}/headers

Flag Type Required Description
--pod-id podsPodId Yes
--webhook-id webhooksWebhookId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail threads

agentmail threads delete

Permanently deletes a thread and all of its messages.

CLI:

agentmail threads delete --thread-id <thread_id>

DELETE /v0/threads/{thread_id}

Flag Type Required Description
--thread-id ThreadId Yes

agentmail threads get

CLI:

agentmail threads get --thread-id <thread_id>

GET /v0/threads/{thread_id}

Flag Type Required Description
--thread-id ThreadId Yes
--limit Limit No Maximum number of messages to return. Cannot exceed 100.
--page-token PageToken No Token returned by the previous response for retrieving the next, older page.

agentmail threads get-attachment

CLI:

agentmail threads get-attachment --thread-id <thread_id> --attachment-id <attachment_id>

GET /v0/threads/{thread_id}/attachments/{attachment_id}

Flag Type Required Description
--thread-id ThreadId Yes
--attachment-id AttachmentId Yes

agentmail threads list

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:

agentmail threads list

GET /v0/threads

Flag Type Required Description
--limit Limit No
--page-token PageToken No
--labels Labels No
--before Before No
--after After No
--ascending Ascending No
--include-spam IncludeSpam No
--include-blocked IncludeBlocked No
--include-unauthenticated IncludeUnauthenticated No
--include-trash IncludeTrash No
--senders string[] No Filter to threads whose senders contain this value (substring match). Repeatable; all values must match.
--recipients string[] No Filter to threads whose recipients contain this value (substring match). Repeatable; all values must match.
--subject string[] No Filter to threads whose subject contains this value (substring match). Repeatable; all values must match.

agentmail threads search

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.

GET /v0/threads/search

Flag Type Required Description
--q Query Yes
--limit Limit No
--page-token PageToken No
--before Before No
--after After No

agentmail threads update

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.

PATCH /v0/threads/{thread_id}

Flag Type Required Description
--thread-id ThreadId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail webhooks

agentmail webhooks create

CLI:

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

POST /v0/webhooks

Flag Type Required Description
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail webhooks delete

CLI:

agentmail webhooks delete --webhook-id <webhook_id>

DELETE /v0/webhooks/{webhook_id}

Flag Type Required Description
--webhook-id webhooksWebhookId Yes

agentmail webhooks get

CLI:

agentmail webhooks get --webhook-id <webhook_id>

GET /v0/webhooks/{webhook_id}

Flag Type Required Description
--webhook-id webhooksWebhookId Yes

agentmail webhooks get-headers

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

GET /v0/webhooks/{webhook_id}/headers

Flag Type Required Description
--webhook-id webhooksWebhookId Yes

agentmail webhooks list

CLI:

agentmail webhooks list

GET /v0/webhooks

Flag Type Required Description
--limit Limit No
--page-token PageToken No
--ascending Ascending No

agentmail webhooks update

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:

agentmail webhooks update --webhook-id <webhook_id> --add-inbox-ids <inbox_id>

PATCH /v0/webhooks/{webhook_id}

Flag Type Required Description
--webhook-id webhooksWebhookId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

agentmail webhooks update-headers

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

PATCH /v0/webhooks/{webhook_id}/headers

Flag Type Required Description
--webhook-id webhooksWebhookId Yes
--json JSON Yes Request body as JSON (or use individual body-field flags)

Global flags

These flags are available on every command:

Flag Description
--dry-run Print the HTTP request without sending it
--json <JSON|-> Supply the request body as JSON (or - for stdin)
--params <JSON> Merge extra parameters as JSON
--format <json|table|yaml|csv> Output format (default: json)
--output <PATH> Write binary responses to a file
--base-url <URL> Override the API base URL
--page-all Auto-paginate and stream all results
--page-limit <N> Max pages to fetch (default: 10)
-q, --quiet Suppress stdout on success
-h, --help Print help
-V, --version Print version