Limits
Four things cap you on this API – a monthly quota on how many mailboxes you may create, a per-minute limit on how fast you may call, a cap on waits held open at once, and the storage your account's messages take. All of them are counted per user, not per key or per IP: every key of yours draws on the same budget, so issuing more keys buys nothing.
Where the numbers are
The numbers depend on the plan and can change without a release, so they are not written on this page – read them live. Your own current numbers, with what you have spent, come from GET /v1/limits, which does not spend quota:
curl -s https://api.fake-email.pro/v1/limits \
-H "Authorization: Bearer $FEP_KEY" Every plan's numbers come from GET /v1/plans on the site – no key and no session needed – and the pricing page shows them side by side:
curl -s https://fake-email.pro/v1/plans| Limit | GET /v1/limits | GET /v1/plans (limits) |
|---|---|---|
| Mailboxes per month Creations only, per calendar month in UTC. | quota.limit, quota.used, quota.resetsAt | apiMailboxesPerMonth |
| Requests per minute Every call, reads included; also X-RateLimit-Limit. | requestsPerMinute | apiRequestsPerMinute |
| Waits open at once Long polls held open at the same time. | concurrentWaits | apiConcurrentWaits |
| Storage One budget for all your messages, site and API. | storage.usedBytes, storage.limitBytes | storageBytes |
| Mailbox lifetime The same on every plan. | mailboxTtlSeconds | – |
| API keys Expired keys count too. | – | apiKeysMaxCount |
A guest session cannot hold an API key: keys are issued only on a plan with allowApiAccess. If your plan loses it, every call answers 403 plan_forbidden.
Monthly quota
Counted per calendar month in UTC: quota.used is the mailboxes you created through the API since the first of the month – deleted and expired ones included, since deleting does not give quota back – and quota.resetsAt is the first of the next month, 00:00 UTC. Only a successful POST /v1/mailboxes spends it; reads never do, and a create that fails for any reason does not either.
Running it out is a 402 quota_exhausted on mailbox creation, with limit, used, resetsAt and upgradeUrl in the body – reading keeps working. upgradeUrl leads to the pricing page, where the plans and their quotas are compared.
Requests per minute
One fixed one-minute window per user. Every call counts – reads, a call refused with a 400 or 404, and a 429 itself. Past requestsPerMinute the answer is 429 rate_limit_exceeded with Retry-After, the seconds left in the window. Every response the limiter saw carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Getting Started has the details). The monthly quota is never in a header: read it from GET /v1/limits.
Waits open at once
GET /v1/mailboxes/{address}/messages/wait is one request, however long it waits – up to 60 seconds for a single request, where a loop over the list of messages spends one every few seconds. What it holds while open is a slot: past concurrentWaits, the next one is 429 too_many_waits with Retry-After: 1 rather than rate_limit_exceeded. A wait that answers at once holds no slot, and any wait that ends – with an email, a 204, an error or a dropped connection – frees its slot.
Storage
storage.limitBytes is one budget for every message of your account, the website's and the API's alike. When a new email does not fit, the oldest messages of your account make room for it, from any mailbox; an email larger than the whole budget is kept without its body, with bodyState: "OVERFLOW".
Mailbox lifetime
Every mailbox this API mints accepts mail for 24 hours (mailboxTtlSeconds), the same on every plan, and cannot be renewed. From expiresAt on, the mailbox and its messages answer 404, and they are deleted soon after: a message never outlives the mailbox holding it. Need it for longer, create a new one; the address of the old one is never handed out again.