AgentMail
App · 20 actions
Give AI agents their own email inboxes: create inboxes, send, reply to and forward email, read and search messages and threads, label mail, and write and schedule drafts.
Actions
| Action | What it does |
|---|---|
| Create draft | Save an email as a draft to review or send later - a new email, a reply or a forward. |
| Create inbox | Create a new email inbox, such as support-agent@agentmail.to. |
| Delete draft | Delete a draft without sending it. |
| Delete inbox | Permanently delete an inbox and all of its mail. |
| Delete thread | Permanently delete a thread and every message in it. |
| Forward message | Forward a message to new recipients, optionally with a note of your own above it. |
| Get inbox | Read one inbox: its address, display name, status and metadata. |
| Get message | Read one message in full: sender, recipients, subject, text and HTML body, and the new text of a reply without the quoted history. |
| Get thread | Read a conversation with its messages in full, oldest first. |
| List inboxes | List the account's inboxes with their email address, display name, status and metadata. |
| List messages | List an inbox's messages, newest first, filtered by label, sender, recipient, subject or date. |
| List threads | List an inbox's conversations (threads), most recent first, filtered by label, sender, recipient, subject or date. |
| Reply to message | Reply to a message in its thread. |
| Search messages | Full-text search across an inbox's messages, best matches first. |
| Send draft | Send a draft now. |
| Send email | Send a new email from an inbox. |
| Update draft | Change a draft's recipients, subject, body, labels or scheduled time. |
| Update inbox | Change an inbox's display name, pause or resume it, or change its metadata. |
| Update message labels | Add or remove labels on a message - for example add 'read' and remove 'unread' to mark it read. |
| Update thread labels | Add or remove labels on a whole thread. |
Create draft
Save an email as a draft to review or send later - a new email, a reply or a forward. Set Send at to schedule it.
Inputs
- Inbox
inbox_idtextRequired - The inbox, which is identified by its email address.
- To
tolist - Recipient email addresses, such as ada@example.com.
- Subject
subjecttext - The subject line.
- Text
texttext - The plain-text body.
- HTML
htmltext - An HTML body. Give Text as well so every mail app can show it.
- CC
cclist - Email addresses to copy.
- BCC
bcclist - Email addresses to blind-copy.
- Reply-to
reply_tolist - Where replies should go, if not to this inbox.
- Labels
labelslist - Labels to attach, such as 'follow-up'.
- Reply to message ID
in_reply_totext - Make the draft a reply to this message.
- Forward message ID
forward_oftext - Make the draft a forward of this message.
- Reply to everyone
reply_alltrue/false - With Reply to message ID, address the reply to everyone on that message. Leave To, CC and BCC empty.
- Send at
send_atdate and time - Schedule the draft to send itself at this time.
Outputs
attachmentslistbcclistcclistclient_idtextcreated_attextdraft_idtextforward_oftexthtmltextin_reply_totextinbox_idtextlabelslistpreviewtextreferenceslistreply_tolistsend_attextsend_statustextsubjecttexttexttexttolistupdated_attext
Example output
{
"attachments": [],
"bcc": [],
"cc": [],
"client_id": null,
"created_at": "2026-10-02T11:00:00Z",
"draft_id": "drf_1",
"forward_of": null,
"html": null,
"in_reply_to": null,
"inbox_id": "support-agent@agentmail.to",
"labels": [
"draft"
],
"preview": null,
"references": [],
"reply_to": [],
"send_at": null,
"send_status": null,
"subject": "Your order",
"text": "It ships tomorrow.",
"to": [
"ada@example.com"
],
"updated_at": "2026-10-02T11:00:00Z"
}Create inbox
Create a new email inbox, such as support-agent@agentmail.to. Returns the inbox, whose id is its email address.
Inputs
- Username
usernametext - The part before the @, such as 'support-agent'. Leave empty for a random one.
- Domain
domaintext - Leave empty for agentmail.to, the only domain on the free plan. A custom domain must be verified in AgentMail first.
- Display name
display_nametext - The sender name recipients see, such as 'Support Agent'.
- Status
statustext - Active or paused. A paused inbox cannot send, and mail sent to it while paused is dropped - it is not delivered when the inbox resumes.One of:
active,paused(Paused (stops receiving mail)). - Metadata
metadataobject - Your own keys and values to keep on the inbox, such as team: sales. Values are text, numbers or true/false.
Outputs
client_idtextcreated_attextdisplay_nametextemailtextinbox_idtextmetadataobjectpod_idtextstatustextupdated_attext
Example output
{
"client_id": "lodol-0f1e",
"created_at": "2026-10-01T09:00:00Z",
"display_name": "Support Agent",
"email": "support-agent@agentmail.to",
"inbox_id": "support-agent@agentmail.to",
"metadata": {
"team": "support"
},
"pod_id": "pod_1",
"status": "active",
"updated_at": "2026-10-01T09:00:00Z"
}Delete draft
Delete a draft without sending it.
Inputs
- Inbox
inbox_idtextRequired - The inbox, which is identified by its email address.
- Draft ID
draft_idtextRequired - The 'draft_id' of a Create draft result.
Outputs
deletedtrue/falseidtexttypetext
Example output
{
"deleted": true,
"id": "drf_1",
"type": "draft"
}Delete inbox
Permanently delete an inbox and all of its mail. This cannot be undone.
Inputs
- Inbox
inbox_idtextRequired - The inbox, which is identified by its email address.
Outputs
deletedtrue/falseidtexttypetext
Example output
{
"deleted": true,
"id": "support-agent@agentmail.to",
"type": "inbox"
}Delete thread
Permanently delete a thread and every message in it.
Inputs
- Inbox
inbox_idtextRequired - The inbox, which is identified by its email address.
- Thread ID
thread_idtextRequired - The 'thread_id' of a List threads, List messages or send result.
Outputs
deletedtrue/falseidtexttypetext
Example output
{
"deleted": true,
"id": "thr_1",
"type": "thread"
}Forward message
Forward a message to new recipients, optionally with a note of your own above it.
Inputs
- Inbox
inbox_idtextRequired - The inbox, which is identified by its email address.
- Message ID
message_idtextRequired - The message's id, such as <abc123@agentmail.to> - the 'message_id' of a List messages, Search messages or Send email result.
- To
tolistRequired - Recipient email addresses, such as ada@example.com or Ada Lovelace <ada@example.com>.
- Subject
subjecttext - Leave empty to use 'Fwd:' and the original subject.
- Text
texttext - A note to add above the forwarded message.
- HTML
htmltext - An HTML body. Give Text as well so every mail app can show it.
- CC
cclist - Email addresses to copy.
- BCC
bcclist - Email addresses to blind-copy.
- Labels
labelslist - Labels to attach, such as 'follow-up'.
Outputs
inbox_idtextmessage_idtextthread_idtext
Example output
{
"inbox_id": "support-agent@agentmail.to",
"message_id": "<def456@agentmail.to>",
"thread_id": "thr_1"
}Get inbox
Read one inbox: its address, display name, status and metadata.
Inputs
- Inbox
inbox_idtextRequired - The inbox, which is identified by its email address.
Outputs
client_idtextcreated_attextdisplay_nametextemailtextinbox_idtextmetadataobjectpod_idtextstatustextupdated_attext
Example output
{
"client_id": "lodol-0f1e",
"created_at": "2026-10-01T09:00:00Z",
"display_name": "Support Agent",
"email": "support-agent@agentmail.to",
"inbox_id": "support-agent@agentmail.to",
"metadata": {
"team": "support"
},
"pod_id": "pod_1",
"status": "active",
"updated_at": "2026-10-01T09:00:00Z"
}Get message
Read one message in full: sender, recipients, subject, text and HTML body, and the new text of a reply without the quoted history.
Inputs
- Inbox
inbox_idtextRequired - The inbox, which is identified by its email address.
- Message ID
message_idtextRequired - The message's id, such as <abc123@agentmail.to> - the 'message_id' of a List messages, Search messages or Send email result.
Outputs
attachmentslistbcclistcclistcreated_attextextracted_htmltextextracted_texttextfromtexthtmltextin_reply_totextinbox_idtextlabelslistmessage_idtextpreviewtextreferenceslistreply_tolistsizenumbersubjecttexttexttextthread_idtexttimestamptexttolistupdated_attext
Example output
{
"attachments": [],
"bcc": [],
"cc": [],
"created_at": "2026-10-02T10:00:00Z",
"extracted_html": null,
"extracted_text": "Where is my order?",
"from": "Ada Lovelace <ada@example.com>",
"html": "<p>Where is my order?</p>",
"in_reply_to": null,
"inbox_id": "support-agent@agentmail.to",
"labels": [
"received",
"unread"
],
"message_id": "<abc123@agentmail.to>",
"preview": "Where is my order?",
"references": [],
"reply_to": [],
"size": 1200,
"subject": "Order status",
"text": "Where is my order?",
"thread_id": "thr_1",
"timestamp": "2026-10-02T10:00:00Z",
"to": [
"support-agent@agentmail.to"
],
"updated_at": "2026-10-02T10:00:00Z"
}Get thread
Read a conversation with its messages in full, oldest first. A long thread returns its newest messages; use the page token for older ones.
Inputs
- Inbox
inbox_idtextRequired - The inbox, which is identified by its email address.
- Thread ID
thread_idtextRequired - The 'thread_id' of a List threads, List messages or send result.
- Messages
limitnumber - How many messages to return, up to 100.From 1 to 100.
- Page token
page_tokentext - The 'next_page_token' of the previous result, for older messages.
Outputs
attachmentslistcountnumbercreated_attextinbox_idtextlabelslistlast_message_idtextmessage_countnumbermessageslist- The newest page of messages, oldest first
next_page_tokentextpreviewtextreceived_timestamptextrecipientslistsenderslistsent_timestamptextsizenumbersubjecttextthread_idtexttimestamptextupdated_attext
Example output
{
"attachments": [],
"count": 1,
"created_at": "2026-10-02T10:00:00Z",
"inbox_id": "support-agent@agentmail.to",
"labels": [
"received"
],
"last_message_id": "<abc123@agentmail.to>",
"message_count": 1,
"messages": [
{
"attachments": [],
"bcc": [],
"cc": [],
"created_at": "2026-10-02T10:00:00Z",
"extracted_html": null,
"extracted_text": "Where is my order?",
"from": "Ada Lovelace <ada@example.com>",
"html": "<p>Where is my order?</p>",
"in_reply_to": null,
"inbox_id": "support-agent@agentmail.to",
"labels": [
"received",
"unread"
],
"message_id": "<abc123@agentmail.to>",
"preview": "Where is my order?",
"references": [],
"reply_to": [],
"size": 1200,
"subject": "Order status",
"text": "Where is my order?",
"thread_id": "thr_1",
"timestamp": "2026-10-02T10:00:00Z",
"to": [
"support-agent@agentmail.to"
],
"updated_at": "2026-10-02T10:00:00Z"
}
],
"next_page_token": null,
"preview": "Where is my order?",
"received_timestamp": "2026-10-02T10:00:00Z",
"recipients": [
"support-agent@agentmail.to"
],
"senders": [
"ada@example.com"
],
"sent_timestamp": null,
"size": 1200,
"subject": "Order status",
"thread_id": "thr_1",
"timestamp": "2026-10-02T10:00:00Z",
"updated_at": "2026-10-02T10:00:00Z"
}List inboxes
List the account's inboxes with their email address, display name, status and metadata.
Inputs
- Order
ordertext - Defaults to newest first.One of:
newest(Newest first),oldest(Oldest first). - Limit
limitnumber - How many to return, up to 100.From 1 to 100.
- Page token
page_tokentext - The 'next_page_token' of the previous result, for the next page.
Outputs
countnumberitemslist- The inboxes
next_page_tokentext
Example output
{
"count": 1,
"items": [
{
"client_id": "lodol-0f1e",
"created_at": "2026-10-01T09:00:00Z",
"display_name": "Support Agent",
"email": "support-agent@agentmail.to",
"inbox_id": "support-agent@agentmail.to",
"metadata": {
"team": "support"
},
"pod_id": "pod_1",
"status": "active",
"updated_at": "2026-10-01T09:00:00Z"
}
],
"next_page_token": null
}List messages
List an inbox's messages, newest first, filtered by label, sender, recipient, subject or date. Returns each message's sender, recipients, subject and preview; use Get message for the full body.
Inputs
- Inbox
inbox_idtextRequired - The inbox, which is identified by its email address.
- Labels
labelslist - Only items carrying every one of these labels, such as 'unread'.
- From contains
from_containslist - Only messages whose sender contains this text.
- To contains
to_containslist - Only messages whose To, CC or BCC contains this text.
- Subject contains
subject_containslist - Only messages whose subject contains this text.
- After
afterdate and time - Only items from after this time.
- Before
beforedate and time - Only items from before this time.
- Include spam
include_spamtrue/false - Also include mail marked as spam.
- Include trash
include_trashtrue/false - Also include mail in the trash.
- Order
ordertext - Defaults to newest first.One of:
newest(Newest first),oldest(Oldest first). - Limit
limitnumber - How many to return, up to 100.From 1 to 100.
- Page token
page_tokentext - The 'next_page_token' of the previous result, for the next page.
Outputs
countnumberitemslist- The matching messages
next_page_tokentext
Example output
{
"count": 1,
"items": [
{
"attachments": [],
"bcc": [],
"cc": [],
"created_at": "2026-10-02T10:00:00Z",
"from": "Ada Lovelace <ada@example.com>",
"in_reply_to": null,
"inbox_id": "support-agent@agentmail.to",
"labels": [
"received",
"unread"
],
"message_id": "<abc123@agentmail.to>",
"preview": "Where is my order?",
"references": [],
"size": 1200,
"subject": "Order status",
"thread_id": "thr_1",
"timestamp": "2026-10-02T10:00:00Z",
"to": [
"support-agent@agentmail.to"
],
"updated_at": "2026-10-02T10:00:00Z"
}
],
"next_page_token": null
}List threads
List an inbox's conversations (threads), most recent first, filtered by label, sender, recipient, subject or date.
Inputs
- Inbox
inbox_idtextRequired - The inbox, which is identified by its email address.
- Labels
labelslist - Only items carrying every one of these labels, such as 'unread'.
- Senders contain
senderslist - Only threads with a sender containing this text.
- Recipients contain
recipientslist - Only threads with a recipient containing this text.
- Subject contains
subject_containslist - Only threads whose subject contains this text.
- After
afterdate and time - Only items from after this time.
- Before
beforedate and time - Only items from before this time.
- Include spam
include_spamtrue/false - Also include mail marked as spam.
- Include trash
include_trashtrue/false - Also include mail in the trash.
- Order
ordertext - Defaults to newest first.One of:
newest(Newest first),oldest(Oldest first). - Limit
limitnumber - How many to return, up to 100.From 1 to 100.
- Page token
page_tokentext - The 'next_page_token' of the previous result, for the next page.
Outputs
countnumberitemslist- The matching threads
next_page_tokentext
Example output
{
"count": 1,
"items": [
{
"attachments": [],
"created_at": "2026-10-02T10:00:00Z",
"inbox_id": "support-agent@agentmail.to",
"labels": [
"received"
],
"last_message_id": "<abc123@agentmail.to>",
"message_count": 1,
"preview": "Where is my order?",
"received_timestamp": "2026-10-02T10:00:00Z",
"recipients": [
"support-agent@agentmail.to"
],
"senders": [
"ada@example.com"
],
"sent_timestamp": null,
"size": 1200,
"subject": "Order status",
"thread_id": "thr_1",
"timestamp": "2026-10-02T10:00:00Z",
"updated_at": "2026-10-02T10:00:00Z"
}
],
"next_page_token": null
}Reply to message
Reply to a message in its thread. It goes to the original sender unless you name recipients, or to everyone on the message with Reply to everyone. The subject is taken from the original.
Inputs
- Inbox
inbox_idtextRequired - The inbox, which is identified by its email address.
- Message ID
message_idtextRequired - The message's id, such as <abc123@agentmail.to> - the 'message_id' of a List messages, Search messages or Send email result.
- Text
texttext - The plain-text body.
- HTML
htmltext - An HTML body. Give Text as well so every mail app can show it.
- Reply to everyone
reply_alltrue/false - Send to the sender and everyone else on the message. Leave To, CC and BCC empty when ticked.
- To
tolist - Send to these instead of the original sender.
- CC
cclist - Email addresses to copy.
- BCC
bcclist - Email addresses to blind-copy.
- Reply-to
reply_tolist - Where replies should go, if not to this inbox.
- Labels
labelslist - Labels to attach, such as 'follow-up'.
Outputs
inbox_idtextmessage_idtextthread_idtext
Example output
{
"inbox_id": "support-agent@agentmail.to",
"message_id": "<def456@agentmail.to>",
"thread_id": "thr_1"
}Search messages
Full-text search across an inbox's messages, best matches first. Spam, trash and blocked mail are never included. Newly received mail can take a short while to become searchable.
Inputs
- Inbox
inbox_idtextRequired - The inbox, which is identified by its email address.
- Search for
querytextRequired - Words to find in the sender, recipients, subject or body.
- After
afterdate and time - Only items from after this time.
- Before
beforedate and time - Only items from before this time.
- Limit
limitnumber - How many to return, up to 100.From 1 to 100.
- Page token
page_tokentext - The 'next_page_token' of the previous result, for the next page.
Outputs
countnumberitemslist- The matching messages
next_page_tokentext
Example output
{
"count": 1,
"items": [
{
"attachments": [],
"bcc": [],
"cc": [],
"created_at": "2026-10-02T10:00:00Z",
"from": "Ada Lovelace <ada@example.com>",
"highlights": {
"from": [],
"recipients": [],
"subject": [],
"text": []
},
"in_reply_to": null,
"inbox_id": "support-agent@agentmail.to",
"labels": [
"received",
"unread"
],
"message_id": "<abc123@agentmail.to>",
"preview": "Where is my order?",
"references": [],
"size": 1200,
"subject": "Order status",
"thread_id": "thr_1",
"timestamp": "2026-10-02T10:00:00Z",
"to": [
"support-agent@agentmail.to"
],
"updated_at": "2026-10-02T10:00:00Z"
}
],
"next_page_token": null
}Send draft
Send a draft now. The draft is removed once it is sent; the result has the sent message's id and thread id.
Inputs
- Inbox
inbox_idtextRequired - The inbox, which is identified by its email address.
- Draft ID
draft_idtextRequired - The 'draft_id' of a Create draft result.
- Add labels
add_labelslist - Labels to put on the sent message.
- Remove labels
remove_labelslist - Labels to take off the sent message.
Outputs
inbox_idtextmessage_idtextthread_idtext
Example output
{
"inbox_id": "support-agent@agentmail.to",
"message_id": "<def456@agentmail.to>",
"thread_id": "thr_1"
}Send email
Send a new email from an inbox. Returns the new message's id and thread id. Free plans can send 100 emails a day.
Inputs
- Inbox
inbox_idtextRequired - The inbox, which is identified by its email address.
- To
tolistRequired - Recipient email addresses, such as ada@example.com or Ada Lovelace <ada@example.com>.
- Subject
subjecttext - The subject line.
- Text
texttext - The plain-text body.
- HTML
htmltext - An HTML body. Give Text as well so every mail app can show it.
- CC
cclist - Email addresses to copy.
- BCC
bcclist - Email addresses to blind-copy.
- Reply-to
reply_tolist - Where replies should go, if not to this inbox.
- Labels
labelslist - Labels to attach, such as 'follow-up'.
Outputs
inbox_idtextmessage_idtextthread_idtext
Example output
{
"inbox_id": "support-agent@agentmail.to",
"message_id": "<def456@agentmail.to>",
"thread_id": "thr_1"
}Update draft
Change a draft's recipients, subject, body, labels or scheduled time. Fields left empty are kept.
Inputs
- Inbox
inbox_idtextRequired - The inbox, which is identified by its email address.
- Draft ID
draft_idtextRequired - The 'draft_id' of a Create draft result.
- To
tolist - Recipient email addresses, such as ada@example.com.
- Subject
subjecttext - The subject line.
- Text
texttext - The plain-text body.
- HTML
htmltext - An HTML body. Give Text as well so every mail app can show it.
- CC
cclist - Email addresses to copy.
- BCC
bcclist - Email addresses to blind-copy.
- Reply-to
reply_tolist - Where replies should go, if not to this inbox.
- Add labels
add_labelslist - Labels to add, such as 'read' or 'follow-up'.
- Remove labels
remove_labelslist - Labels to remove, such as 'unread'.
- Send at
send_atdate and time - Schedule (or reschedule) the draft for this time.
- Cancel scheduled send
cancel_scheduled_sendtrue/false - Unschedule the draft so it is kept but not sent.
Outputs
attachmentslistbcclistcclistclient_idtextcreated_attextdraft_idtextforward_oftexthtmltextin_reply_totextinbox_idtextlabelslistpreviewtextreferenceslistreply_tolistsend_attextsend_statustextsubjecttexttexttexttolistupdated_attext
Example output
{
"attachments": [],
"bcc": [],
"cc": [],
"client_id": null,
"created_at": "2026-10-02T11:00:00Z",
"draft_id": "drf_1",
"forward_of": null,
"html": null,
"in_reply_to": null,
"inbox_id": "support-agent@agentmail.to",
"labels": [
"draft"
],
"preview": null,
"references": [],
"reply_to": [],
"send_at": null,
"send_status": null,
"subject": "Your order",
"text": "It ships tomorrow.",
"to": [
"ada@example.com"
],
"updated_at": "2026-10-02T11:00:00Z"
}Update inbox
Change an inbox's display name, pause or resume it, or change its metadata. Fields left empty are kept.
Inputs
- Inbox
inbox_idtextRequired - The inbox, which is identified by its email address.
- Display name
display_nametext - The sender name recipients see, such as 'Support Agent'.
- Status
statustext - Active or paused. A paused inbox cannot send, and mail sent to it while paused is dropped - it is not delivered when the inbox resumes.One of:
active,paused(Paused (stops receiving mail)). - Metadata
metadataobject - Keys to set, merged into the existing metadata. Give a key an empty (null) value to remove it.
Outputs
client_idtextcreated_attextdisplay_nametextemailtextinbox_idtextmetadataobjectpod_idtextstatustextupdated_attext
Example output
{
"client_id": "lodol-0f1e",
"created_at": "2026-10-01T09:00:00Z",
"display_name": "Support Agent",
"email": "support-agent@agentmail.to",
"inbox_id": "support-agent@agentmail.to",
"metadata": {
"team": "support"
},
"pod_id": "pod_1",
"status": "active",
"updated_at": "2026-10-01T09:00:00Z"
}Update message labels
Add or remove labels on a message - for example add 'read' and remove 'unread' to mark it read.
Inputs
- Inbox
inbox_idtextRequired - The inbox, which is identified by its email address.
- Message ID
message_idtextRequired - The message's id, such as <abc123@agentmail.to> - the 'message_id' of a List messages, Search messages or Send email result.
- Add labels
add_labelslist - Labels to add, such as 'read' or 'follow-up'.
- Remove labels
remove_labelslist - Labels to remove, such as 'unread'.
Outputs
labelslistmessage_idtext
Example output
{
"labels": [
"received",
"read"
],
"message_id": "<abc123@agentmail.to>"
}Update thread labels
Add or remove labels on a whole thread. System labels such as 'sent' and 'received' cannot be changed, and threads of 100 or more messages cannot be relabelled.
Inputs
- Inbox
inbox_idtextRequired - The inbox, which is identified by its email address.
- Thread ID
thread_idtextRequired - The 'thread_id' of a List threads, List messages or send result.
- Add labels
add_labelslist - Labels to add, such as 'read' or 'follow-up'.
- Remove labels
remove_labelslist - Labels to remove, such as 'unread'.
Outputs
labelslistthread_idtext
Example output
{
"labels": [
"received",
"follow-up"
],
"thread_id": "thr_1"
}