# AgentMail > 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. App ยท 20 actions. Web page: https://docs.lodol.com/docs/integrations/agentmail ## Actions ### 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_id`, text, required): The inbox, which is identified by its email address. - To (`to`, list): Recipient email addresses, such as ada@example.com. - Subject (`subject`, text): The subject line. - Text (`text`, text): The plain-text body. - HTML (`html`, text): An HTML body. Give Text as well so every mail app can show it. - CC (`cc`, list): Email addresses to copy. - BCC (`bcc`, list): Email addresses to blind-copy. - Reply-to (`reply_to`, list): Where replies should go, if not to this inbox. - Labels (`labels`, list): Labels to attach, such as 'follow-up'. - Reply to message ID (`in_reply_to`, text): Make the draft a reply to this message. - Forward message ID (`forward_of`, text): Make the draft a forward of this message. - Reply to everyone (`reply_all`, true/false): With Reply to message ID, address the reply to everyone on that message. Leave To, CC and BCC empty. - Send at (`send_at`, date and time): Schedule the draft to send itself at this time. **Outputs** - `attachments` (list) - `bcc` (list) - `cc` (list) - `client_id` (text) - `created_at` (text) - `draft_id` (text) - `forward_of` (text) - `html` (text) - `in_reply_to` (text) - `inbox_id` (text) - `labels` (list) - `preview` (text) - `references` (list) - `reply_to` (list) - `send_at` (text) - `send_status` (text) - `subject` (text) - `text` (text) - `to` (list) - `updated_at` (text) **Example output** ```json { "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 (`username`, text): The part before the @, such as 'support-agent'. Leave empty for a random one. - Domain (`domain`, text): Leave empty for agentmail.to, the only domain on the free plan. A custom domain must be verified in AgentMail first. - Display name (`display_name`, text): The sender name recipients see, such as 'Support Agent'. - Status (`status`, text): 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 (`metadata`, object): Your own keys and values to keep on the inbox, such as team: sales. Values are text, numbers or true/false. **Outputs** - `client_id` (text) - `created_at` (text) - `display_name` (text) - `email` (text) - `inbox_id` (text) - `metadata` (object) - `pod_id` (text) - `status` (text) - `updated_at` (text) **Example output** ```json { "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_id`, text, required): The inbox, which is identified by its email address. - Draft ID (`draft_id`, text, required): The 'draft_id' of a Create draft result. **Outputs** - `deleted` (true/false) - `id` (text) - `type` (text) **Example output** ```json { "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_id`, text, required): The inbox, which is identified by its email address. **Outputs** - `deleted` (true/false) - `id` (text) - `type` (text) **Example output** ```json { "deleted": true, "id": "support-agent@agentmail.to", "type": "inbox" } ``` ### Delete thread Permanently delete a thread and every message in it. **Inputs** - Inbox (`inbox_id`, text, required): The inbox, which is identified by its email address. - Thread ID (`thread_id`, text, required): The 'thread_id' of a List threads, List messages or send result. **Outputs** - `deleted` (true/false) - `id` (text) - `type` (text) **Example output** ```json { "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_id`, text, required): The inbox, which is identified by its email address. - Message ID (`message_id`, text, required): The message's id, such as - the 'message_id' of a List messages, Search messages or Send email result. - To (`to`, list, required): Recipient email addresses, such as ada@example.com or Ada Lovelace . - Subject (`subject`, text): Leave empty to use 'Fwd:' and the original subject. - Text (`text`, text): A note to add above the forwarded message. - HTML (`html`, text): An HTML body. Give Text as well so every mail app can show it. - CC (`cc`, list): Email addresses to copy. - BCC (`bcc`, list): Email addresses to blind-copy. - Labels (`labels`, list): Labels to attach, such as 'follow-up'. **Outputs** - `inbox_id` (text) - `message_id` (text) - `thread_id` (text) **Example output** ```json { "inbox_id": "support-agent@agentmail.to", "message_id": "", "thread_id": "thr_1" } ``` ### Get inbox Read one inbox: its address, display name, status and metadata. **Inputs** - Inbox (`inbox_id`, text, required): The inbox, which is identified by its email address. **Outputs** - `client_id` (text) - `created_at` (text) - `display_name` (text) - `email` (text) - `inbox_id` (text) - `metadata` (object) - `pod_id` (text) - `status` (text) - `updated_at` (text) **Example output** ```json { "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_id`, text, required): The inbox, which is identified by its email address. - Message ID (`message_id`, text, required): The message's id, such as - the 'message_id' of a List messages, Search messages or Send email result. **Outputs** - `attachments` (list) - `bcc` (list) - `cc` (list) - `created_at` (text) - `extracted_html` (text) - `extracted_text` (text) - `from` (text) - `html` (text) - `in_reply_to` (text) - `inbox_id` (text) - `labels` (list) - `message_id` (text) - `preview` (text) - `references` (list) - `reply_to` (list) - `size` (number) - `subject` (text) - `text` (text) - `thread_id` (text) - `timestamp` (text) - `to` (list) - `updated_at` (text) **Example output** ```json { "attachments": [], "bcc": [], "cc": [], "created_at": "2026-10-02T10:00:00Z", "extracted_html": null, "extracted_text": "Where is my order?", "from": "Ada Lovelace ", "html": "

Where is my order?

", "in_reply_to": null, "inbox_id": "support-agent@agentmail.to", "labels": [ "received", "unread" ], "message_id": "", "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_id`, text, required): The inbox, which is identified by its email address. - Thread ID (`thread_id`, text, required): The 'thread_id' of a List threads, List messages or send result. - Messages (`limit`, number): How many messages to return, up to 100. From 1 to 100. - Page token (`page_token`, text): The 'next_page_token' of the previous result, for older messages. **Outputs** - `attachments` (list) - `count` (number) - `created_at` (text) - `inbox_id` (text) - `labels` (list) - `last_message_id` (text) - `message_count` (number) - `messages` (list): The newest page of messages, oldest first - `next_page_token` (text) - `preview` (text) - `received_timestamp` (text) - `recipients` (list) - `senders` (list) - `sent_timestamp` (text) - `size` (number) - `subject` (text) - `thread_id` (text) - `timestamp` (text) - `updated_at` (text) **Example output** ```json { "attachments": [], "count": 1, "created_at": "2026-10-02T10:00:00Z", "inbox_id": "support-agent@agentmail.to", "labels": [ "received" ], "last_message_id": "", "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 ", "html": "

Where is my order?

", "in_reply_to": null, "inbox_id": "support-agent@agentmail.to", "labels": [ "received", "unread" ], "message_id": "", "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 (`order`, text): Defaults to newest first. One of: `newest` (Newest first), `oldest` (Oldest first). - Limit (`limit`, number): How many to return, up to 100. From 1 to 100. - Page token (`page_token`, text): The 'next_page_token' of the previous result, for the next page. **Outputs** - `count` (number) - `items` (list): The inboxes - `next_page_token` (text) **Example output** ```json { "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_id`, text, required): The inbox, which is identified by its email address. - Labels (`labels`, list): Only items carrying every one of these labels, such as 'unread'. - From contains (`from_contains`, list): Only messages whose sender contains this text. - To contains (`to_contains`, list): Only messages whose To, CC or BCC contains this text. - Subject contains (`subject_contains`, list): Only messages whose subject contains this text. - After (`after`, date and time): Only items from after this time. - Before (`before`, date and time): Only items from before this time. - Include spam (`include_spam`, true/false): Also include mail marked as spam. - Include trash (`include_trash`, true/false): Also include mail in the trash. - Order (`order`, text): Defaults to newest first. One of: `newest` (Newest first), `oldest` (Oldest first). - Limit (`limit`, number): How many to return, up to 100. From 1 to 100. - Page token (`page_token`, text): The 'next_page_token' of the previous result, for the next page. **Outputs** - `count` (number) - `items` (list): The matching messages - `next_page_token` (text) **Example output** ```json { "count": 1, "items": [ { "attachments": [], "bcc": [], "cc": [], "created_at": "2026-10-02T10:00:00Z", "from": "Ada Lovelace ", "in_reply_to": null, "inbox_id": "support-agent@agentmail.to", "labels": [ "received", "unread" ], "message_id": "", "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_id`, text, required): The inbox, which is identified by its email address. - Labels (`labels`, list): Only items carrying every one of these labels, such as 'unread'. - Senders contain (`senders`, list): Only threads with a sender containing this text. - Recipients contain (`recipients`, list): Only threads with a recipient containing this text. - Subject contains (`subject_contains`, list): Only threads whose subject contains this text. - After (`after`, date and time): Only items from after this time. - Before (`before`, date and time): Only items from before this time. - Include spam (`include_spam`, true/false): Also include mail marked as spam. - Include trash (`include_trash`, true/false): Also include mail in the trash. - Order (`order`, text): Defaults to newest first. One of: `newest` (Newest first), `oldest` (Oldest first). - Limit (`limit`, number): How many to return, up to 100. From 1 to 100. - Page token (`page_token`, text): The 'next_page_token' of the previous result, for the next page. **Outputs** - `count` (number) - `items` (list): The matching threads - `next_page_token` (text) **Example output** ```json { "count": 1, "items": [ { "attachments": [], "created_at": "2026-10-02T10:00:00Z", "inbox_id": "support-agent@agentmail.to", "labels": [ "received" ], "last_message_id": "", "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_id`, text, required): The inbox, which is identified by its email address. - Message ID (`message_id`, text, required): The message's id, such as - the 'message_id' of a List messages, Search messages or Send email result. - Text (`text`, text): The plain-text body. - HTML (`html`, text): An HTML body. Give Text as well so every mail app can show it. - Reply to everyone (`reply_all`, true/false): Send to the sender and everyone else on the message. Leave To, CC and BCC empty when ticked. - To (`to`, list): Send to these instead of the original sender. - CC (`cc`, list): Email addresses to copy. - BCC (`bcc`, list): Email addresses to blind-copy. - Reply-to (`reply_to`, list): Where replies should go, if not to this inbox. - Labels (`labels`, list): Labels to attach, such as 'follow-up'. **Outputs** - `inbox_id` (text) - `message_id` (text) - `thread_id` (text) **Example output** ```json { "inbox_id": "support-agent@agentmail.to", "message_id": "", "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_id`, text, required): The inbox, which is identified by its email address. - Search for (`query`, text, required): Words to find in the sender, recipients, subject or body. - After (`after`, date and time): Only items from after this time. - Before (`before`, date and time): Only items from before this time. - Limit (`limit`, number): How many to return, up to 100. From 1 to 100. - Page token (`page_token`, text): The 'next_page_token' of the previous result, for the next page. **Outputs** - `count` (number) - `items` (list): The matching messages - `next_page_token` (text) **Example output** ```json { "count": 1, "items": [ { "attachments": [], "bcc": [], "cc": [], "created_at": "2026-10-02T10:00:00Z", "from": "Ada Lovelace ", "highlights": { "from": [], "recipients": [], "subject": [], "text": [] }, "in_reply_to": null, "inbox_id": "support-agent@agentmail.to", "labels": [ "received", "unread" ], "message_id": "", "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_id`, text, required): The inbox, which is identified by its email address. - Draft ID (`draft_id`, text, required): The 'draft_id' of a Create draft result. - Add labels (`add_labels`, list): Labels to put on the sent message. - Remove labels (`remove_labels`, list): Labels to take off the sent message. **Outputs** - `inbox_id` (text) - `message_id` (text) - `thread_id` (text) **Example output** ```json { "inbox_id": "support-agent@agentmail.to", "message_id": "", "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_id`, text, required): The inbox, which is identified by its email address. - To (`to`, list, required): Recipient email addresses, such as ada@example.com or Ada Lovelace . - Subject (`subject`, text): The subject line. - Text (`text`, text): The plain-text body. - HTML (`html`, text): An HTML body. Give Text as well so every mail app can show it. - CC (`cc`, list): Email addresses to copy. - BCC (`bcc`, list): Email addresses to blind-copy. - Reply-to (`reply_to`, list): Where replies should go, if not to this inbox. - Labels (`labels`, list): Labels to attach, such as 'follow-up'. **Outputs** - `inbox_id` (text) - `message_id` (text) - `thread_id` (text) **Example output** ```json { "inbox_id": "support-agent@agentmail.to", "message_id": "", "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_id`, text, required): The inbox, which is identified by its email address. - Draft ID (`draft_id`, text, required): The 'draft_id' of a Create draft result. - To (`to`, list): Recipient email addresses, such as ada@example.com. - Subject (`subject`, text): The subject line. - Text (`text`, text): The plain-text body. - HTML (`html`, text): An HTML body. Give Text as well so every mail app can show it. - CC (`cc`, list): Email addresses to copy. - BCC (`bcc`, list): Email addresses to blind-copy. - Reply-to (`reply_to`, list): Where replies should go, if not to this inbox. - Add labels (`add_labels`, list): Labels to add, such as 'read' or 'follow-up'. - Remove labels (`remove_labels`, list): Labels to remove, such as 'unread'. - Send at (`send_at`, date and time): Schedule (or reschedule) the draft for this time. - Cancel scheduled send (`cancel_scheduled_send`, true/false): Unschedule the draft so it is kept but not sent. **Outputs** - `attachments` (list) - `bcc` (list) - `cc` (list) - `client_id` (text) - `created_at` (text) - `draft_id` (text) - `forward_of` (text) - `html` (text) - `in_reply_to` (text) - `inbox_id` (text) - `labels` (list) - `preview` (text) - `references` (list) - `reply_to` (list) - `send_at` (text) - `send_status` (text) - `subject` (text) - `text` (text) - `to` (list) - `updated_at` (text) **Example output** ```json { "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_id`, text, required): The inbox, which is identified by its email address. - Display name (`display_name`, text): The sender name recipients see, such as 'Support Agent'. - Status (`status`, text): 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 (`metadata`, object): Keys to set, merged into the existing metadata. Give a key an empty (null) value to remove it. **Outputs** - `client_id` (text) - `created_at` (text) - `display_name` (text) - `email` (text) - `inbox_id` (text) - `metadata` (object) - `pod_id` (text) - `status` (text) - `updated_at` (text) **Example output** ```json { "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_id`, text, required): The inbox, which is identified by its email address. - Message ID (`message_id`, text, required): The message's id, such as - the 'message_id' of a List messages, Search messages or Send email result. - Add labels (`add_labels`, list): Labels to add, such as 'read' or 'follow-up'. - Remove labels (`remove_labels`, list): Labels to remove, such as 'unread'. **Outputs** - `labels` (list) - `message_id` (text) **Example output** ```json { "labels": [ "received", "read" ], "message_id": "" } ``` ### 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_id`, text, required): The inbox, which is identified by its email address. - Thread ID (`thread_id`, text, required): The 'thread_id' of a List threads, List messages or send result. - Add labels (`add_labels`, list): Labels to add, such as 'read' or 'follow-up'. - Remove labels (`remove_labels`, list): Labels to remove, such as 'unread'. **Outputs** - `labels` (list) - `thread_id` (text) **Example output** ```json { "labels": [ "received", "follow-up" ], "thread_id": "thr_1" } ```