Appearance

Authentication ​

Mail.cx uses bearer token authentication. No API key registration is needed.

How It Works ​

┌─────────────┐     POST /api/accounts      ┌──────────┐
│   Client     │ ──────────────────────────→  │  Server  │
│              │ ←──────────────────────────  │          │
│              │     { token: "eyJ..." }      │          │
│              │                               │          │
│              │     GET /api/messages         │          │
│              │     Authorization: Bearer ... │          │
│              │ ──────────────────────────→  │          │
└─────────────┘                               └──────────┘

Getting a Token ​

There are two ways to get a token:

1. Create a new mailbox ​

bash
curl -X POST https://api.mail.cx/api/accounts \
  -H "Content-Type: application/json" \
  -d '{"address":"user@mail.cx","password":"mypassword"}'

The response includes a token field — use it immediately.

2. Sign in to an existing mailbox ​

bash
curl -X POST https://api.mail.cx/api/token \
  -H "Content-Type: application/json" \
  -d '{"address":"user@mail.cx","password":"mypassword"}'

Using the Token ​

Include the token in the Authorization header for all authenticated requests:

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

Token Lifetime ​

  • Tokens are JWT (JSON Web Token) format
  • Tokens are valid for 7 days
  • After expiry, sign in again via POST /api/token to get a new one

Expired Token Response ​

When a token expires, any authenticated request returns 401:

json
{
  "error": "invalid_token"
}

Re-authenticate by calling POST /api/token with your email and password to get a fresh token.

Pro Authentication ​

Pro users authenticate with an API token (long-lived, prefixed with tm_pro_). Create one in the Pro dashboard under Tokens.

bash
curl https://api.mail.cx/pro/api/accounts \
  -H "Authorization: Bearer tm_pro_xxxxxxxxxxxx"

API tokens:

  • Start with tm_pro_ prefix
  • Do not expire (until manually revoked)
  • Can be used for server-to-server integrations
  • Are managed via the Tokens API

Security Notes ​

  • Always use HTTPS — tokens are sent in plain text in headers
  • Do not share tokens or embed them in client-side code
  • Rotate Pro API tokens periodically
  • Delete mailboxes when no longer needed

Mail.cx API Documentation