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

ActionWhat it does
Create draftSave an email as a draft to review or send later - a new email, a reply or a forward.
Create inboxCreate a new email inbox, such as support-agent@agentmail.to.
Delete draftDelete a draft without sending it.
Delete inboxPermanently delete an inbox and all of its mail.
Delete threadPermanently delete a thread and every message in it.
Forward messageForward a message to new recipients, optionally with a note of your own above it.
Get inboxRead one inbox: its address, display name, status and metadata.
Get messageRead one message in full: sender, recipients, subject, text and HTML body, and the new text of a reply without the quoted history.
Get threadRead a conversation with its messages in full, oldest first.
List inboxesList the account's inboxes with their email address, display name, status and metadata.
List messagesList an inbox's messages, newest first, filtered by label, sender, recipient, subject or date.
List threadsList an inbox's conversations (threads), most recent first, filtered by label, sender, recipient, subject or date.
Reply to messageReply to a message in its thread.
Search messagesFull-text search across an inbox's messages, best matches first.
Send draftSend a draft now.
Send emailSend a new email from an inbox.
Update draftChange a draft's recipients, subject, body, labels or scheduled time.
Update inboxChange an inbox's display name, pause or resume it, or change its metadata.
Update message labelsAdd or remove labels on a message - for example add 'read' and remove 'unread' to mark it read.
Update thread labelsAdd 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

Inboxinbox_idtextRequired
The inbox, which is identified by its email address.
Totolist
Recipient email addresses, such as ada@example.com.
Subjectsubjecttext
The subject line.
Texttexttext
The plain-text body.
HTMLhtmltext
An HTML body. Give Text as well so every mail app can show it.
CCcclist
Email addresses to copy.
BCCbcclist
Email addresses to blind-copy.
Reply-toreply_tolist
Where replies should go, if not to this inbox.
Labelslabelslist
Labels to attach, such as 'follow-up'.
Reply to message IDin_reply_totext
Make the draft a reply to this message.
Forward message IDforward_oftext
Make the draft a forward of this message.
Reply to everyonereply_alltrue/false
With Reply to message ID, address the reply to everyone on that message. Leave To, CC and BCC empty.
Send atsend_atdate and time
Schedule the draft to send itself at this time.

Outputs

attachmentslist
bcclist
cclist
client_idtext
created_attext
draft_idtext
forward_oftext
htmltext
in_reply_totext
inbox_idtext
labelslist
previewtext
referenceslist
reply_tolist
send_attext
send_statustext
subjecttext
texttext
tolist
updated_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

Usernameusernametext
The part before the @, such as 'support-agent'. Leave empty for a random one.
Domaindomaintext
Leave empty for agentmail.to, the only domain on the free plan. A custom domain must be verified in AgentMail first.
Display namedisplay_nametext
The sender name recipients see, such as 'Support Agent'.
Statusstatustext
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)).
Metadatametadataobject
Your own keys and values to keep on the inbox, such as team: sales. Values are text, numbers or true/false.

Outputs

client_idtext
created_attext
display_nametext
emailtext
inbox_idtext
metadataobject
pod_idtext
statustext
updated_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

Inboxinbox_idtextRequired
The inbox, which is identified by its email address.
Draft IDdraft_idtextRequired
The 'draft_id' of a Create draft result.

Outputs

deletedtrue/false
idtext
typetext
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

Inboxinbox_idtextRequired
The inbox, which is identified by its email address.

Outputs

deletedtrue/false
idtext
typetext
Example output
{
  "deleted": true,
  "id": "support-agent@agentmail.to",
  "type": "inbox"
}

Delete thread

Permanently delete a thread and every message in it.

Inputs

Inboxinbox_idtextRequired
The inbox, which is identified by its email address.
Thread IDthread_idtextRequired
The 'thread_id' of a List threads, List messages or send result.

Outputs

deletedtrue/false
idtext
typetext
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

Inboxinbox_idtextRequired
The inbox, which is identified by its email address.
Message IDmessage_idtextRequired
The message's id, such as <abc123@agentmail.to> - the 'message_id' of a List messages, Search messages or Send email result.
TotolistRequired
Recipient email addresses, such as ada@example.com or Ada Lovelace <ada@example.com>.
Subjectsubjecttext
Leave empty to use 'Fwd:' and the original subject.
Texttexttext
A note to add above the forwarded message.
HTMLhtmltext
An HTML body. Give Text as well so every mail app can show it.
CCcclist
Email addresses to copy.
BCCbcclist
Email addresses to blind-copy.
Labelslabelslist
Labels to attach, such as 'follow-up'.

Outputs

inbox_idtext
message_idtext
thread_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

Inboxinbox_idtextRequired
The inbox, which is identified by its email address.

Outputs

client_idtext
created_attext
display_nametext
emailtext
inbox_idtext
metadataobject
pod_idtext
statustext
updated_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

Inboxinbox_idtextRequired
The inbox, which is identified by its email address.
Message IDmessage_idtextRequired
The message's id, such as <abc123@agentmail.to> - the 'message_id' of a List messages, Search messages or Send email result.

Outputs

attachmentslist
bcclist
cclist
created_attext
extracted_htmltext
extracted_texttext
fromtext
htmltext
in_reply_totext
inbox_idtext
labelslist
message_idtext
previewtext
referenceslist
reply_tolist
sizenumber
subjecttext
texttext
thread_idtext
timestamptext
tolist
updated_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

Inboxinbox_idtextRequired
The inbox, which is identified by its email address.
Thread IDthread_idtextRequired
The 'thread_id' of a List threads, List messages or send result.
Messageslimitnumber
How many messages to return, up to 100.From 1 to 100.
Page tokenpage_tokentext
The 'next_page_token' of the previous result, for older messages.

Outputs

attachmentslist
countnumber
created_attext
inbox_idtext
labelslist
last_message_idtext
message_countnumber
messageslist
The newest page of messages, oldest first
next_page_tokentext
previewtext
received_timestamptext
recipientslist
senderslist
sent_timestamptext
sizenumber
subjecttext
thread_idtext
timestamptext
updated_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

Orderordertext
Defaults to newest first.One of: newest (Newest first), oldest (Oldest first).
Limitlimitnumber
How many to return, up to 100.From 1 to 100.
Page tokenpage_tokentext
The 'next_page_token' of the previous result, for the next page.

Outputs

countnumber
itemslist
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

Inboxinbox_idtextRequired
The inbox, which is identified by its email address.
Labelslabelslist
Only items carrying every one of these labels, such as 'unread'.
From containsfrom_containslist
Only messages whose sender contains this text.
To containsto_containslist
Only messages whose To, CC or BCC contains this text.
Subject containssubject_containslist
Only messages whose subject contains this text.
Afterafterdate and time
Only items from after this time.
Beforebeforedate and time
Only items from before this time.
Include spaminclude_spamtrue/false
Also include mail marked as spam.
Include trashinclude_trashtrue/false
Also include mail in the trash.
Orderordertext
Defaults to newest first.One of: newest (Newest first), oldest (Oldest first).
Limitlimitnumber
How many to return, up to 100.From 1 to 100.
Page tokenpage_tokentext
The 'next_page_token' of the previous result, for the next page.

Outputs

countnumber
itemslist
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

Inboxinbox_idtextRequired
The inbox, which is identified by its email address.
Labelslabelslist
Only items carrying every one of these labels, such as 'unread'.
Senders containsenderslist
Only threads with a sender containing this text.
Recipients containrecipientslist
Only threads with a recipient containing this text.
Subject containssubject_containslist
Only threads whose subject contains this text.
Afterafterdate and time
Only items from after this time.
Beforebeforedate and time
Only items from before this time.
Include spaminclude_spamtrue/false
Also include mail marked as spam.
Include trashinclude_trashtrue/false
Also include mail in the trash.
Orderordertext
Defaults to newest first.One of: newest (Newest first), oldest (Oldest first).
Limitlimitnumber
How many to return, up to 100.From 1 to 100.
Page tokenpage_tokentext
The 'next_page_token' of the previous result, for the next page.

Outputs

countnumber
itemslist
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

Inboxinbox_idtextRequired
The inbox, which is identified by its email address.
Message IDmessage_idtextRequired
The message's id, such as <abc123@agentmail.to> - the 'message_id' of a List messages, Search messages or Send email result.
Texttexttext
The plain-text body.
HTMLhtmltext
An HTML body. Give Text as well so every mail app can show it.
Reply to everyonereply_alltrue/false
Send to the sender and everyone else on the message. Leave To, CC and BCC empty when ticked.
Totolist
Send to these instead of the original sender.
CCcclist
Email addresses to copy.
BCCbcclist
Email addresses to blind-copy.
Reply-toreply_tolist
Where replies should go, if not to this inbox.
Labelslabelslist
Labels to attach, such as 'follow-up'.

Outputs

inbox_idtext
message_idtext
thread_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

Inboxinbox_idtextRequired
The inbox, which is identified by its email address.
Search forquerytextRequired
Words to find in the sender, recipients, subject or body.
Afterafterdate and time
Only items from after this time.
Beforebeforedate and time
Only items from before this time.
Limitlimitnumber
How many to return, up to 100.From 1 to 100.
Page tokenpage_tokentext
The 'next_page_token' of the previous result, for the next page.

Outputs

countnumber
itemslist
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

Inboxinbox_idtextRequired
The inbox, which is identified by its email address.
Draft IDdraft_idtextRequired
The 'draft_id' of a Create draft result.
Add labelsadd_labelslist
Labels to put on the sent message.
Remove labelsremove_labelslist
Labels to take off the sent message.

Outputs

inbox_idtext
message_idtext
thread_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

Inboxinbox_idtextRequired
The inbox, which is identified by its email address.
TotolistRequired
Recipient email addresses, such as ada@example.com or Ada Lovelace <ada@example.com>.
Subjectsubjecttext
The subject line.
Texttexttext
The plain-text body.
HTMLhtmltext
An HTML body. Give Text as well so every mail app can show it.
CCcclist
Email addresses to copy.
BCCbcclist
Email addresses to blind-copy.
Reply-toreply_tolist
Where replies should go, if not to this inbox.
Labelslabelslist
Labels to attach, such as 'follow-up'.

Outputs

inbox_idtext
message_idtext
thread_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

Inboxinbox_idtextRequired
The inbox, which is identified by its email address.
Draft IDdraft_idtextRequired
The 'draft_id' of a Create draft result.
Totolist
Recipient email addresses, such as ada@example.com.
Subjectsubjecttext
The subject line.
Texttexttext
The plain-text body.
HTMLhtmltext
An HTML body. Give Text as well so every mail app can show it.
CCcclist
Email addresses to copy.
BCCbcclist
Email addresses to blind-copy.
Reply-toreply_tolist
Where replies should go, if not to this inbox.
Add labelsadd_labelslist
Labels to add, such as 'read' or 'follow-up'.
Remove labelsremove_labelslist
Labels to remove, such as 'unread'.
Send atsend_atdate and time
Schedule (or reschedule) the draft for this time.
Cancel scheduled sendcancel_scheduled_sendtrue/false
Unschedule the draft so it is kept but not sent.

Outputs

attachmentslist
bcclist
cclist
client_idtext
created_attext
draft_idtext
forward_oftext
htmltext
in_reply_totext
inbox_idtext
labelslist
previewtext
referenceslist
reply_tolist
send_attext
send_statustext
subjecttext
texttext
tolist
updated_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

Inboxinbox_idtextRequired
The inbox, which is identified by its email address.
Display namedisplay_nametext
The sender name recipients see, such as 'Support Agent'.
Statusstatustext
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)).
Metadatametadataobject
Keys to set, merged into the existing metadata. Give a key an empty (null) value to remove it.

Outputs

client_idtext
created_attext
display_nametext
emailtext
inbox_idtext
metadataobject
pod_idtext
statustext
updated_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

Inboxinbox_idtextRequired
The inbox, which is identified by its email address.
Message IDmessage_idtextRequired
The message's id, such as <abc123@agentmail.to> - the 'message_id' of a List messages, Search messages or Send email result.
Add labelsadd_labelslist
Labels to add, such as 'read' or 'follow-up'.
Remove labelsremove_labelslist
Labels to remove, such as 'unread'.

Outputs

labelslist
message_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

Inboxinbox_idtextRequired
The inbox, which is identified by its email address.
Thread IDthread_idtextRequired
The 'thread_id' of a List threads, List messages or send result.
Add labelsadd_labelslist
Labels to add, such as 'read' or 'follow-up'.
Remove labelsremove_labelslist
Labels to remove, such as 'unread'.

Outputs

labelslist
thread_idtext
Example output
{
  "labels": [
    "received",
    "follow-up"
  ],
  "thread_id": "thr_1"
}

On this page