# Agent Mail

AgentMail provides AI agents with their own email inboxes, enabling them to send, receive, and act upon emails for communication with services, people, and other agents.

- **Category:** ai agents
- **Auth:** API_KEY
- **Composio Managed App Available?** N/A
- **Tools:** 3
- **Triggers:** 1
- **Slug:** `AGENT_MAIL`
- **Version:** 20260316_00

## Tools

### Create Inbox

**Slug:** `AGENT_MAIL_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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `domain` | string | No | Domain for the inbox email address. Must be a verified domain in your AgentMail account. Defaults to 'agentmail.to' if not provided. |
| `username` | string | No | Username for the inbox. Used to create the email address (username@domain). If not provided, a random username will be generated. |
| `client_id` | string | No | Client-side identifier for idempotency or correlation. Can be used to prevent duplicate inbox creation or to associate the inbox with your internal systems. |
| `display_name` | string | No | Display name for the inbox (shown as the sender name in emails) |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Message

**Slug:** `AGENT_MAIL_GET_MESSAGE`

Retrieve the complete details of a specific email message from an AgentMail inbox. This action returns the full message content including sender, recipients, subject, body (both text and HTML), attachments, labels, and metadata. Use this to read individual messages after discovering them via LIST_MESSAGES or webhooks.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `inbox_id` | string | Yes | MUST be a valid email address (e.g., agent@agentmail.to). This is NOT an ID or identifier - it must be a full email address of the inbox. |
| `message_id` | string | Yes | The unique message ID to retrieve (typically in email Message-ID format with angle brackets) |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Inboxes

**Slug:** `AGENT_MAIL_LIST_INBOXES`

List all inboxes available to the authenticated AgentMail account. Use this to discover valid inbox_id values for message operations.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of inboxes to return per page |
| `ascending` | boolean | No | Sort inboxes in ascending order by created_at timestamp (oldest first). Default is descending (newest first) |
| `page_token` | string | No | Token for pagination to get the next set of results |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Messages

**Slug:** `AGENT_MAIL_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`).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `after` | string | No | Return messages sent after this timestamp (ISO 8601 format) |
| `limit` | integer | No | Maximum number of messages to return (1-100) |
| `before` | string | No | Return messages sent before this timestamp (ISO 8601 format) |
| `labels` | array | No | Filter messages by labels (e.g., 'sent', 'unread', 'important') |
| `inbox_id` | string | Yes | MUST be a valid email address (e.g., agent@agentmail.to). This is NOT an ID or identifier - it must be a full email address of the inbox. |
| `ascending` | boolean | No | Sort messages in ascending order by timestamp (oldest first). Default is descending (newest first) |
| `page_token` | string | No | Token for pagination to get the next set of results |
| `include_spam` | boolean | No | Include messages marked as spam in the results |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Send Email

**Slug:** `AGENT_MAIL_SEND_EMAIL`

Send an email using AgentMail API

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cc` | array | No | List of CC recipient email addresses |
| `to` | array | Yes | List of recipient email addresses |
| `bcc` | array | No | List of BCC recipient email addresses |
| `html` | string | No | HTML content of the email. Either text or html (or both) must be provided. If both are provided, email clients will typically prefer HTML with text as fallback. |
| `text` | string | No | Plain text content of the email. Either text or html (or both) must be provided. |
| `labels` | array | No | Labels to apply to the sent message |
| `subject` | string | Yes | Email subject line |
| `inbox_id` | string | Yes | The inbox identifier (typically the full email address, e.g., 'your-inbox@agentmail.to') Must be obtained from external configuration or prior context; no tool exists to list or discover available inboxes. |
| `reply_to` | array | No | Reply-to email addresses |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |


## Triggers

### New Email Received

**Slug:** `AGENT_MAIL_NEW_EMAIL_TRIGGER`

**Type:** poll

Trigger for new emails in an AgentMail inbox

#### Configuration

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `inbox_id` | string | Yes | The inbox ID or email address to monitor for new emails |
| `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes |
| `labels` | array | No | Filter messages by specific labels (e.g., 'unread', 'inbox') |

#### Payload

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `attachments` | array | No | Message attachments |
| `bcc` | array | No | BCC email addresses |
| `cc` | array | No | CC email addresses |
| `created_at` | string | Yes | When the message was created |
| `from` | string | Yes | Sender's email address |
| `html` | string | No | HTML content |
| `in_reply_to` | string | No | ID of message being replied to |
| `inbox_id` | string | Yes | ID of the inbox |
| `labels` | array | Yes | Labels applied to the message |
| `message_id` | string | Yes | ID of the message |
| `preview` | string | No | Text preview of the message |
| `references` | array | No | IDs of previous messages in thread |
| `reply_to` | array | No | Reply-to email addresses |
| `subject` | string | No | Email subject |
| `text` | string | No | Plain text content |
| `thread_id` | string | Yes | ID of the thread |
| `timestamp` | string | Yes | When the message was received |
| `to` | array | Yes | Recipient email addresses |
| `updated_at` | string | Yes | When the message was last updated |