Skip to main content
API docs by Redocly

AgentMail API (0.0.0)

Download OpenAPI specification:Download

URL: https://agentmail.to

Programmatic email inboxes for AI agents

Inboxes

Create and manage email inboxes.

List inboxes

Returns a paginated list of inboxes for the authenticated account.

Authorizations:
bearerAuth
query Parameters
limit
integer [ 1 .. 100 ]

Maximum number of inboxes to return.

page_token
string

Pagination token returned from a previous list call.

Responses

Response samples

Content type
application/json
{
  • "inboxes": [
    ],
  • "count": 42,
  • "limit": 20,
  • "next_page_token": "tok_nextpage"
}

Create an inbox

Creates a new email inbox.

Authorizations:
bearerAuth
Request Body schema: application/json
optional
username
string

Local part of the email address (before the @). Auto-generated if omitted.

domain
string

Domain for the email address. Defaults to the account default domain.

display_name
string

Human-readable label for the inbox.

client_id
string

Optional client-supplied identifier for correlation.

Responses

Request samples

Content type
application/json
{
  • "username": "support",
  • "domain": "agentmail.to",
  • "display_name": "Support Team",
  • "client_id": "client_007"
}

Response samples

Content type
application/json
{
  • "pod_id": "pod_abc123",
  • "inbox_id": "inbox_xyz789",
  • "display_name": "Support Team",
  • "client_id": "client_007",
  • "created_at": "2024-01-15T10:30:00Z",
  • "updated_at": "2024-01-15T12:00:00Z"
}

Get an inbox

Retrieves a single inbox by ID.

Authorizations:
bearerAuth
path Parameters
inbox_id
required
string

The unique identifier of the inbox.

Responses

Response samples

Content type
application/json
{
  • "pod_id": "pod_abc123",
  • "inbox_id": "inbox_xyz789",
  • "display_name": "Support Team",
  • "client_id": "client_007",
  • "created_at": "2024-01-15T10:30:00Z",
  • "updated_at": "2024-01-15T12:00:00Z"
}

Update an inbox

Updates the display name of an existing inbox.

Authorizations:
bearerAuth
path Parameters
inbox_id
required
string

The unique identifier of the inbox.

Request Body schema: application/json
required
display_name
required
string

New display name for the inbox.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "pod_id": "pod_abc123",
  • "inbox_id": "inbox_xyz789",
  • "display_name": "Support Team",
  • "client_id": "client_007",
  • "created_at": "2024-01-15T10:30:00Z",
  • "updated_at": "2024-01-15T12:00:00Z"
}

Delete an inbox

Permanently deletes an inbox and all its messages.

Authorizations:
bearerAuth
path Parameters
inbox_id
required
string

The unique identifier of the inbox.

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Inbox not found."
}

Messages

Send, receive, and manage messages within an inbox.

List messages

Returns a paginated list of messages in the inbox.

Authorizations:
bearerAuth
path Parameters
inbox_id
required
string

The unique identifier of the inbox.

query Parameters
limit
integer [ 1 .. 100 ]

Maximum number of messages to return.

page_token
string

Pagination token returned from a previous list call.

labels
Array of strings

Filter messages by labels.

before
string <date-time>

Return messages before this ISO 8601 timestamp.

after
string <date-time>

Return messages after this ISO 8601 timestamp.

ascending
boolean

Sort in ascending order (oldest first). Defaults to descending.

include_spam
boolean

Include messages marked as spam.

include_blocked
boolean

Include messages that were blocked.

include_trash
boolean

Include messages in the trash.

Responses

Response samples

Content type
application/json
{
  • "messages": [
    ],
  • "count": 42,
  • "limit": 20,
  • "next_page_token": "tok_nextpage"
}

Send a message

Sends an email from the inbox.

Authorizations:
bearerAuth
path Parameters
inbox_id
required
string

The unique identifier of the inbox.

Request Body schema: application/json
required
string or Array of strings

Recipient email address(es).

(string or null) or (Array of strings or null)

CC recipient email address(es).

(string or null) or (Array of strings or null)

BCC recipient email address(es).

subject
string

Subject of the message.

text
string

Plain-text body.

html
string

HTML body.

(string or null) or (Array of strings or null)

Reply-To email address(es).

labels
Array of strings or null

Labels to apply to the sent message.

object or null

Additional email headers.

Responses

Request samples

Content type
application/json
{
  • "to": "[email protected]",
  • "cc": "string",
  • "bcc": "string",
  • "subject": "Hello from AgentMail",
  • "text": "string",
  • "html": "string",
  • "reply_to": "string",
  • "labels": [
    ],
  • "headers": {
    }
}

Response samples

Content type
application/json
{
  • "message_id": "msg_def456",
  • "thread_id": "thread_abc123"
}

Get a message

Retrieves a single message by ID.

Authorizations:
bearerAuth
path Parameters
inbox_id
required
string

The unique identifier of the inbox.

message_id
required
string

The unique identifier of the message.

Responses

Response samples

Content type
application/json
{
  • "inbox_id": "inbox_xyz789",
  • "thread_id": "thread_abc123",
  • "message_id": "msg_def456",
  • "labels": [
    ],
  • "timestamp": "2024-01-15T10:30:00Z",
  • "from": "[email protected]",
  • "to": [],
  • "size": 4096,
  • "updated_at": "2024-01-15T12:00:00Z",
  • "created_at": "2024-01-15T10:30:00Z",
  • "cc": [],
  • "bcc": [
    ],
  • "reply_to": [
    ],
  • "subject": "Hello from AgentMail",
  • "preview": "Just checking in...",
  • "text": "string",
  • "html": "string",
  • "extracted_text": "string",
  • "extracted_html": "string",
  • "in_reply_to": "string",
  • "references": [
    ],
  • "attachments": [
    ],
  • "headers": {
    }
}

Update a message

Adds or removes labels on a message.

Authorizations:
bearerAuth
path Parameters
inbox_id
required
string

The unique identifier of the inbox.

message_id
required
string

The unique identifier of the message.

Request Body schema: application/json
required
add_labels
Array of strings or null

Labels to add to the message.

remove_labels
Array of strings or null

Labels to remove from the message.

Responses

Request samples

Content type
application/json
{
  • "add_labels": [
    ],
  • "remove_labels": [
    ]
}

Response samples

Content type
application/json
{
  • "inbox_id": "inbox_xyz789",
  • "thread_id": "thread_abc123",
  • "message_id": "msg_def456",
  • "labels": [
    ],
  • "timestamp": "2024-01-15T10:30:00Z",
  • "from": "[email protected]",
  • "to": [],
  • "size": 4096,
  • "updated_at": "2024-01-15T12:00:00Z",
  • "created_at": "2024-01-15T10:30:00Z",
  • "cc": [],
  • "bcc": [
    ],
  • "reply_to": [
    ],
  • "subject": "Hello from AgentMail",
  • "preview": "Just checking in...",
  • "text": "string",
  • "html": "string",
  • "extracted_text": "string",
  • "extracted_html": "string",
  • "in_reply_to": "string",
  • "references": [
    ],
  • "attachments": [
    ],
  • "headers": {
    }
}

Reply to a message

Sends a reply to an existing message.

Authorizations:
bearerAuth
path Parameters
inbox_id
required
string

The unique identifier of the inbox.

message_id
required
string

The unique identifier of the message to reply to.

Request Body schema: application/json
optional
(string or null) or (Array of strings or null)

Override recipient email address(es).

(string or null) or (Array of strings or null)

CC recipient email address(es).

(string or null) or (Array of strings or null)

BCC recipient email address(es).

text
string

Plain-text body of the reply.

html
string

HTML body of the reply.

(string or null) or (Array of strings or null)

Reply-To email address(es).

labels
Array of strings or null

Labels to apply to the reply.

object or null

Additional email headers.

Responses

Request samples

Content type
application/json
{
  • "to": "string",
  • "cc": "string",
  • "bcc": "string",
  • "text": "string",
  • "html": "string",
  • "reply_to": "string",
  • "labels": [
    ],
  • "headers": {
    }
}

Response samples

Content type
application/json
{
  • "message_id": "msg_def456",
  • "thread_id": "thread_abc123"
}

Reply all to a message

Sends a reply to all recipients of an existing message.

Authorizations:
bearerAuth
path Parameters
inbox_id
required
string

The unique identifier of the inbox.

message_id
required
string

The unique identifier of the message to reply-all to.

Request Body schema: application/json
optional
(string or null) or (Array of strings or null)

Override recipient email address(es).

(string or null) or (Array of strings or null)

CC recipient email address(es).

(string or null) or (Array of strings or null)

BCC recipient email address(es).

text
string

Plain-text body of the reply.

html
string

HTML body of the reply.

(string or null) or (Array of strings or null)

Reply-To email address(es).

labels
Array of strings or null

Labels to apply to the reply.

object or null

Additional email headers.

Responses

Request samples

Content type
application/json
{
  • "to": "string",
  • "cc": "string",
  • "bcc": "string",
  • "text": "string",
  • "html": "string",
  • "reply_to": "string",
  • "labels": [
    ],
  • "headers": {
    }
}

Response samples

Content type
application/json
{
  • "message_id": "msg_def456",
  • "thread_id": "thread_abc123"
}

Forward a message

Forwards an existing message to new recipients.

Authorizations:
bearerAuth
path Parameters
inbox_id
required
string

The unique identifier of the inbox.

message_id
required
string

The unique identifier of the message to forward.

Request Body schema: application/json
optional
(string or null) or (Array of strings or null)

Recipient email address(es) to forward to.

(string or null) or (Array of strings or null)

CC recipient email address(es).

(string or null) or (Array of strings or null)

BCC recipient email address(es).

subject
string or null

Override subject for the forwarded message.

text
string

Additional plain-text body prepended to the forwarded content.

html
string

Additional HTML body prepended to the forwarded content.

(string or null) or (Array of strings or null)

Reply-To email address(es).

labels
Array of strings or null

Labels to apply to the forwarded message.

object or null

Additional email headers.

Responses

Request samples

Content type
application/json
{
  • "to": "string",
  • "cc": "string",
  • "bcc": "string",
  • "subject": "string",
  • "text": "string",
  • "html": "string",
  • "reply_to": "string",
  • "labels": [
    ],
  • "headers": {
    }
}

Response samples

Content type
application/json
{
  • "message_id": "msg_def456",
  • "thread_id": "thread_abc123"
}