API Reference

Base URL

https://api.mail.cx/api

All API requests should be made to this base URL. HTTPS is required.

Authentication

All API requests require an API token sent via the x-api-token header. You can create tokens in your Dashboard under the Tokens page.

curl https://api.mail.cx/api/mailboxes \
  -H "x-api-token: tm_live_your_token_here"

Quick start

1. Create a mailbox:

curl -X POST https://api.mail.cx/api/mailboxes \
  -H "x-api-token: tm_live_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"local_part":"myinbox","domain":"qabq.com"}'

2. List emails in the mailbox:

curl https://api.mail.cx/api/mailboxes/{mailbox_id}/emails \
  -H "x-api-token: tm_live_your_token_here"

3. Read a specific email (full content with body and attachments):

curl https://api.mail.cx/api/emails/{email_id} \
  -H "x-api-token: tm_live_your_token_here"

Rate limits

Rate limits are applied in two layers: per-IP globally (100 requests/second for all users), and per-user (across all tokens). Free and Pro users also have monthly Ops quotas based on received emails.

Authenticated requests include X-Ops-Limit and X-Ops-Remaining headers showing your monthly Ops usage. Rate limit 429 responses include a Retry-After header; Ops quota 429 responses do not (resets monthly).

What counts as an Op?

Ops is a monthly quota based on received emails:

• Every email received by a registered user consumes 1 Op
• API calls do not consume Ops
• Webhook deliveries do not consume Ops
• Anonymous users are not subject to Ops limits (IP-based rate limits apply instead)

Endpoints

Mailboxes

Both fields are optional. If omitted, a random 6-character address on the default domain is generated.

Emails

Tokens

Domains (Pro)

Domain Emails (Pro)

Both endpoints support pagination via offset and limit query parameters. Default: 20 items per page, max 50. Response includes total count for building pagination.

GET /api/domain-emails?domain=yourdomain.com&offset=0&limit=20

// Response
{
  "emails": [...],
  "total": 142,
  "offset": 0,
  "limit": 20
}

Webhooks (Pro)

Webhook guide

Webhooks send an HTTP POST to your URL whenever an email arrives. Use them to integrate mail.cx with your application in real time.

Payload format

Each delivery sends a JSON payload with signature headers. The payload includes email metadata — not the full email body. Use the email_id to fetch the complete email via GET /api/emails/:id.

POST https://your-server.com/webhook
Content-Type: application/json
X-Webhook-ID: evt_abc123
X-Webhook-Timestamp: 1709721600
X-Webhook-Signature: sha256=a1b2c3...

{
  "id": "evt_abc123",
  "type": "email.received",
  "created_at": "2024-03-06T12:00:00Z",
  "data": {
    "email_id": "uuid",
    "mailbox_id": "uuid",
    "address": "inbox@qabq.com",
    "from": "sender@example.com",
    "sender": "sender@example.com",
    "subject": "Your verification code",
    "preview_text": "Your code is 123456...",
    "size": 2048,
    "created_at": "2024-03-06T12:00:00Z"
  }
}

Verifying signatures

Every webhook request includes HMAC-SHA256 signature headers. Always verify the signature before processing the payload to ensure it came from mail.cx.

import hmac, hashlib

def verify_webhook(payload: bytes, timestamp: str, signature: str, secret: str) -> bool:
    message = f"{timestamp}.{payload.decode()}"
    expected = hmac.new(secret.encode(), message.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Expected responses

Your endpoint should respond quickly. The system interprets your HTTP status code as follows:

Retry schedule

Failed deliveries are retried up to 5 times with exponential backoff: 15s, 1min, 5min, 10min, 20min. After 5 consecutive failures, the webhook status changes to "failing". Rotating the secret resets the failure count and restores the webhook to active.

Limits & requirements

Use GET /api/webhooks/:id/deliveries to view the last 20 delivery attempts, including HTTP status codes, errors, and response times — useful for debugging integration issues.

WebSocket

Connect to the WebSocket endpoint for real-time email notifications. Authenticate by sending an auth message as the first frame. The server sends ping frames every 30 seconds.

// Connect
const ws = new WebSocket("wss://api.mail.cx/api/ws");

// Authenticate (send as first message)
ws.send(JSON.stringify({
  type: "auth",
  token: "tm_live_your_token_here"
}));

// Receive new emails
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // { type: "new_email", data: { id, from, subject, mailbox_id } }
};

Errors

All errors return a JSON object with an error field:

{
  "error": "rate_limit_exceeded"
}