API Reference

Disposable email inboxes for AI agents and developers. Create temporary addresses, receive messages, and read content — all via REST. No browser required.

Base URL https://emptyinbox.me/api

Quick Start

Zero-config with MCP

Add to your MCP config and the server auto-registers on first run — no setup needed:

json 
{
  "mcpServers": {
    "emptyinbox": {
      "command": "npx",
      "args": ["-y", "emptyinbox-mcp"]
    }
  }
}

REST API workflow

  1. 1Call POST /auth/register to get an API key (one-time setup)
  2. 2Call POST /inbox to create a disposable address
  3. 3Trigger signup or verification using that address
  4. 4Poll GET /messages until the email arrives
  5. 5Read the code or link from text_body

Authentication

API Key

All endpoints except POST /auth/register require an API key in the Authorization header:

http 
Authorization: Bearer YOUR_API_KEY

Agents: call POST /auth/register below to get a key programmatically.
Humans: get your key at Settings.

Account

POST /auth/register No auth required

Create a new account and get an API key. Agent accounts start with 1 inbox quota. Rate limited to 3 registrations per IP per 24 hours.

Request Body

FieldTypeRequiredDescription
username string Required 3–32 chars, letters/numbers/hyphens/underscores

Example Request

curl 
curl -X POST "https://emptyinbox.me/api/auth/register" \
  -H "Content-Type: application/json" \
  -d '{"username": "my-agent"}'

Response

200 OK

json 
{
  "api_key": "eiXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "username": "my-agent",
  "inbox_quota": 1
}

400 Bad Request — Invalid or taken username

429 Too Many Requests — Rate limit exceeded

GET /auth/me

Returns the authenticated account's username and remaining inbox quota.

Example Request

curl 
curl "https://emptyinbox.me/api/auth/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK

json 
{
  "username": "my-agent",
  "inbox_quota": 1
}

Inbox Management

POST /inbox

Creates a new disposable email inbox. Returns the email address as plain text. Each inbox consumes 1 from your quota. Agent accounts start with 1 inbox; human accounts start with 5. Buy more at emptyinbox.me/inboxes.html.

Example Request

curl 
curl -X POST "https://emptyinbox.me/api/inbox" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

201 Created — Returns the email address as plain text

text 
clever.sunny.butterfly@emptyinbox.me

403 Forbidden — Insufficient inbox quota

GET /inboxes

Returns all inboxes on this account, newest first.

Example Request

curl 
curl "https://emptyinbox.me/api/inboxes" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK

json 
[
  {
    "inbox": "clever.sunny.butterfly@emptyinbox.me",
    "created_at": "2024-01-01T10:00:00"
  },
  {
    "inbox": "quick.blue.elephant@emptyinbox.me",
    "created_at": "2024-01-01T09:00:00"
  }
]

Message Management

GET /messages

Returns all messages across all inboxes, newest first. Messages are automatically deleted after 7 days. Poll this endpoint after triggering a signup or verification flow.

Example Request

curl 
curl "https://emptyinbox.me/api/messages" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Fields (per message)

FieldTypeDescription
idstringUnique message identifier
inboxstringEmail address that received the message
subjectstringEmail subject line
senderstringSender email address
timestampintegerUnix timestamp
text_bodystringPlain text body
html_bodystringHTML body

Example Response

json 
[
  {
    "id": "a1b2c3d4",
    "inbox": "clever.sunny.butterfly@emptyinbox.me",
    "subject": "Confirm your email address",
    "sender": "noreply@example.com",
    "timestamp": 1711234567,
    "text_body": "Your verification code is 482910",
    "html_body": "<p>Your verification code is <strong>482910</strong></p>"
  }
]
GET /message/{msgid}

Returns the full content of a specific message including all headers.

Path Parameters

ParameterTypeRequiredDescription
msgid string Required Message ID from GET /messages

Example Request

curl 
curl "https://emptyinbox.me/api/message/a1b2c3d4" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Fields

FieldTypeDescription
recipientsarrayRecipient email addresses
headersobjectRaw email headers (Subject, From, Date, etc.)
text_bodystringPlain text body
html_bodystringHTML body
senderstringSender email address

Example Response

json 
{
  "recipients": ["clever.sunny.butterfly@emptyinbox.me"],
  "headers": {
    "Subject": "Confirm your email address",
    "From": "noreply@example.com",
    "Date": "Mon, 1 Jan 2024 10:00:00 +0000"
  },
  "text_body": "Your verification code is 482910",
  "html_body": "<p>Your verification code is <strong>482910</strong></p>",
  "sender": "noreply@example.com"
}

404 Not Found — Message not found

Error Codes

StatusDescriptionCommon Causes
401 Unauthorized Missing or invalid API key
403 Forbidden Insufficient inbox quota
404 Not Found Message ID doesn't exist
429 Too Many Requests Registration rate limit exceeded (3 per IP per 24 hours)

Limits & Notes

  • Agent accounts start with 1 inbox quota; human accounts start with 5
  • Creating an inbox consumes 1 quota unit — buy more at emptyinbox.me/inboxes.html
  • Messages are automatically deleted after 7 days
  • Registration is limited to 3 new accounts per IP per 24 hours
  • Full OpenAPI 3.1 spec available at /openapi.yaml