API Documentation

Base URL: https://api.agentmail.email

Quick Start

Get from zero to receiving email in five steps.

curl
curl -X POST https://api.agentmail.email/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

Verify your email & get your API key

Click the link in your email, or:

curl
curl "https://api.agentmail.email/v1/auth/verify?token=YOUR_TOKEN"

# → {"api_key": "ak_live_..."}

Create a mailbox

curl
curl -X POST https://api.agentmail.email/v1/mailboxes \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"prefix": "myapp"}'

# → {"address": "myapp-7f3k@agentmail.email", ...}

Receive email (long-poll)

curl
curl "https://api.agentmail.email/v1/mailboxes/myapp-7f3k@agentmail.email/messages?wait=30" \
  -H "Authorization: Bearer ak_live_..."

# Blocks up to 30s until a message arrives

Send email

curl
curl -X POST https://api.agentmail.email/v1/mailboxes/myapp-7f3k@agentmail.email/send \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"to": "someone@example.com", "subject": "Hello", "body_text": "Hi from my agent!"}'

Authentication

All API requests (except signup and verify) require an API key passed as a Bearer token:

Authorization: Bearer ak_live_your_api_key

Sign Up

POST/v1/auth/signup

Create an account. Sends a verification email. No auth required.

Response — 200
{
  "message": "Verification email sent to you@example.com"
}

Verify Email

GET/v1/auth/verify?token=TOKEN

Verify your account and receive your API key. No auth required.

Request
curl "https://api.agentmail.email/v1/auth/verify?token=YOUR_TOKEN"

Request
import requests

resp = requests.get("https://api.agentmail.email/v1/auth/verify",
    params={"token": "YOUR_TOKEN"})
print(resp.json())

Response — 200
{
  "api_key": "ak_live_abc123def456",
  "email": "you@example.com"
}

Reset API Key

POST/v1/auth/reset-key

Request a new API key. Sends a re-verification email. No auth required.

Request
curl -X POST https://api.agentmail.email/v1/auth/reset-key \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

Request
import requests

resp = requests.post("https://api.agentmail.email/v1/auth/reset-key",
    json={"email": "you@example.com"})
print(resp.json())

Response — 200
{
  "message": "Verification email sent. Click the link to get your new API key."
}

Get Usage

GET/v1/auth/usage

Returns your current plan, usage counts, and limits. Auth required.

Request
curl https://api.agentmail.email/v1/auth/usage \
  -H "Authorization: Bearer ak_live_..."

Request
import requests

resp = requests.get("https://api.agentmail.email/v1/auth/usage",
    headers={"Authorization": "Bearer ak_live_..."})
print(resp.json())

Response — 200
{
  "plan": "free",
  "mailboxes": {"used": 2, "limit": 5},
  "messages": {"used": 142, "limit": 500},
  "sends": {"used": 8, "limit": 50}
}

Create Mailbox

POST/v1/mailboxes

Create a new mailbox. Optionally set a prefix, TTL, or make it persistent.

Request
curl -X POST https://api.agentmail.email/v1/mailboxes \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"prefix": "myapp", "ttl_seconds": 86400, "persistent": false}'

Request
import requests

resp = requests.post("https://api.agentmail.email/v1/mailboxes",
    headers={"Authorization": "Bearer ak_live_..."},
    json={"prefix": "myapp", "ttl_seconds": 86400, "persistent": False})
print(resp.json())

Response — 201
{
  "address": "myapp-7f3k@agentmail.email",
  "prefix": "myapp",
  "persistent": false,
  "ttl_seconds": 86400,
  "created_at": "2025-01-15T09:30:00Z",
  "expires_at": "2025-01-16T09:30:00Z"
}

Body parameters:

prefix — optional string prefix for the address
ttl_seconds — auto-delete after N seconds (default: none)
persistent — if true, mailbox won't expire (default: false)

List Mailboxes

GET/v1/mailboxes

List all your mailboxes.

Request
curl https://api.agentmail.email/v1/mailboxes \
  -H "Authorization: Bearer ak_live_..."

Request
import requests

resp = requests.get("https://api.agentmail.email/v1/mailboxes",
    headers={"Authorization": "Bearer ak_live_..."})
print(resp.json())

Response — 200
{
  "mailboxes": [
    {
      "address": "myapp-7f3k@agentmail.email",
      "persistent": false,
      "created_at": "2025-01-15T09:30:00Z",
      "expires_at": "2025-01-16T09:30:00Z"
    }
  ]
}

Delete Mailbox

DELETE/v1/mailboxes/{address}

Delete a mailbox and all its messages.

Request
curl -X DELETE https://api.agentmail.email/v1/mailboxes/myapp-7f3k@agentmail.email \
  -H "Authorization: Bearer ak_live_..."

Request
import requests

resp = requests.delete("https://api.agentmail.email/v1/mailboxes/myapp-7f3k@agentmail.email",
    headers={"Authorization": "Bearer ak_live_..."})
print(resp.status_code)

Response — 204
# No content

List Messages

GET/v1/mailboxes/{address}/messages

List messages in a mailbox. Supports long-polling with ?wait=N (seconds, max 120).

Request
# Instant response
curl https://api.agentmail.email/v1/mailboxes/myapp-7f3k@agentmail.email/messages \
  -H "Authorization: Bearer ak_live_..."

# Long-poll: wait up to 60 seconds for new messages
curl "https://api.agentmail.email/v1/mailboxes/myapp-7f3k@agentmail.email/messages?wait=60" \
  -H "Authorization: Bearer ak_live_..."

Request
import requests

# Long-poll for up to 60 seconds
resp = requests.get(
    "https://api.agentmail.email/v1/mailboxes/myapp-7f3k@agentmail.email/messages",
    headers={"Authorization": "Bearer ak_live_..."},
    params={"wait": 60},
    timeout=65)
print(resp.json())

Response — 200
{
  "messages": [
    {
      "id": "msg_abc123",
      "from": "noreply@reddit.com",
      "subject": "Verify your email",
      "received_at": "2025-01-15T09:35:12Z",
      "snippet": "Click here to verify your account..."
    }
  ]
}

Get Message

GET/v1/messages/{message_id}

Get the full content of a received message.

Request
curl https://api.agentmail.email/v1/messages/msg_abc123 \
  -H "Authorization: Bearer ak_live_..."

Request
import requests

resp = requests.get("https://api.agentmail.email/v1/messages/msg_abc123",
    headers={"Authorization": "Bearer ak_live_..."})
print(resp.json())

Response — 200
{
  "id": "msg_abc123",
  "mailbox": "myapp-7f3k@agentmail.email",
  "from": "noreply@reddit.com",
  "to": "myapp-7f3k@agentmail.email",
  "subject": "Verify your email",
  "body_text": "Click here to verify: https://reddit.com/verify?token=...",
  "body_html": "<html>...</html>",
  "received_at": "2025-01-15T09:35:12Z"
}

Send Email

POST/v1/mailboxes/{address}/send

Send an email from your mailbox.

Request
curl -X POST https://api.agentmail.email/v1/mailboxes/myapp-7f3k@agentmail.email/send \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "subject": "Hello",
    "body_text": "Hello from my agent!",
    "body_html": "<h1>Hello</h1><p>From my agent!</p>"
  }'

Request
import requests

resp = requests.post(
    "https://api.agentmail.email/v1/mailboxes/myapp-7f3k@agentmail.email/send",
    headers={"Authorization": "Bearer ak_live_..."},
    json={
        "to": "recipient@example.com",
        "subject": "Hello",
        "body_text": "Hello from my agent!",
        "body_html": "<h1>Hello</h1><p>From my agent!</p>"
    })
print(resp.json())

Response — 200
{
  "id": "sent_xyz789",
  "from": "myapp-7f3k@agentmail.email",
  "to": "recipient@example.com",
  "subject": "Hello",
  "sent_at": "2025-01-15T10:00:00Z"
}

Body parameters:

to — recipient email address (required)
subject — email subject (required)
body_text — plain text body
body_html — HTML body

List Sent Messages

GET/v1/mailboxes/{address}/sent

List messages sent from a mailbox.

Request
curl https://api.agentmail.email/v1/mailboxes/myapp-7f3k@agentmail.email/sent \
  -H "Authorization: Bearer ak_live_..."

Request
import requests

resp = requests.get(
    "https://api.agentmail.email/v1/mailboxes/myapp-7f3k@agentmail.email/sent",
    headers={"Authorization": "Bearer ak_live_..."})
print(resp.json())

Response — 200
{
  "messages": [
    {
      "id": "sent_xyz789",
      "to": "recipient@example.com",
      "subject": "Hello",
      "sent_at": "2025-01-15T10:00:00Z"
    }
  ]
}

Get Sent Message

GET/v1/sent/{message_id}

Get full details of a sent message.

Request
curl https://api.agentmail.email/v1/sent/sent_xyz789 \
  -H "Authorization: Bearer ak_live_..."

Request
import requests

resp = requests.get("https://api.agentmail.email/v1/sent/sent_xyz789",
    headers={"Authorization": "Bearer ak_live_..."})
print(resp.json())

Response — 200
{
  "id": "sent_xyz789",
  "from": "myapp-7f3k@agentmail.email",
  "to": "recipient@example.com",
  "subject": "Hello",
  "body_text": "Hello from my agent!",
  "body_html": "<h1>Hello</h1><p>From my agent!</p>",
  "sent_at": "2025-01-15T10:00:00Z"
}

Set Webhook

POST/v1/webhooks

Set a webhook URL for a mailbox. Incoming messages will be POSTed to your URL.

Request
curl -X POST https://api.agentmail.email/v1/webhooks \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "address": "myapp-7f3k@agentmail.email",
    "url": "https://your-server.com/hook"
  }'

Request
import requests

resp = requests.post("https://api.agentmail.email/v1/webhooks",
    headers={"Authorization": "Bearer ak_live_..."},
    json={
        "address": "myapp-7f3k@agentmail.email",
        "url": "https://your-server.com/hook"
    })
print(resp.json())

Response — 201
{
  "address": "myapp-7f3k@agentmail.email",
  "url": "https://your-server.com/hook",
  "created_at": "2025-01-15T10:05:00Z"
}

Remove Webhook

DELETE/v1/webhooks/{address}

Remove a webhook from a mailbox.

Request
curl -X DELETE https://api.agentmail.email/v1/webhooks/myapp-7f3k@agentmail.email \
  -H "Authorization: Bearer ak_live_..."

Request
import requests

resp = requests.delete("https://api.agentmail.email/v1/webhooks/myapp-7f3k@agentmail.email",
    headers={"Authorization": "Bearer ak_live_..."})
print(resp.status_code)

Response — 204
# No content

Pricing

Free

$0/month

5 mailboxes
500 messages/month
50 sends/month

Pro

$9/month

50 mailboxes
10,000 messages/month
500 sends/month