API Reference

REST API for programmatic mailbox access. Send and read emails from your AI agents with simple HTTP calls.

Endpoints

GET /api/v1/mail GET /api/v1/mail/:id POST /api/v1/mail/send DELETE /api/v1/mail/:id

Management

GET /api/v1/domains POST /api/v1/domains POST /api/v1/domains/:id/verify DELETE /api/v1/domains/:id GET /api/v1/mailboxes POST /api/v1/mailboxes DELETE /api/v1/mailboxes/:id

Authentication

All API requests require a Bearer token in the Authorization header. Create API keys from your dashboard.

Authorization: Bearer ai_your_api_key_here

Key scoping

API keys can be scoped to a specific mailbox or left unscoped (access all mailboxes). Scoped keys don't need to pass the mailbox query parameter.

Base URL

https://agentmbox.com/api/v1

GET/api/v1/mail

List emails in a mailbox. Returns summaries sorted by most recent.

Query parameters

mailboxstring

Email address to list, e.g. agent@agentmbox.com. Not required if API key is scoped to a mailbox.

limitnumber

Max emails to return. Default 50, max 100.

offsetnumber

Pagination offset. Default 0.

Example request

curl "https://agentmbox.com/api/v1/mail?mailbox=agent@agentmbox.com&limit=10" \
  -H "Authorization: Bearer ai_your_api_key"

Response

{
  "mailbox": "agent@agentmbox.com",
  "emails": [
    {
      "id": "M1234",
      "from": [{ "name": "Alice", "email": "alice@example.com" }],
      "to": [{ "email": "agent@agentmbox.com" }],
      "subject": "Hello from Alice",
      "receivedAt": "2026-03-10T12:00:00Z",
      "preview": "Hey, just wanted to check in about...",
      "isRead": false
    }
  ],
  "limit": 10,
  "offset": 0
}

GET/api/v1/mail/:id

Fetch the full content of a single email, including body and attachments metadata.

Path parameters

idstring*

The email ID (from the list endpoint).

Query parameters

mailboxstring

Email address. Not required if API key is scoped.

Example request

curl "https://agentmbox.com/api/v1/mail/M1234?mailbox=agent@agentmbox.com" \
  -H "Authorization: Bearer ai_your_api_key"

Response

{
  "email": {
    "id": "M1234",
    "from": [{ "name": "Alice", "email": "alice@example.com" }],
    "to": [{ "email": "agent@agentmbox.com" }],
    "cc": null,
    "subject": "Hello from Alice",
    "receivedAt": "2026-03-10T12:00:00Z",
    "textBody": "Hey, just wanted to check in about the project.",
    "htmlBody": "<p>Hey, just wanted to check in about the project.</p>",
    "hasAttachment": false,
    "isRead": true
  }
}

POST/api/v1/mail/send

Send an email from one of your agent mailboxes.

Request body

fromstring*

Sender email address. Must be a mailbox you own.

tostring | string[]*

Recipient(s). A single address or an array.

subjectstring*

Email subject line.

textstring

Plain text body.

htmlstring

HTML body. If both text and html are provided, HTML takes precedence.

Example request

curl -X POST "https://agentmbox.com/api/v1/mail/send" \
  -H "Authorization: Bearer ai_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "agent@agentmbox.com",
    "to": "client@example.com",
    "subject": "Your report is ready",
    "text": "Hi, your weekly report has been generated."
  }'

Response

{
  "success": true
}

Sending to multiple recipients

{
  "from": "agent@agentmbox.com",
  "to": ["alice@example.com", "bob@example.com"],
  "subject": "Team update",
  "html": "<h1>Weekly Update</h1><p>Here are the highlights...</p>"
}

DELETE/api/v1/mail/:id

Permanently delete an email from the mailbox.

Path parameters

idstring*

The email ID to delete.

Query parameters

mailboxstring

Email address. Not required if API key is scoped.

Example request

curl -X DELETE "https://agentmbox.com/api/v1/mail/M1234?mailbox=agent@agentmbox.com" \
  -H "Authorization: Bearer ai_your_api_key"

Response

{
  "success": true
}

Management API

These endpoints use session cookie authentication (same as the dashboard) for managing domains, mailboxes, and API keys programmatically.

GET/api/v1/domains

List all custom domains for the current user. Each domain includes DNS records to configure.

Response

{
  "domains": [
    {
      "id": "uuid",
      "domain": "example.com",
      "verified": false,
      "mxVerified": false,
      "spfVerified": false,
      "dkimVerified": false,
      "dnsRecords": {
        "verification": { "type": "TXT", "name": "_agentmbox.example.com", "value": "agentmbox-verify-..." },
        "mx": { "type": "MX", "name": "example.com", "value": "mail.agentmbox.com", "priority": 10 },
        "spf": { "type": "TXT", "name": "example.com", "value": "v=spf1 include:mail.agentmbox.com ~all" }
      }
    }
  ]
}

POST/api/v1/domains

Add a custom domain. Returns DNS records to configure at your registrar.

Request body

domainstring*

The domain name, e.g. "example.com". Requires Pro plan.

POST/api/v1/domains/:id/verify

Check DNS records and update domain verification status. Performs live TXT, MX, and SPF lookups.

Path parameters

idstring*

Domain UUID.

Response

{
  "verified": true,
  "txtVerified": true,
  "mxVerified": true,
  "spfVerified": true,
  "dkimVerified": false
}

DELETE/api/v1/domains/:id

Delete a custom domain. Fails if the domain still has mailboxes.

Path parameters

idstring*

Domain UUID.

GET/api/v1/mailboxes

List all mailboxes for the current user.

Response

{
  "mailboxes": [
    {
      "id": "uuid",
      "address": "agent@agentmbox.com",
      "localPart": "agent",
      "domainName": "agentmbox.com",
      "displayName": "My Agent",
      "createdAt": "2026-03-10T12:00:00Z"
    }
  ]
}

POST/api/v1/mailboxes

Create a new mailbox. Uses @agentmbox.com by default, or a verified custom domain.

Request body

localPartstring*

The part before @, e.g. "my-agent". Letters, numbers, dots, hyphens only.

domainIdstring

UUID of a verified custom domain. Omit for @agentmbox.com.

displayNamestring

Display name for the mailbox.

DELETE/api/v1/mailboxes/:id

Permanently delete a mailbox, all its emails, and associated API keys.

Path parameters

idstring*

Mailbox UUID.

Errors

All errors return a JSON object with an error field.

{
  "error": "You are not authorized to send from this address"
}

Status	Meaning
400	Missing or invalid parameters
401	Missing or invalid API key
403	Not authorized for this resource (e.g. sending from a mailbox you don't own)
404	Mailbox or email not found
502	Mail server error (temporary, retry with backoff)

IMAP access

Every mailbox also supports standard IMAP for use with any email client.

Server	mail.agentmbox.com
Port	993
Security	TLS (implicit)
Username	your-agent@agentmbox.com
Password	Your mailbox password (shown once at creation)

SMTP access

Send emails via SMTP from any client or framework.

Server	mail.agentmbox.com
Port	465
Security	TLS (implicit)
Username	your-agent@agentmbox.com
Password	Your mailbox password