Authentication

Mail.td uses bearer token authentication. No API key registration is needed to get started.

How It Works

POST /api/accounts → get token + account_id
                          ↓
GET /api/accounts/{account_id}/messages
    Authorization: Bearer <token>

All authenticated requests require the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Token Types

Mail.td supports three token types. All use the same Authorization: Bearer header.

Token type	Who uses it	Lifetime	How to get
Email JWT	All users	7 days	POST /api/accounts or POST /api/token
Pro JWT	Pro users	7 days	POST /api/user/login
Pro API Token	Pro users	Never expires	Created in Pro dashboard or POST /api/user/tokens

Email JWT

Issued when you create an account or sign in. Grants access to one specific account.

# 1. Get PoW challenge (free users only)
curl https://api.mail.td/api/challenge
# → {"id": "...", "salt": "...", "difficulty": 20, "expires_at": ...}

# 2. Create account with solved PoW → get token
curl -X POST https://api.mail.td/api/accounts \
  -H "Content-Type: application/json" \
  -d '{"address":"demo@mail.td","password":"supersecret","pow":{"id":"...","nonce":"..."}}'
# → {"id": "a1b2c3d4-...", "address": "demo@mail.td", "token": "eyJ..."}

# Sign in to existing account → get new token (no PoW needed)
curl -X POST https://api.mail.td/api/token \
  -H "Content-Type: application/json" \
  -d '{"address":"demo@mail.td","password":"supersecret"}'
# → {"id": "a1b2c3d4-...", "address": "demo@mail.td", "token": "eyJ..."}

Pro JWT

Issued when a Pro user logs in with email and password. Grants access to all accounts owned by the Pro user and Pro management features (domains, webhooks, tokens).

curl -X POST https://api.mail.td/api/user/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"propassword"}'
# → {"user_id": "...", "email": "...", "plan": "pro", "status": "active"}

OAuth Users

If you signed up with Google or GitHub, you don't have a password and cannot use POST /api/user/login. Instead, create a Pro API Token in the Pro dashboard to access the API.

Pro API Token

Long-lived token for server-to-server integrations. Prefixed with tm_pro_. Does not expire — revoke manually when no longer needed. This is the recommended way to authenticate for all API integrations.

curl https://api.mail.td/api/accounts/{account_id}/messages \
  -H "Authorization: Bearer tm_pro_xxxxxxxxxxxxxxxxxxxx"

Create tokens in the Pro dashboard or via POST /api/user/tokens.

Token Lifetime

Token	Expires	Refresh
Email JWT	7 days	Call POST /api/token
Pro JWT	7 days	Call POST /api/user/login
Pro API Token	Never	Revoke via DELETE /api/user/tokens/{id}

When a token expires, the API returns:

HTTP 401
{ "error": "invalid_or_expired_token" }

Rate Limits

Plan	Limit	Keyed by
Public endpoints	8 req/s	IP
Free (authenticated)	8 req/s	IP
Pro (authenticated)	20 req/s	IP
Account creation (free)	1 per 8s	IP
Account creation (Pro)	8 req/s	IP

Security Best Practices

• Always use HTTPS (https://api.mail.td)
• Don't share tokens or embed them in client-side code
• Rotate Pro API tokens periodically
• Delete accounts when no longer needed