Rate Limiting

Mail.td applies rate limits to ensure fair usage and service stability.

Limits

Plan	Rate Limit	Keyed by
Free (authenticated)	4 req/s	User
Pro (authenticated)	10 req/s	User
Account creation (free)	1 per 8s	User
Account creation (Pro)	1 req/s	User

Pro users also have a monthly ops quota — each API operation counts toward this limit. You can check your current usage via GET /api/user/me (ops_used / ops_limit). When the quota is exceeded, the API returns 429 with ops_quota_exceeded.

Rate Limit Response

When you exceed the limit, the API returns 429 Too Many Requests:

{
  "error": "rate_limit_exceeded"
}

Best Practices

• Use webhooks for real-time updates instead of polling GET /api/accounts/{id}/messages repeatedly
• Cache domain lists — available domains rarely change
• Use exponential backoff when retrying after a 429
• Batch operations where possible — don't create/delete accounts in tight loops

Example: Retry with Backoff

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const res = await fetch(url, options);
    if (res.status !== 429) return res;

    const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
    await new Promise(r => setTimeout(r, delay));
  }
  throw new Error('Rate limit exceeded after retries');
}