Appearance

Quick Start ​

Get up and running with Mail.cx API in under a minute. No API key required.

Base URL ​

https://api.mail.cx

Two paths, one API ​

Free user — 3 steps to receive email ​

GET /api/domains          → pick a domain
POST /api/accounts        → create mailbox, get token
GET /api/messages          → read emails

Pro user — custom domains + management ​

POST /api/accounts         → create mailbox on custom domain (with Pro token)
GET /pro/api/accounts      → list / manage mailboxes
GET /pro/api/domains       → manage custom domains
POST /pro/api/webhooks     → get notified when email arrives

TIP

Both paths use the same REST API. Start with the Free flow below, then add Pro features when you need them.

Step 1: Get Available Domains ​

bash
curl https://api.mail.cx/api/domains
json
{
  "domains": [
    { "id": "...", "domain": "mail.cx", "default": true, "sort_order": 0 },
    { "id": "...", "domain": "fexbox.org", "default": false, "sort_order": 1 }
  ]
}

Step 2: Create a Mailbox ​

Pick a domain and create an email address. The response includes a token — use it immediately.

bash
curl -X POST https://api.mail.cx/api/accounts \
  -H "Content-Type: application/json" \
  -d '{"address":"demo@mail.cx","password":"supersecret"}'
json
{
  "id": "a1b2c3d4-...",
  "address": "demo@mail.cx",
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Step 3: Fetch Messages ​

Use the token to list and read emails:

bash
# List messages
curl https://api.mail.cx/api/messages \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Read a specific message
curl https://api.mail.cx/api/messages/f5e6d7c8-... \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
json
{
  "id": "f5e6d7c8-...",
  "sender": "noreply@example.com",
  "from": "Example <noreply@example.com>",
  "subject": "Verify your email",
  "address": "demo@mail.cx",
  "size": 4523,
  "created_at": "2025-01-15T10:30:00Z",
  "text_body": "Click the link below to verify your email...",
  "html_body": "<html>...</html>",
  "attachments": []
}

That's it — three steps, zero setup.

Code Examples ​

Python ​

python
import requests

API = "https://api.mail.cx/api"

# Create mailbox
r = requests.post(f"{API}/accounts", json={
    "address": "demo@mail.cx",
    "password": "supersecret"
})
token = r.json()["token"]

# Fetch messages
headers = {"Authorization": f"Bearer {token}"}
messages = requests.get(f"{API}/messages", headers=headers).json()

for msg in messages["messages"]:
    print(f"{msg['from']}: {msg['subject']}")

    # Read full message
    detail = requests.get(f"{API}/messages/{msg['id']}", headers=headers).json()
    print(detail["text_body"])

JavaScript (Node.js) ​

javascript
const API = "https://api.mail.cx/api";

// Create mailbox
const res = await fetch(`${API}/accounts`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ address: "demo@mail.cx", password: "supersecret" }),
});
const { token } = await res.json();

// Fetch messages
const headers = { Authorization: `Bearer ${token}` };
const { messages } = await (await fetch(`${API}/messages`, { headers })).json();

for (const msg of messages) {
  console.log(`${msg.from}: ${msg.subject}`);

  // Read full message
  const detail = await (await fetch(`${API}/messages/${msg.id}`, { headers })).json();
  console.log(detail.text_body);
}

What's Next? ​

Mail.cx API Documentation