AgentMail API

Create and manage email inboxes for AI agents. Send, receive, and reply to emails in threads via AgentMail's REST API.

Official docs: https://docs.agentmail.to

When to Use

Use this skill when you need to:

• Create email inboxes for AI agents on the fly
• Send emails and reply to conversation threads
• Manage drafts with scheduled sending
• Set up webhooks for real-time email event notifications
• Register and verify custom sending domains
• Organize inboxes with pods
• Track email delivery metrics

Scenarios

1. Customer Support Agent

An AI agent handles inbound support emails automatically.

1. Create a dedicated inbox for support: POST /v0/inboxes with username: "support"
2. Register a webhook listening for message.received: POST /v0/webhooks with inbox_ids scoped to the support inbox
3. When a customer emails support@agentmail.to, the webhook fires with the message payload
4. Read the full thread for context: GET /v0/inboxes/{inbox-id}/threads/{thread-id}
5. Generate a response with your LLM, then reply in-thread: POST /v0/inboxes/{inbox-id}/messages/{message-id}/reply
6. Update labels to track state: PATCH /v0/inboxes/{inbox-id}/messages/{message-id} with add_labels: ["replied"], remove_labels: ["unreplied"]
7. Periodically check for stale threads: GET /v0/inboxes/{inbox-id}/threads?labels=unreplied to find conversations that still need attention

2. Sales Outreach with Scheduled Follow-ups

An AI agent sends personalized cold emails and manages follow-up sequences.

1. Create an inbox per sales campaign: POST /v0/inboxes with client_id: "campaign-q1" for idempotency
2. Send initial outreach: POST /v0/inboxes/{inbox-id}/messages/send with personalized subject/body
3. Create scheduled follow-up drafts for non-responders: POST /v0/inboxes/{inbox-id}/drafts with send_at set to 3 days later
4. Register a webhook for message.received to detect replies
5. When a prospect replies, cancel the scheduled draft: DELETE /v0/inboxes/{inbox-id}/drafts/{draft-id}
6. Monitor delivery health: GET /v0/metrics?event_types=message.bounced&event_types=message.complained to detect reputation issues early

3. Document Processing Pipeline

An AI agent receives documents via email, processes them, and sends results back.

1. Create an inbox: POST /v0/inboxes with username: "doc-processor"
2. Set up a webhook for message.received
3. When an email arrives with attachments, the webhook payload includes attachment metadata
4. Download the attachment: GET /v0/inboxes/{inbox-id}/messages/{message-id}/attachments/{attachment-id} → returns a temporary download_url
5. Download and process the file (OCR, summarization, data extraction, etc.)
6. Reply with results: POST /v0/inboxes/{inbox-id}/messages/{message-id}/reply including processed output in the body or a new attachment

4. Multi-Agent Team Coordination

Multiple AI agents each have their own inbox, organized by team.

1. Create a pod for the team: POST /v0/pods with name: "Research Team"
2. Create an inbox per agent with pod_id: POST /v0/inboxes for each agent (e.g. researcher-1, researcher-2, summarizer)
3. Set up per-inbox webhooks to route events to each agent's handler: POST /v0/webhooks with inbox_ids scoped per agent
4. Agents send emails to each other using their @agentmail.to addresses for inter-agent communication
5. List all inboxes in the pod for oversight: GET /v0/inboxes filtered by pod

5. Human-in-the-Loop Draft Approval

An AI agent drafts emails for human review before sending.

1. Create a draft with the AI-generated content: POST /v0/inboxes/{inbox-id}/drafts
2. Notify the human reviewer (via Slack, UI, etc.) with the draft ID
3. Human reviews the draft: GET /v0/inboxes/{inbox-id}/drafts/{draft-id}
4. If approved, send the draft: POST /v0/inboxes/{inbox-id}/drafts/{draft-id}/send
5. If changes needed, update and re-review: PATCH /v0/inboxes/{inbox-id}/drafts/{draft-id} with revised content
6. If rejected, delete the draft: DELETE /v0/inboxes/{inbox-id}/drafts/{draft-id}

6. Ephemeral Inboxes for One-off Tasks

Create disposable inboxes for short-lived tasks, then clean up.

1. Create a temporary inbox with client_id tied to the task ID: POST /v0/inboxes with client_id: "task-abc123"
2. Use the inbox to send/receive emails for this specific task (e.g. verifying an account, requesting info from an external party)
3. Poll or webhook for responses
4. When the task is complete, delete the inbox: DELETE /v0/inboxes/{inbox-id} — all associated threads and messages are cleaned up

7. Email Monitoring and Analytics

Track email delivery health across all agent inboxes.

1. Query delivery metrics over a time range: GET /v0/metrics?start_timestamp=...&end_timestamp=...
2. Filter by event type to find problems: GET /v0/metrics?event_types=message.bounced&event_types=message.rejected
3. If bounce rates are high, investigate specific inboxes using GET /v0/inboxes/{inbox-id}/messages?labels=bounced
4. Set up a webhook for message.bounced and message.complained to get real-time alerts on deliverability issues

8. Inbound Lead Qualification

An AI agent triages inbound emails and routes them appropriately.

1. Create an inbox as the public-facing entry point: POST /v0/inboxes with username: "hello"
2. Register a webhook for message.received
3. When a new email arrives, use your LLM to classify intent (sales inquiry, support request, partnership, spam)
4. Label the message by category: PATCH /v0/inboxes/{inbox-id}/messages/{message-id} with add_labels: ["sales-lead"]
5. Send an auto-acknowledgment: POST /v0/inboxes/{inbox-id}/messages/{message-id}/reply
6. Forward to the right team by sending a new email from a different inbox or notifying via webhook
7. Review unhandled messages: GET /v0/inboxes/{inbox-id}/messages?labels=needs-review

Prerequisites

1. Sign up at https://console.agentmail.to
2. Go to API Keys section and create a new key

Set environment variable:

export AGENTMAIL_TOKEN="your-api-key"

Placeholders: Values in {curly-braces} like {inbox-id} are placeholders. Replace them with actual values when executing.

Inboxes

Create Inbox

curl -s -X POST "https://api.agentmail.to/v0/inboxes" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" --header "Content-Type: application/json" -d '{"username": "my-agent", "display_name": "My Agent"}' | jq .

Create with idempotent client_id (safe to retry without creating duplicates):

curl -s -X POST "https://api.agentmail.to/v0/inboxes" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" --header "Content-Type: application/json" -d '{"username": "my-agent", "display_name": "My Agent", "client_id": "my-agent-inbox"}' | jq .

List Inboxes

curl -s "https://api.agentmail.to/v0/inboxes" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" | jq .

With pagination:

curl -s "https://api.agentmail.to/v0/inboxes?limit=10" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" | jq .

Get Inbox

curl -s "https://api.agentmail.to/v0/inboxes/{inbox-id}" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" | jq .

Update Inbox

curl -s -X PATCH "https://api.agentmail.to/v0/inboxes/{inbox-id}" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" --header "Content-Type: application/json" -d '{"display_name": "New Name"}' | jq .

Delete Inbox

curl -s -X DELETE "https://api.agentmail.to/v0/inboxes/{inbox-id}" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)"

Messages

Send Email

Write to /tmp/agentmail_request.json:

{
  "to": ["recipient@example.com"],
  "subject": "Hello from my agent",
  "text": "Plain text body",
  "html": "<p>HTML body</p>"
}

Then run:

curl -s -X POST "https://api.agentmail.to/v0/inboxes/{inbox-id}/messages/send" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" --header "Content-Type: application/json" -d @/tmp/agentmail_request.json' | jq .

Send Email with CC/BCC

Write to /tmp/agentmail_request.json:

{
  "to": ["recipient@example.com"],
  "cc": ["cc@example.com"],
  "bcc": ["bcc@example.com"],
  "subject": "Hello",
  "text": "Plain text body",
  "html": "<p>HTML body</p>"
}

Then run:

curl -s -X POST "https://api.agentmail.to/v0/inboxes/{inbox-id}/messages/send" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" --header "Content-Type: application/json" -d @/tmp/agentmail_request.json' | jq .

Send Email with Labels

Write to /tmp/agentmail_request.json:

{
  "to": ["recipient@example.com"],
  "subject": "Hello",
  "text": "Plain text body",
  "labels": ["outreach", "onboarding"]
}

Then run:

curl -s -X POST "https://api.agentmail.to/v0/inboxes/{inbox-id}/messages/send" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" --header "Content-Type: application/json" -d @/tmp/agentmail_request.json' | jq .

Send Email with Attachment

Write to /tmp/agentmail_request.json:

{
  "to": ["recipient@example.com"],
  "subject": "Report attached",
  "text": "Please find the report attached.",
  "attachments": [
    {
      "filename": "report.txt",
      "content_type": "text/plain",
      "content": "<base64-encoded-content>"
    }
  ]
}

Then run:

curl -s -X POST "https://api.agentmail.to/v0/inboxes/{inbox-id}/messages/send" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" --header "Content-Type: application/json" -d @/tmp/agentmail_request.json' | jq .

To base64 encode a file:

base64 -w 0 /path/to/file.pdf

Reply to Message

Write to /tmp/agentmail_request.json:

{
  "text": "Thanks for your message!",
  "html": "<p>Thanks for your message!</p>"
}

Then run:

curl -s -X POST "https://api.agentmail.to/v0/inboxes/{inbox-id}/messages/{message-id}/reply" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" --header "Content-Type: application/json" -d @/tmp/agentmail_request.json' | jq .

Reply All

Write to /tmp/agentmail_request.json:

{
  "reply_all": true,
  "text": "Thanks everyone!",
  "html": "<p>Thanks everyone!</p>"
}

Then run:

curl -s -X POST "https://api.agentmail.to/v0/inboxes/{inbox-id}/messages/{message-id}/reply" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" --header "Content-Type: application/json" -d @/tmp/agentmail_request.json' | jq .

List Messages

curl -s "https://api.agentmail.to/v0/inboxes/{inbox-id}/messages" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" | jq .

With filters:

curl -s "https://api.agentmail.to/v0/inboxes/{inbox-id}/messages?labels=unreplied&limit=10" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" | jq .

Get Message

curl -s "https://api.agentmail.to/v0/inboxes/{inbox-id}/messages/{message-id}" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" | jq .

Update Message Labels

Write to /tmp/agentmail_request.json:

{
  "add_labels": ["replied"],
  "remove_labels": ["unreplied"]
}

Then run:

curl -s -X PATCH "https://api.agentmail.to/v0/inboxes/{inbox-id}/messages/{message-id}" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" --header "Content-Type: application/json" -d @/tmp/agentmail_request.json' | jq .

Get Message Attachment

curl -s "https://api.agentmail.to/v0/inboxes/{inbox-id}/messages/{message-id}/attachments/{attachment-id}" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" | jq .

Returns a download_url (temporary pre-signed URL) and expires_at. Download the file:

curl -s -o attachment.bin "{download-url}"

Threads

List Threads

curl -s "https://api.agentmail.to/v0/inboxes/{inbox-id}/threads" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" | jq .

With filters:

curl -s "https://api.agentmail.to/v0/inboxes/{inbox-id}/threads?labels=unreplied&after=2025-01-01T00:00:00Z&limit=10" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" | jq .

Get Thread

Returns thread with all messages ordered by timestamp ascending:

curl -s "https://api.agentmail.to/v0/inboxes/{inbox-id}/threads/{thread-id}" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" | jq .

Get Thread Attachment

curl -s "https://api.agentmail.to/v0/inboxes/{inbox-id}/threads/{thread-id}/attachments/{attachment-id}" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" | jq .

Delete Thread

curl -s -X DELETE "https://api.agentmail.to/v0/inboxes/{inbox-id}/threads/{thread-id}" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)"

Drafts

Create Draft

Write to /tmp/agentmail_request.json:

{
  "to": ["recipient@example.com"],
  "subject": "Draft email",
  "text": "This is a draft.",
  "html": "<p>This is a draft.</p>"
}

Then run:

curl -s -X POST "https://api.agentmail.to/v0/inboxes/{inbox-id}/drafts" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" --header "Content-Type: application/json" -d @/tmp/agentmail_request.json' | jq .

Create Scheduled Draft

Write to /tmp/agentmail_request.json:

{
  "to": ["recipient@example.com"],
  "subject": "Scheduled email",
  "text": "This will be sent later.",
  "send_at": "2025-12-01T10:00:00Z"
}

Then run:

curl -s -X POST "https://api.agentmail.to/v0/inboxes/{inbox-id}/drafts" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" --header "Content-Type: application/json" -d @/tmp/agentmail_request.json' | jq .

List Drafts

curl -s "https://api.agentmail.to/v0/inboxes/{inbox-id}/drafts" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" | jq .

Get Draft

curl -s "https://api.agentmail.to/v0/inboxes/{inbox-id}/drafts/{draft-id}" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" | jq .

Update Draft

Write to /tmp/agentmail_request.json:

{
  "subject": "Updated subject",
  "text": "Updated body"
}

Then run:

curl -s -X PATCH "https://api.agentmail.to/v0/inboxes/{inbox-id}/drafts/{draft-id}" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" --header "Content-Type: application/json" -d @/tmp/agentmail_request.json' | jq .

Send Draft

curl -s -X POST "https://api.agentmail.to/v0/inboxes/{inbox-id}/drafts/{draft-id}/send" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" --header "Content-Type: application/json" -d '{}' | jq .

Delete Draft

curl -s -X DELETE "https://api.agentmail.to/v0/inboxes/{inbox-id}/drafts/{draft-id}" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)"

Webhooks

Create Webhook

Write to /tmp/agentmail_request.json:

{
  "url": "https://your-server.com/webhooks",
  "event_types": ["message.received", "message.sent", "message.delivered"],
  "client_id": "my-webhook"
}

Then run:

curl -s -X POST "https://api.agentmail.to/v0/webhooks" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" --header "Content-Type: application/json" -d @/tmp/agentmail_request.json' | jq .

Supported event types: message.received, message.sent, message.delivered, message.bounced, message.complained, message.rejected, domain.verified

Create Webhook for Specific Inboxes

Write to /tmp/agentmail_request.json:

{
  "url": "https://your-server.com/webhooks",
  "event_types": ["message.received"],
  "inbox_ids": ["{inbox-id-1}", "{inbox-id-2}"],
  "client_id": "inbox-webhook"
}

Then run:

curl -s -X POST "https://api.agentmail.to/v0/webhooks" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" --header "Content-Type: application/json" -d @/tmp/agentmail_request.json' | jq .

List Webhooks

curl -s "https://api.agentmail.to/v0/webhooks" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" | jq .

Get Webhook

curl -s "https://api.agentmail.to/v0/webhooks/{webhook-id}" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" | jq .

Update Webhook (Add/Remove Inboxes)

Write to /tmp/agentmail_request.json:

{
  "add_inbox_ids": ["{new-inbox-id}"],
  "remove_inbox_ids": ["{old-inbox-id}"]
}

Then run:

curl -s -X PATCH "https://api.agentmail.to/v0/webhooks/{webhook-id}" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" --header "Content-Type: application/json" -d @/tmp/agentmail_request.json' | jq .

Delete Webhook

curl -s -X DELETE "https://api.agentmail.to/v0/webhooks/{webhook-id}" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)"

Domains

Create Domain

curl -s -X POST "https://api.agentmail.to/v0/domains" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" --header "Content-Type: application/json" -d '{"domain": "yourdomain.com", "feedback_enabled": true}' | jq .

Returns DNS records (TXT, CNAME, MX) that must be added to your DNS provider.

List Domains

curl -s "https://api.agentmail.to/v0/domains" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" | jq .

Get Domain

curl -s "https://api.agentmail.to/v0/domains/{domain-id}" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" | jq .

Verify Domain

Trigger DNS verification after adding records:

curl -s -X POST "https://api.agentmail.to/v0/domains/{domain-id}/verify" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)"

Domain status values: NOT_STARTED, PENDING, INVALID, FAILED, VERIFYING, VERIFIED

Delete Domain

curl -s -X DELETE "https://api.agentmail.to/v0/domains/{domain-id}" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)"

Pods

Pods are organizational groups for inboxes.

Create Pod

curl -s -X POST "https://api.agentmail.to/v0/pods" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" --header "Content-Type: application/json" -d '{"name": "Support Team", "client_id": "support-pod"}' | jq .

List Pods

curl -s "https://api.agentmail.to/v0/pods" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" | jq .

Get Pod

curl -s "https://api.agentmail.to/v0/pods/{pod-id}" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" | jq .

Delete Pod

curl -s -X DELETE "https://api.agentmail.to/v0/pods/{pod-id}" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)"

Metrics

Get Delivery Metrics

curl -s "https://api.agentmail.to/v0/metrics?start_timestamp=2025-01-01T00:00:00Z&end_timestamp=2025-12-31T23:59:59Z" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" | jq .

Filter by event type:

curl -s "https://api.agentmail.to/v0/metrics?start_timestamp=2025-01-01T00:00:00Z&end_timestamp=2025-12-31T23:59:59Z&event_types=message.sent&event_types=message.bounced" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" | jq .

Supported event types: message.sent, message.delivered, message.bounced, message.delayed, message.rejected, message.complained, message.received

API Keys

List API Keys

curl -s "https://api.agentmail.to/v0/api-keys" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" | jq .

Create API Key

curl -s -X POST "https://api.agentmail.to/v0/api-keys" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)" --header "Content-Type: application/json" -d '{"name": "production-key"}' | jq .

The api_key value is only returned once at creation time. Save it immediately.

Delete API Key

curl -s -X DELETE "https://api.agentmail.to/v0/api-keys/{api-key}" --header "Authorization: Bearer $(printenv AGENTMAIL_TOKEN)"

Webhook Event Payload

When a webhook fires, AgentMail sends a POST request with this JSON payload:

{
  "type": "event",
  "event_type": "message.received",
  "event_id": "unique-event-id",
  "message": {
    "inbox_id": "...",
    "thread_id": "...",
    "message_id": "...",
    "from": "sender@example.com",
    "to": ["your-inbox@agentmail.to"],
    "subject": "Hello",
    "text": "Message body",
    "html": "<p>Message body</p>",
    "attachments": []
  },
  "thread": {
    "thread_id": "...",
    "subject": "Hello",
    "message_count": 1
  }
}

Your endpoint should return HTTP 200 immediately and process the payload asynchronously.

Send Parameters Reference

Response Codes

Guidelines

1. Always send both text and HTML: Provide both formats for best deliverability across email clients
2. Use client_id for idempotency: When creating inboxes, webhooks, or drafts, use client_id to prevent duplicates on retries
3. Use labels for state tracking: Tag messages as unreplied/replied to manage conversation state
4. Use webhooks over polling: Webhooks are the recommended way to handle incoming emails in production
5. Custom domains improve deliverability: Set up verified custom domains for production use
6. Default domain: Without a custom domain, inboxes use @agentmail.to
7. Webhook response: Return HTTP 200 immediately from webhook endpoints; process payloads asynchronously

API Reference

• Documentation: https://docs.agentmail.to
• API Reference: https://docs.agentmail.to/api-reference/inboxes/list
• Console: https://console.agentmail.to
• Quickstart: https://docs.agentmail.to/quickstart
• Node.js SDK: https://www.npmjs.com/package/agentmail
• Python SDK: pip install agentmail