Skip to content
RUN MAIL
EN AR
Log in Sign up

API documentation

Base path /api/runmail/v1 — authenticate with Bearer or X-Api-Key.

Overview

RUN MAIL exposes a versioned public API for creating mailboxes and reading messages. Website guests use AJAX cookies; integrations use API keys.

  • Base URL: /api/runmail/v1
  • JSON request and response bodies
  • Mailbox types: temp, disposable, developer
  • Mailbox-scoped operations require X-Mailbox-Token
Base URL
/api/runmail/v1

Authentication

Send your API key as Authorization: Bearer or X-Api-Key. After creating a mailbox, pass X-Mailbox-Token with the access_token from the create response.

HeaderExample
Authorization Bearer rm_live_...
X-Api-Key rm_live_...
X-Mailbox-Token <access_token from create>

Scope: *, mailboxes:read, mailboxes:write, messages:read, messages:write, domains:read, usage:read

Guests on this website never need an API key — the inbox uses session cookies via /ajax.

Mailboxes

POST /api/runmail/v1/mailboxes mailboxes:write

Create a mailbox. Returns email, uuid, and access_token.

Request

JSON 
{
    "type": "temp | disposable | developer",
    "ttl": 3600,
    "local_part": "optional-local"
}

Response

JSON 
{
    "success": true,
    "data": {
        "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "email": "[email protected]",
        "access_token": "mbx_...",
        "expires_at": 1710000000,
        "type": "temp"
    }
}
POST /api/runmail/v1/mailboxes/rotate mailboxes:write

Rotate an existing mailbox (new address + token).

Headers: X-Mailbox-Token

Request

JSON 
{
    "uuid": "mailbox-uuid",
    "type": "temp",
    "ttl": 7200
}

Response

JSON 
{
    "success": true,
    "data": {
        "uuid": "new-uuid",
        "email": "[email protected]",
        "access_token": "mbx_...",
        "expires_at": 1710007200,
        "type": "temp"
    }
}
GET /api/runmail/v1/mailboxes/{uuid} mailboxes:read

Fetch mailbox metadata and unread count.

Headers: X-Mailbox-Token

Response

JSON 
{
    "success": true,
    "data": {
        "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "email": "[email protected]",
        "expires_at": 1710000000,
        "type": "temp"
    }
}
DELETE /api/runmail/v1/mailboxes/{uuid} mailboxes:write

docs_ep_delete_mb

Headers: X-Mailbox-Token

Response

JSON 
{
    "success": true,
    "data": {
        "deleted": true
    }
}

Messages

GET /api/runmail/v1/mailboxes/{uuid}/messages messages:read

List messages for a mailbox (paginated).

Headers: X-Mailbox-Token

Parameters: limit=50, offset=0

Response

JSON 
{
    "success": true,
    "data": {
        "messages": [
            {
                "id": "msg_1",
                "from": "[email protected]",
                "to": "[email protected]",
                "subject": "Verify your email",
                "received_at": 1710000100
            }
        ],
        "total": 1
    }
}
GET /api/runmail/v1/mailboxes/{uuid}/messages/{id} messages:read

Fetch a single message including body.

Headers: X-Mailbox-Token

Response

JSON 
{
    "success": true,
    "data": {
        "id": "msg_1",
        "from": "[email protected]",
        "to": "[email protected]",
        "subject": "Verify your email",
        "text": "Your code is 123456",
        "html": "<p>Your code is <strong>123456</strong></p>",
        "received_at": 1710000100
    }
}
DELETE /api/runmail/v1/mailboxes/{uuid}/messages/{id} messages:write

docs_ep_delete_msg

Headers: X-Mailbox-Token

Response

JSON 
{
    "success": true,
    "data": {
        "deleted": true
    }
}

Domains

GET /api/runmail/v1/domains domains:read

docs_ep_list_domains

Response

JSON 
{
    "success": true,
    "data": {
        "domains": [
            {
                "domain": "example.com",
                "status": "active"
            }
        ]
    }
}

Usage & realtime

GET /api/runmail/v1/usage usage:read

Usage summary for the authenticated key.

Response

JSON 
{
    "success": true,
    "data": {
        "mailboxes_created": 12,
        "messages_received": 48,
        "period": "30d"
    }
}

API Keys

Create and revoke keys from the API Keys page (administrators). Secrets are shown once at creation.

Store keys in your secret manager. Prefer least-privilege scopes over * when possible.

API Keys

Rate limits

Requests are rate-limited per IP and API key. Exceeding limits returns HTTP 429.

  • Website polling and sync endpoints have separate budgets.
  • API create/rotate share abuse protection with the rest of the surface.
  • Backoff and retry with jitter when you receive 429.

Errors

Failures return success: false with an error object.

JSON
{
    "success": false,
    "error": {
        "code": "rm_auth",
        "message": "Invalid API key"
    }
}
HTTPMeaning
401 Missing or invalid API key
403 Insufficient scope or mailbox token mismatch
429 Rate limited — slow down
500 Server or provider failure