AgentMail

Add a custom domain.

POST JSON body. Returns domain with DNS records needed for verification.

{
  "body": {
    "domain": "string (required, e.g. 'example.com')",
    "feedback_enabled": "boolean (required, enable bounce/complaint notifications)"
  }
}

List all custom domains.

GET with optional pagination. Returns verified and pending custom domains.

{
  "query": {
    "limit": "number (optional)",
    "page_token": "string (optional)"
  }
}

Get domain details and verification status.

Replace {domain_id}. Returns domain status and required DNS records.

{
  "path": {
    "domain_id": "string (domain name)"
  }
}

Delete a custom domain.

Permanently removes the custom domain.

{
  "path": {
    "domain_id": "string"
  }
}

Trigger domain verification.

Triggers DNS verification for the domain. Check domain status after.

{
  "path": {
    "domain_id": "string"
  }
}

Get DNS zone file for a domain.

Returns the DNS zone file with required records for domain verification.

{
  "path": {
    "domain_id": "string"
  }
}

List all drafts across all inboxes.

GET with optional filters. Returns drafts across all inboxes ordered by updated_at.

{
  "query": {
    "limit": "number (optional)",
    "page_token": "string (optional)",
    "labels": [
      "string (optional)"
    ],
    "before": "string (optional, ISO datetime)",
    "after": "string (optional, ISO datetime)",
    "ascending": "boolean (optional)"
  }
}

Get a draft by ID.

Replace {draft_id}. Returns draft details including to, subject, text, html, and attachments.

{
  "path": {
    "draft_id": "string"
  }
}

Create a new inbox with a real email address.

POST JSON body. Returns the created inbox. The inbox can immediately send and receive email.

{
  "body": {
    "username": "string (optional, randomly generated if omitted)",
    "domain": "string (optional, defaults to 'agentmail.to', must be a verified domain)",
    "display_name": "string (optional, format: 'Display Name <user@domain.com>')",
    "client_id": "string (optional)"
  }
}

List all inboxes.

GET with optional pagination. Returns inboxes ordered by created_at descending.

{
  "query": {
    "limit": "number (optional)",
    "page_token": "string (optional)"
  }
}

Update inbox display name.

PATCH JSON body with display_name.

{
  "path": {
    "inbox_id": "string"
  },
  "body": {
    "display_name": "string (required)"
  }
}

Delete an inbox.

Permanently deletes the inbox and all its messages.

{
  "path": {
    "inbox_id": "string"
  }
}

Get inbox details.

Replace {inbox_id}. Returns inbox details including pod_id, display_name, and timestamps.

{
  "path": {
    "inbox_id": "string (inbox ID)"
  }
}

List drafts in an inbox.

Replace {inbox_id}. Returns drafts ordered by updated_at.

{
  "path": {
    "inbox_id": "string"
  },
  "query": {
    "limit": "number (optional)",
    "page_token": "string (optional)",
    "labels": [
      "string (optional)"
    ],
    "before": "string (optional, ISO datetime)",
    "after": "string (optional, ISO datetime)",
    "ascending": "boolean (optional)"
  }
}

Create a draft email.

Replace {inbox_id}. POST JSON body. Use send_at for scheduled sending.

{
  "path": {
    "inbox_id": "string"
  },
  "body": {
    "to": [
      "string (optional, recipient addresses)"
    ],
    "cc": [
      "string (optional)"
    ],
    "bcc": [
      "string (optional)"
    ],
    "subject": "string (optional)",
    "text": "string (optional, plain text body)",
    "html": "string (optional, HTML body)",
    "reply_to": [
      "string (optional)"
    ],
    "labels": [
      "string (optional)"
    ],
    "in_reply_to": "string (optional, message ID being replied to)",
    "send_at": "string (optional, ISO datetime for scheduled send)",
    "client_id": "string (optional)"
  }
}

Delete a draft.

Permanently deletes the draft.

{
  "path": {
    "inbox_id": "string",
    "draft_id": "string"
  }
}

Update a draft.

PATCH JSON body with fields to update.

{
  "path": {
    "inbox_id": "string",
    "draft_id": "string"
  },
  "body": {
    "to": [
      "string (optional)"
    ],
    "cc": [
      "string (optional)"
    ],
    "bcc": [
      "string (optional)"
    ],
    "subject": "string (optional)",
    "text": "string (optional)",
    "html": "string (optional)",
    "reply_to": [
      "string (optional)"
    ],
    "send_at": "string (optional, ISO datetime)"
  }
}

Get a draft in an inbox.

Replace path params. Returns full draft details.

{
  "path": {
    "inbox_id": "string",
    "draft_id": "string"
  }
}

Send a draft email.

Sends the draft. Optionally update labels before sending. Returns message_id and thread_id.

{
  "path": {
    "inbox_id": "string",
    "draft_id": "string"
  },
  "body": {
    "add_labels": [
      "string (optional)"
    ],
    "remove_labels": [
      "string (optional)"
    ]
  }
}

List messages in an inbox.

Replace {inbox_id}. Returns messages ordered by timestamp. Use labels, before/after, and include_spam to filter.

{
  "path": {
    "inbox_id": "string"
  },
  "query": {
    "limit": "number (optional)",
    "page_token": "string (optional)",
    "labels": [
      "string (optional)"
    ],
    "before": "string (optional, ISO datetime)",
    "after": "string (optional, ISO datetime)",
    "ascending": "boolean (optional)",
    "include_spam": "boolean (optional)"
  }
}

Get a specific message.

Returns the full message with from, to, subject, text, html, extracted_text, attachments, headers, and timestamps.

{
  "path": {
    "inbox_id": "string",
    "message_id": "string"
  }
}

Update message labels.

PATCH JSON body to add or remove labels on the message.

{
  "path": {
    "inbox_id": "string",
    "message_id": "string"
  },
  "body": {
    "add_labels": [
      "string (optional)"
    ],
    "remove_labels": [
      "string (optional)"
    ]
  }
}

Get a message attachment.

Returns attachment metadata with a temporary download_url and expires_at.

{
  "path": {
    "inbox_id": "string",
    "message_id": "string",
    "attachment_id": "string"
  }
}

Forward a message.

Forward the message to new recipients. Returns message_id and thread_id.

{
  "path": {
    "inbox_id": "string",
    "message_id": "string"
  },
  "body": {
    "to": "string | string[] (required)",
    "cc": "string | string[] (optional)",
    "bcc": "string | string[] (optional)",
    "subject": "string (optional)",
    "text": "string (optional)",
    "html": "string (optional)",
    "labels": [
      "string (optional)"
    ],
    "attachments": [
      {
        "filename": "string",
        "content": "string (base64)",
        "content_type": "string"
      }
    ],
    "headers": "object (optional)"
  }
}

Get raw email message (RFC 2822).

Returns the raw email message content.

{
  "path": {
    "inbox_id": "string",
    "message_id": "string"
  }
}

Reply to a message.

POST reply content. Set reply_all: true to reply to all recipients. Returns message_id and thread_id.

{
  "path": {
    "inbox_id": "string",
    "message_id": "string"
  },
  "body": {
    "text": "string (optional)",
    "html": "string (optional)",
    "to": "string | string[] (optional, override recipients)",
    "cc": "string | string[] (optional)",
    "bcc": "string | string[] (optional)",
    "reply_all": "boolean (optional)",
    "labels": [
      "string (optional)"
    ],
    "attachments": [
      {
        "filename": "string",
        "content": "string (base64)",
        "content_type": "string"
      }
    ],
    "headers": "object (optional)"
  }
}

Reply all to a message.

Replies to all recipients of the original message. Returns message_id and thread_id.

{
  "path": {
    "inbox_id": "string",
    "message_id": "string"
  },
  "body": {
    "text": "string (optional)",
    "html": "string (optional)",
    "reply_to": "string | string[] (optional)",
    "labels": [
      "string (optional)"
    ],
    "attachments": [
      {
        "filename": "string",
        "content": "string (base64)",
        "content_type": "string"
      }
    ],
    "headers": "object (optional)"
  }
}

Send an email from an inbox.

Replace {inbox_id}. POST JSON body with 'to' and message content. Returns message_id and thread_id.

{
  "path": {
    "inbox_id": "string"
  },
  "body": {
    "to": "string | string[] (recipient addresses)",
    "cc": "string | string[] (optional)",
    "bcc": "string | string[] (optional)",
    "subject": "string (optional)",
    "text": "string (optional, plain text body)",
    "html": "string (optional, HTML body)",
    "reply_to": "string | string[] (optional)",
    "labels": [
      "string (optional)"
    ],
    "attachments": [
      {
        "filename": "string (optional)",
        "content": "string (optional, base64 encoded)",
        "url": "string (optional, URL to attachment)",
        "content_type": "string (optional)",
        "content_disposition": "string (optional, 'inline' or 'attachment')",
        "content_id": "string (optional)"
      }
    ],
    "headers": "object (optional, custom email headers)"
  }
}

Get email metrics for an inbox.

Returns message metrics (sent, delivered, bounced, delayed, rejected, complained, received timestamps) for the time range.

{
  "path": {
    "inbox_id": "string"
  },
  "query": {
    "event_types": [
      "string (optional, e.g. 'message.sent', 'message.delivered', 'message.bounced', 'message.received')"
    ],
    "start_timestamp": "string (required, ISO datetime)",
    "end_timestamp": "string (required, ISO datetime)"
  }
}

List email threads in an inbox.

Returns conversation threads. Each thread groups related messages with senders, recipients, subject, preview, and message_count.

{
  "path": {
    "inbox_id": "string"
  },
  "query": {
    "limit": "number (optional)",
    "page_token": "string (optional)",
    "labels": [
      "string (optional)"
    ],
    "before": "string (optional, ISO datetime)",
    "after": "string (optional, ISO datetime)",
    "ascending": "boolean (optional)",
    "include_spam": "boolean (optional)"
  }
}

Delete a thread.

Permanently deletes the thread and its messages.

{
  "path": {
    "inbox_id": "string",
    "thread_id": "string"
  }
}

Get a thread with all its messages.

Returns the thread with all messages in the conversation ordered by timestamp ascending.

{
  "path": {
    "inbox_id": "string",
    "thread_id": "string"
  }
}

Get a thread attachment.

Returns attachment metadata with download_url and expires_at.

{
  "path": {
    "inbox_id": "string",
    "thread_id": "string",
    "attachment_id": "string"
  }
}

Get email metrics across all inboxes.

Returns aggregated message metrics across all inboxes for the time range.

{
  "query": {
    "event_types": [
      "string (optional)"
    ],
    "start_timestamp": "string (required, ISO datetime)",
    "end_timestamp": "string (required, ISO datetime)"
  }
}

Get current organization details.

Returns organization info including inbox_count, domain_count, inbox_limit, and domain_limit.

Create a new pod.

POST JSON body. Creates a pod to group inboxes.

{
  "body": {
    "name": "string (optional)",
    "client_id": "string (optional)"
  }
}

List all pods.

GET with optional pagination. Pods group inboxes together.

{
  "query": {
    "limit": "number (optional)",
    "page_token": "string (optional)"
  }
}

Get pod details.

Replace {pod_id}. Returns pod details.

{
  "path": {
    "pod_id": "string"
  }
}

Delete a pod.

Permanently deletes the pod.

{
  "path": {
    "pod_id": "string"
  }
}

List domains in a pod.

Replace {pod_id}. Returns domains associated with the pod.

{
  "path": {
    "pod_id": "string"
  },
  "query": {
    "limit": "number (optional)",
    "page_token": "string (optional)"
  }
}

Add a domain to a pod.

Creates a custom domain scoped to the pod.

{
  "path": {
    "pod_id": "string"
  },
  "body": {
    "domain": "string (required)",
    "feedback_enabled": "boolean (required)"
  }
}

Remove a domain from a pod.

Deletes the domain from the pod.

{
  "path": {
    "pod_id": "string",
    "domain_id": "string"
  }
}

List drafts across all inboxes in a pod.

Returns drafts from all inboxes in the pod.

{
  "path": {
    "pod_id": "string"
  },
  "query": {
    "limit": "number (optional)",
    "page_token": "string (optional)",
    "labels": [
      "string (optional)"
    ],
    "before": "string (optional, ISO datetime)",
    "after": "string (optional, ISO datetime)",
    "ascending": "boolean (optional)"
  }
}

Get a draft in a pod.

Returns draft details.

{
  "path": {
    "pod_id": "string",
    "draft_id": "string"
  }
}

List inboxes in a pod.

Returns inboxes belonging to the pod.

{
  "path": {
    "pod_id": "string"
  },
  "query": {
    "limit": "number (optional)",
    "page_token": "string (optional)"
  }
}

Create an inbox in a pod.

Creates an inbox scoped to the pod.

{
  "path": {
    "pod_id": "string"
  },
  "body": {
    "username": "string (optional)",
    "domain": "string (optional)",
    "display_name": "string (optional)",
    "client_id": "string (optional)"
  }
}

Get an inbox in a pod.

Returns inbox details within the pod.

{
  "path": {
    "pod_id": "string",
    "inbox_id": "string"
  }
}

Delete an inbox from a pod.

Permanently deletes the inbox from the pod.

{
  "path": {
    "pod_id": "string",
    "inbox_id": "string"
  }
}

List threads across all inboxes in a pod.

Returns threads from all inboxes in the pod.

{
  "path": {
    "pod_id": "string"
  },
  "query": {
    "limit": "number (optional)",
    "page_token": "string (optional)",
    "labels": [
      "string (optional)"
    ],
    "before": "string (optional, ISO datetime)",
    "after": "string (optional, ISO datetime)",
    "ascending": "boolean (optional)",
    "include_spam": "boolean (optional)"
  }
}

Get a thread in a pod.

Returns the thread with all messages.

{
  "path": {
    "pod_id": "string",
    "thread_id": "string"
  }
}

Get a thread attachment in a pod.

Returns attachment metadata with download_url.

{
  "path": {
    "pod_id": "string",
    "thread_id": "string",
    "attachment_id": "string"
  }
}

List all threads across all inboxes.

Returns threads across all inboxes ordered by timestamp.

{
  "query": {
    "limit": "number (optional)",
    "page_token": "string (optional)",
    "labels": [
      "string (optional)"
    ],
    "before": "string (optional, ISO datetime)",
    "after": "string (optional, ISO datetime)",
    "ascending": "boolean (optional)",
    "include_spam": "boolean (optional)"
  }
}

Get a thread by ID.

Returns the thread with all messages.

{
  "path": {
    "thread_id": "string"
  }
}

Get a thread attachment.

Returns attachment metadata with download_url and expires_at.

{
  "path": {
    "thread_id": "string",
    "attachment_id": "string"
  }
}

Create a webhook for email events.

POST JSON body with url and event_types. Returns webhook with secret for signature verification.

{
  "body": {
    "url": "string (required, webhook endpoint URL)",
    "event_types": [
      "string (required, e.g. 'message.received', 'message.sent', 'message.delivered', 'message.bounced', 'message.complained', 'message.rejected', 'domain.verified')"
    ],
    "pod_ids": [
      "string (optional, max 10)"
    ],
    "inbox_ids": [
      "string (optional, max 10)"
    ],
    "client_id": "string (optional)"
  }
}

List all webhooks.

GET with optional pagination. Returns configured webhooks.

{
  "query": {
    "limit": "number (optional)",
    "page_token": "string (optional)"
  }
}

Delete a webhook.

Permanently deletes the webhook.

{
  "path": {
    "webhook_id": "string"
  }
}

Update webhook subscriptions.

PATCH to add/remove inbox or pod subscriptions.

{
  "path": {
    "webhook_id": "string"
  },
  "body": {
    "add_inbox_ids": [
      "string (optional)"
    ],
    "remove_inbox_ids": [
      "string (optional)"
    ],
    "add_pod_ids": [
      "string (optional)"
    ],
    "remove_pod_ids": [
      "string (optional)"
    ]
  }
}

Get webhook details.

Replace {webhook_id}. Returns webhook details including secret and enabled status.

{
  "path": {
    "webhook_id": "string"
  }
}