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: https://run-mail.com/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": 1710003600,
        "type": "temp",
        "rotated": true
    }
}
GET /api/runmail/v1/mailboxes/{uuid} mailboxes:read

Fetch mailbox metadata and unread count.

Headers: X-Mailbox-Token

Response

JSON 
{
    "success": true,
    "data": {
        "uuid": "uuid",
        "email": "[email protected]",
        "expires_at": 1710000000,
        "type": "temp",
        "status": "active",
        "unread": 2
    }
}
DELETE /api/runmail/v1/mailboxes/{uuid} mailboxes:write

Delete a mailbox and its messages.

Headers: X-Mailbox-Token

Response

JSON 
{
    "success": true,
    "data": {
        "deleted": true
    }
}
POST /api/runmail/v1/mailboxes/{uuid}/refresh messages:read

Force a sync/refresh of the mailbox store.

Headers: X-Mailbox-Token

Response

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

Messages

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

List messages for a mailbox (paginated).

Headers: X-Mailbox-Token

Parameters: limit=1–100, cursor=optional

Response

JSON 
{
    "success": true,
    "data": {
        "messages": [
            {
                "uuid": "msg-uuid",
                "subject": "Verify your account",
                "from": "[email protected]",
                "date": "2026-03-20T12:00:00Z"
            }
        ],
        "next_cursor": null
    }
}
GET /api/runmail/v1/mailboxes/{uuid}/messages/{message_uuid} messages:read

Fetch a single message including body.

Headers: X-Mailbox-Token

Response

JSON 
{
    "success": true,
    "data": {
        "uuid": "msg-uuid",
        "subject": "Verify your account",
        "from": "[email protected]",
        "html": "<p>...</p>",
        "text": "..."
    }
}
DELETE /api/runmail/v1/mailboxes/{uuid}/messages/{message_uuid} messages:write

Delete a single message.

Headers: X-Mailbox-Token

Response

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

Domains

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

List active receiving domains.

Response

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

Usage & realtime

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

Usage summary for the authenticated key.

Response

JSON 
{
    "success": true,
    "data": {
        "requests": 120,
        "period": "24h"
    }
}
GET /api/runmail/v1/ws-config mailboxes:read

Realtime / WebSocket configuration hint.

Response

JSON 
{
    "success": true,
    "data": {
        "mode": "poll",
        "wsUrl": ""
    }
}

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