Rate limits

Requests are limited per second and per month. When you exceed the monthly limit, credits (if any) are consumed automatically. Response headers expose current limits and remaining usage.

Response headers

X-RateLimit-Limit-Second — per-second cap
X-RateLimit-Remaining-Second — remaining this second
X-RateLimit-Limit-Month — monthly quota
X-RateLimit-Remaining-Month — remaining this month
X-API-Plan — your plan name

HTTP 429

Per-second limit:

json

{
  "success": false,
  "error": "rate_limit_exceeded",
  "message": "Per-second limit of 25 req/s exceeded (startup plan).",
  "upgrade_url": "https://freecustom.email/api/pricing"
}

Monthly quota exhausted (no credits):

json

{
  "success": false,
  "error": "monthly_quota_exceeded",
  "message": "Monthly quota of 250,000 requests exhausted.",
  "hint": "Purchase request credits (never expire) or upgrade your plan.",
  "credits_url": "https://freecustom.email/api/credits",
  "upgrade_url": "https://freecustom.email/api/pricing"
}

Use the Retry-After header (seconds) when present to back off.

Endpoint Costs

Most API endpoints cost 1 request. However, some advanced endpoints and features consume more requests due to heavier processing:

GET /v1/inboxes/{inbox}/otp: 3 requests
GET /v1/inboxes/{inbox}/timeline: 2 requests
GET /v1/inboxes/{inbox}/insights: 3 requests
GET /v1/inboxes/{inbox}/wait: 10 requests
WebSocket Push (Basic): 1 request
WebSocket Push (OTP Present & Parsed): 2 requests
Webhook Delivery (Basic): 2 requests
Webhook Delivery (OTP Present & Parsed): 4 requests