Agent Mail
AgentMail provides programmable email inboxes, messages, drafts, domains, webhooks, and related infrastructure for AI agents.
Tools (94)
Batch Get Messages
Return metadata for up to 500 messages from one inbox in a single request. Compare count with limit to detect missing or restricted IDs. Source or target records with spam, blocked, unauthenticated, or trash labels may be hidden or reported not found when the API key lacks the corresponding label visibility permission.
Inputs: inbox_id, message_ids
Batch Update Message Labels
Atomically add or remove the same labels on up to 50 messages in one inbox. Missing or restricted message IDs are omitted from the result. Source or target records with spam, blocked, unauthenticated, or trash labels may be hidden or reported not found when the API key lacks the corresponding label visibility permission.
Inputs: inbox_id, add_labels, message_ids, remove_labels
Complete File Upload
Mark a pending Agent Drive file ready after its bytes have been PUT to the presigned URL returned by CREATE_FILE. AgentMail verifies the exact declared size and SHA-256; calling this before a successful upload returns a conflict. Only a key with file_read or the key that created the file can complete it. Agent Drive is a US-production-only Labs feature.
Inputs: file_id, inbox_id
Create Agent Armor Feedback
Record whether Agent Armor's completed verdict on a message was correct. A message accepts up to 20 feedback records.
Inputs: notes, feedback, inbox_id, message_id
Create Calendar Event
Create a one-off or recurring event on a US-only inbox calendar. client_id makes retries safe; send_invites emails attendees and consumes send limits.
Inputs: end, start, title, status, all_day, inbox_id, location, metadata, timezone, attendees, client_id, recurrence, description, send_invites, duration_mode
Create Draft
Create a draft, optionally scheduling its automatic delivery with send_at.
Inputs: cc, to, bcc, html, text, labels, send_at, subject, inbox_id, reply_to, client_id, reply_all, forward_of, attachments, in_reply_to
Create File
Initialize a pending Agent Drive file and return instructions for a direct storage upload. This does not upload bytes: PUT the exact bytes to the credential-sensitive presigned URL with every returned header unchanged and without the AgentMail API key, then call COMPLETE_FILE_UPLOAD. Identical requests are retry-safe. Pending files consume Drive quota immediately and expire after one day if incomplete; call DELETE_FILE when abandoning an upload. Agent Drive is a US-production-only Labs feature.
Inputs: path, size, sha256, inbox_id, expires_at, content_type
Create Inbox
Create a new AgentMail inbox via API. Returns the inbox_id and email address for sending/receiving messages. Use when provisioning new inboxes for agents or workflows. With Ittes AI-managed credentials the address is on Ittes AI.agentmail.to (for example example@Ittes AI.agentmail.to) and inbox_id is that address plus a Ittes AI signature (example@Ittes AI.agentmail.to.a1B2c3D4e5F6g). Give senders the returned email; use inbox_id only in AgentMail tool calls.
Inputs: domain, months, pod_id, username, client_id, display_name, deactivate_at
Create Inbox API Key
Create an inbox-scoped bearer key and return its one-time secret. Permissions can be specified to restrict the key.
Inputs: name, inbox_id, expires_at, permissions
Create Inbox in Pod
Create an inbox inside an explicitly selected AgentMail pod, optionally choosing its address, initial status, idempotency ID, and metadata.
Inputs: domain, pod_id, status, metadata, username, client_id, display_name
Create Inbox Polling Webhook
Create or resume a polling webhook scoped to one inbox. The inbox comes from the path, so organization selector lists are not accepted. AgentMail's polling guide currently says polling is US-only even though the API reference lists an EU server; follow the guide and do not assume EU support. The response contains a one-time credential-sensitive polling token; store it securely and never log or expose it.
Inputs: inbox_id, client_id, event_types
Create Inbox Webhook
Create a regular webhook scoped to one AgentMail inbox for a non-empty set of event types. The response contains a credential-sensitive signature secret; never log or expose it.
Inputs: url, headers, inbox_id, client_id, event_types
Create Allowlist or Blocklist Entry
Add an email address or domain to an organization-wide send, receive, or reply allowlist or blocklist.
Inputs: entry, reason, direction, list_type
Create Pod
Create an AgentMail pod for grouping inboxes and related resources. With Ittes AI-managed credentials each user has one pod: calling this again returns the same pod, and CREATE_INBOX and LIST_POD_INBOXES use it automatically when pod_id is omitted.
Inputs: name, client_id
Create Polling Webhook
Create or resume an organization-level polling webhook for a non-empty set of event types, optionally filtered to at most 10 inboxes and pods combined. Current provider polling support is US-only (api.agentmail.to); do not use this action with an EU connection. The response contains a one-time, credential-sensitive polling token; store it securely and never log or expose it.
Inputs: pod_ids, client_id, inbox_ids, event_types
Create Webhook
Create an organization-level webhook for a non-empty set of event types, optionally filtered to at most 10 inboxes and pods combined. The response contains a credential-sensitive signature secret; never log or expose it.
Inputs: url, headers, pod_ids, client_id, inbox_ids, event_types
Delete Calendar Event
Accept asynchronous deletion of a US-only calendar event or cancel recurring dates. If-Match guards the version and Idempotency-Key makes retries deterministic.
Inputs: mode, event_id, if_match, inbox_id, send_invites, idempotency_key
Delete Draft
Permanently delete one unsent draft from an inbox.
Inputs: draft_id, inbox_id
Delete File
Permanently delete a pending or ready Agent Drive file and free its path. A previously issued presigned download URL can remain valid until its expiry. Requires file_delete, and only a key with file_read or the key that created the file can delete it. Agent Drive is a US-production-only Labs feature.
Inputs: file_id, inbox_id
Delete Inbox
Permanently delete one inbox by ID. AgentMail accepts the deletion asynchronously, so acceptance does not guarantee immediate completion.
Inputs: inbox_id
Delete Inbox Polling Webhook
Permanently delete an inbox-scoped polling webhook by webhook_id or client_id, invalidate its polling token, and free its subscription slot. AgentMail's polling guide currently says polling is US-only even though the API reference lists an EU server; follow the guide and do not assume EU support.
Inputs: inbox_id, webhook_id
Delete Inbox Webhook
Permanently delete a regular webhook created for a selected AgentMail inbox and stop future deliveries.
Inputs: inbox_id, webhook_id
Delete Allowlist or Blocklist Entry
Remove one email address or domain from an organization-wide send, receive, or reply allowlist or blocklist.
Inputs: entry, direction, list_type
Delete Message
Permanently delete one message from an inbox. Source or target records with spam, blocked, unauthenticated, or trash labels may be hidden or reported not found when the API key lacks the corresponding label visibility permission.
Inputs: inbox_id, message_id
Delete Pod
Permanently delete one AgentMail pod by its unique ID.
Inputs: pod_id
Delete Pod Inbox
Permanently delete an inbox through its explicitly selected AgentMail pod, preserving the pod tenant boundary. A 202 response means deletion continues asynchronously; poll GET_POD_INBOX until it returns 404.
Inputs: pod_id, inbox_id
Delete Polling Webhook
Permanently delete an organization-level polling webhook by webhook_id or client_id, invalidate its polling token, and free its subscription slot. Current provider polling support is US-only (api.agentmail.to); do not use this action with an EU connection.
Inputs: webhook_id
Delete Thread
Permanently delete one AgentMail thread and all of its messages.
Inputs: inbox_id, thread_id
Delete Webhook
Permanently delete an organization-level webhook and stop future deliveries.
Inputs: webhook_id
Extend Inbox
Add whole months before an AgentMail inbox deactivates, or reactivate a deactivated inbox for that many months.
Inputs: months, inbox_id
Forward Message
Immediately forward an existing message to new recipients with optional added content and attachments. Source or target records with spam, blocked, unauthenticated, or trash labels may be hidden or reported not found when the API key lacks the corresponding label visibility permission.
Inputs: cc, to, bcc, html, text, labels, headers, subject, inbox_id, reply_to, message_id, attachments, track_opens
Get Agenda
Get one page of non-cancelled calendar dates in a UTC window, expanding recurring events and ordering dates by start time. Calendar is available only in US production.
Inputs: after, limit, before, inbox_id, page_token, consistency, include_overlapping
Get API Key
Retrieve API-key metadata without exposing bearer secret values.
Inputs: api_key_id
Get Calendar
Get an inbox's US-only calendar settings, event count, and ETag. Use primary consistency to read a just-completed write.
Inputs: inbox_id, consistency
Get Calendar Event
Get the full current form of a US-only calendar event or recurring-event date, including its opaque ETag for conditional mutations.
Inputs: event_id, inbox_id, consistency
Get Current Identity
Return the connected AgentMail identity and its organization, pod, or inbox access boundary without exposing the credential itself.
Get Domain
Return an AgentMail custom domain, its domain and tracking verification statuses, and all required DNS records.
Inputs: domain_id
Get Domain Setup Link
Build a one-click Domain Connect DNS setup link when supported. The returned signed URL must be delivered privately to the intended domain owner. Retain the sensitive state ephemerally and compare it on redirect; do not log either value.
Inputs: domain_id
Get Domain Zone File
Download the AgentMail-generated DNS zone file for a custom domain as a bounded binary file reference.
Inputs: domain_id
Get Draft
Retrieve the complete contents and scheduling details of one draft.
Inputs: draft_id, inbox_id
Get Draft Attachment
Get a temporary download reference for one draft attachment.
Inputs: draft_id, attachment_id
Get File
Get Agent Drive file metadata. A ready file can include a credential-sensitive presigned download URL valid for up to one hour; treat it as a secret and never log or expose it. Requires file_read. Agent Drive is a US-production-only Labs feature.
Inputs: file_id, inbox_id
Get Inbox
Retrieve one AgentMail inbox and its metadata by ID or email address.
Inputs: inbox_id
Get Inbox Polling Webhook
Get one inbox-scoped polling webhook by webhook_id or client_id. AgentMail's polling guide currently says polling is US-only even though the API reference lists an EU server; follow the guide and do not assume EU support. The polling token is never returned; create again with the same client_id to issue a new token.
Inputs: inbox_id, webhook_id
Get Inbox Webhook
Get one regular webhook created for a selected AgentMail inbox. The response contains a credential-sensitive signature secret; never log or expose it.
Inputs: inbox_id, webhook_id
Get Inbox Webhook Headers
List only the names of custom delivery headers on an inbox-scoped regular webhook. Header values are credential-sensitive, write-only, and never returned.
Inputs: inbox_id, webhook_id
Get Message
Retrieve an email message from an AgentMail inbox, including sender, recipients, labels, and available subject, body and attachment metadata. Use it to read individual messages discovered through message listing or webhooks.
Inputs: inbox_id, message_id
Get Message Attachment
Get a temporary download reference for one message attachment. Source or target records with spam, blocked, unauthenticated, or trash labels may be hidden or reported not found when the API key lacks the corresponding label visibility permission.
Inputs: inbox_id, message_id, attachment_id
Get Organization
Return the connected AgentMail organization's identifiers, current inbox and domain counts, configured resource limits, and timestamps.
Get Pod
Retrieve one AgentMail pod by its unique ID.
Inputs: pod_id
Get Pod Inbox
Get an AgentMail inbox through an explicitly selected pod, preserving the pod tenant boundary.
Inputs: pod_id, inbox_id
Get Polling Webhook
Get one organization-level polling webhook by webhook_id or client_id. Current provider polling support is US-only (api.agentmail.to); do not use this action with an EU connection. The polling token is never returned; create again with the same client_id to issue a new token.
Inputs: webhook_id
Get Raw Message
Get a temporary download reference for one message's raw RFC 5322 source, including its original headers and MIME structure. Source or target records with spam, blocked, unauthenticated, or trash labels may be hidden or reported not found when the API key lacks the corresponding label visibility permission.
Inputs: inbox_id, message_id
Get Thread
Retrieve one AgentMail thread and a paginated page of its messages.
Inputs: limit, inbox_id, thread_id, page_token
Get Thread Attachment
Get a temporary download reference for an attachment using its thread and attachment IDs. Source or target records with spam, blocked, unauthenticated, or trash labels may be hidden or reported not found when the API key lacks the corresponding label visibility permission.
Inputs: thread_id, attachment_id
Get Webhook
Get one organization-level webhook configuration by ID. The response contains a credential-sensitive signature secret; never log or expose it.
Inputs: webhook_id
Get Webhook Headers
List only the names of custom delivery headers on an organization-level webhook. Header values are credential-sensitive, write-only, and never returned.
Inputs: webhook_id
List Calendar Event Instances
List one page of non-cancelled dates computed for a recurring US-only calendar event in a UTC window, including dates beyond the agenda horizon.
Inputs: after, limit, before, event_id, inbox_id, page_token, consistency, include_overlapping
List Calendar Events
List one US-only calendar page of stored one-off events, recurring series, and edited series dates, including cancelled events, by most recent update.
Inputs: limit, inbox_id, page_token
List Domains
List one page of AgentMail custom domains and return the continuation token for the next page.
Inputs: limit, ascending, page_token
List Drafts
List unsent drafts in an AgentMail inbox with filters and pagination.
Inputs: after, limit, before, labels, inbox_id, ascending, page_token
List Files
List one page of an inbox's Agent Drive files in path order, including pending files. List items intentionally contain no presigned download URL; call GET_FILE for one. Requires file_read. Agent Drive is a US-production-only Labs feature.
Inputs: limit, inbox_id, ascending, page_token, path_prefix
List Inbox API Keys
List API-key metadata scoped to an inbox without exposing secret values.
Inputs: limit, inbox_id, page_token
List Inboxes
List a page of inboxes available to the authenticated AgentMail account. Use this to discover inbox_id values for message operations; follow the next page token to retrieve more results.
Inputs: limit, ascending, page_token
List Inbox Events
List label-change events from an AgentMail inbox.
Inputs: limit, inbox_id, ascending, page_token
List Inbox Polling Webhooks
List polling webhooks created through one inbox route. Returns one page and an endpoint- and inbox-bound opaque continuation token. AgentMail's polling guide currently says polling is US-only even though the API reference lists an EU server; follow the guide and do not assume EU support. Polling tokens are never returned.
Inputs: limit, inbox_id, ascending, page_token
List Inbox Webhooks
List one page of regular webhooks created for a selected AgentMail inbox. Responses contain credential-sensitive signature secrets; never log or expose them.
Inputs: limit, inbox_id, ascending, page_token
List Allowlist or Blocklist Entries
List one page of organization-wide send, receive, or reply allowlist or blocklist entries. Supply entry to retrieve one exact email address or domain.
Inputs: entry, limit, direction, list_type, page_token
List Messages
List messages from an AgentMail inbox. Returns a `messages` array; each message uses `message_id` and `timestamp` fields (not `id`, `date`, or `items`).
Inputs: after, limit, before, labels, inbox_id, ascending, page_token, include_spam
List Pod Inboxes
List one page of inboxes inside an AgentMail pod, or supply query to search addresses and display names. Follow next_page_token until absent, including after an empty search page. With Ittes AI-managed credentials, omit pod_id to list your own pod. That call first gets your pod the same way AGENT_MAIL_CREATE_POD does, so it creates your one pod if you don't have it yet (free, never a second pod). Each returned inbox carries its signed inbox_id and pod_id, which work in the other AgentMail tools.
Inputs: limit, query, pod_id, ascending, page_token
List Pods
Return one page of AgentMail pods and its continuation token.
Inputs: limit, ascending, page_token
List Polling Webhooks
List organization-level polling webhooks created through the organization route. Returns one page and an endpoint-bound opaque continuation token. Current provider polling support is US-only (api.agentmail.to); do not use this action with an EU connection. Polling tokens are never returned.
Inputs: limit, ascending, page_token
List Threads
List conversation threads in an AgentMail inbox with filters.
Inputs: after, limit, before, labels, senders, subject, inbox_id, ascending, page_token, recipients, include_spam, include_trash, include_blocked, include_unauthenticated
List Webhooks
List AgentMail webhook configurations.
Inputs: limit, ascending, page_token
Query Inbox Event Metrics
Query timestamped email-event counts for an AgentMail inbox.
Inputs: end, limit, start, period, inbox_id, descending, event_types
Query Metrics
Query organization-wide email event counts or cumulative resource-usage time series over a bounded time range.
Inputs: end, limit, start, period, descending, event_types, metric_kind, usage_types
Query Rate Metrics
Query organization-wide rolling bounce and complaint rates.
Inputs: end, limit, start, period, window, descending, rate_types
Release Held Message
Release a message that Agent Armor held for review, emit its delivery and security override events, and remove the agent-armor-held label. Only a still-held message with a review verdict can be released.
Inputs: reason, inbox_id, message_id
Reply To Message
Reply to a selected message while preserving its AgentMail thread.
Inputs: cc, to, bcc, html, text, labels, headers, inbox_id, reply_to, reply_all, message_id, attachments, track_opens
Respond to Calendar Event
Accept, decline, or tentatively accept an email invitation on a US-only inbox calendar. By default AgentMail emails the organizer; If-Match guards the response.
Inputs: status, comment, event_id, if_match, inbox_id, send_reply
Send Draft
Immediately send and consume a draft, optionally changing message labels.
Inputs: draft_id, inbox_id, add_labels, remove_labels
Send Email
Send an email using AgentMail API
Inputs: cc, to, bcc, html, text, labels, subject, inbox_id, reply_to
Send Message
Immediately send a new email from an AgentMail inbox with optional HTML, attachments, custom headers, labels, and open tracking. Use a draft instead when the message must be scheduled for later.
Inputs: cc, to, bcc, html, text, labels, headers, subject, inbox_id, reply_to, attachments, track_opens
Update Calendar
Change an inbox calendar's default time zone in US production. Existing events retain their own time zones; optionally guard the update with If-Match.
Inputs: if_match, inbox_id, timezone
Update Calendar Event
Patch a US-only calendar event, one recurring date, or that date and future dates. Explicit null clears only documented nullable fields; If-Match prevents overwrites.
Inputs: end, mode, start, title, status, all_day, event_id, if_match, inbox_id, location, metadata, timezone, attendees, recurrence, description, send_invites, duration_mode
Update Draft
Edit a draft, reschedule delivery with send_at, or cancel a scheduled send with cancel_scheduled_send=true.
Inputs: cc, to, bcc, html, text, send_at, subject, draft_id, inbox_id, reply_to, add_labels, remove_labels, add_attachments, remove_attachments, cancel_scheduled_send
Update Inbox
Update an inbox's display name, status, or custom metadata.
Inputs: status, inbox_id, metadata, display_name
Update Inbox Webhook
Update an inbox-scoped regular webhook's enabled state or replace its event types. An empty update is allowed. The response contains a credential-sensitive signature secret; never log or expose it.
Inputs: enabled, inbox_id, webhook_id, event_types
Update Inbox Webhook Headers
Atomically set, replace, or remove custom delivery headers on an inbox-scoped regular webhook. At least one real header change is required. Header values are credential-sensitive and write-only; never log or expose them.
Inputs: headers, inbox_id, webhook_id, remove_headers
Update Message Labels
Add or remove labels from one message in an inbox. Source or target records with spam, blocked, unauthenticated, or trash labels may be hidden or reported not found when the API key lacks the corresponding label visibility permission.
Inputs: inbox_id, add_labels, message_id, remove_labels
Update Pod Inbox
Update the display name, active or paused status, or metadata of an inbox inside an explicitly selected AgentMail pod. Provide at least one field.
Inputs: pod_id, status, inbox_id, metadata, display_name
Update Thread Labels
Add or remove custom labels from every message in one thread. Source or target records with spam, blocked, unauthenticated, or trash labels may be hidden or reported not found when the API key lacks the corresponding label visibility permission.
Inputs: thread_id, add_labels, remove_labels
Update Webhook
Update an organization-level webhook's enabled state, event types, or inbox and pod subscriptions. An empty update is allowed. The response contains a credential-sensitive signature secret; never log or expose it.
Inputs: enabled, webhook_id, add_pod_ids, event_types, add_inbox_ids, remove_pod_ids, remove_inbox_ids
Update Webhook Headers
Atomically set, replace, or remove custom delivery headers on an organization-level webhook. At least one real header change is required. Header values are credential-sensitive and write-only; never log or expose them.
Inputs: headers, webhook_id, remove_headers