agentmail docs
ConsoleAPI Reference

Quickstart

Go from zero to sending your first email in under 5 minutes. All you need is an API key.

Base URL: https://your-instance.com/api/v0

1

Get an API key

Create an API key from the console or via the API. The full key is returned only once, so store it safely.

Create an API key
curl -X POST https://your-instance.com/api/v0/api-keys \
  -H "Authorization: Bearer <ADMIN_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent-key"}'
Response
{
  "key_id": "abc123",
  "name": "my-agent-key",
  "prefix": "inai_xxxx_...",
  "key": "inai_xxxx_full_key_shown_once",
  "created_at": "2025-01-15T10:30:00.000Z"
}
2

Create an inbox

An inbox provisions a real mailbox. You specify a username and optionally a domain (defaults to the platform's default domain).

POST /api/v0/inboxes
curl -X POST https://your-instance.com/api/v0/inboxes \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "agent-1",
    "display_name": "Agent One"
  }'
Response
{
  "inbox_id": "nk8x2j...",
  "email_address": "agent-1@yourdomain.com",
  "username": "agent-1",
  "domain": "yourdomain.com",
  "display_name": "Agent One",
  "created_at": "2025-01-15T10:31:00.000Z"
}
3

Send an email

Use the send endpoint with the inbox ID from step 2. You can send plain text, HTML, or both.

POST /api/v0/inboxes/:id/messages/send
curl -X POST https://your-instance.com/api/v0/inboxes/nk8x2j.../messages/send \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "subject": "Hello from agentmail",
    "text": "This is a test email sent via the agentmail API."
  }'
Response
{
  "message_id": "msg_abc123",
  "thread_id": "thr_xyz789"
}
4

List messages

Retrieve all messages in the inbox, including both sent and received emails. Results are paginated.

GET /api/v0/inboxes/:id/messages
curl https://your-instance.com/api/v0/inboxes/nk8x2j.../messages \
  -H "Authorization: Bearer <API_KEY>"
Response
{
  "data": [
    {
      "message_id": "msg_abc123",
      "direction": "outbound",
      "from": "Agent One <agent-1@yourdomain.com>",
      "to": ["recipient@example.com"],
      "subject": "Hello from agentmail",
      "preview": "This is a test email sent via the agentmail API.",
      "timestamp": "2025-01-15T10:32:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20
}
5

Set up a webhook

Webhooks notify your application when email events occur. Subscribe to specific event types and optionally filter by inbox.

POST /api/v0/webhooks
curl -X POST https://your-instance.com/api/v0/webhooks \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/email",
    "event_types": ["message.received", "message.sent"]
  }'
Response
{
  "webhook_id": "wh_abc123",
  "url": "https://your-app.com/webhooks/email",
  "event_types": ["message.received", "message.sent"],
  "enabled": true,
  "created_at": "2025-01-15T10:33:00.000Z"
}

What's next?

  • • Add a custom domain for branded email addresses
  • • Use reply and reply-all to respond to incoming emails programmatically
  • • Browse the full API Reference for all available endpoints