Rate limits

Three things limit what an account can do, and the effective limit is always the lowest of them: the plan, the trust tier, and the per-minute rate limit.

Per plan

Receiving is free on every plan, because charging for the thing that makes an inbox valuable would be the wrong business.

Every number above is read, as this page renders, from the same module the API enforces them from — so this table cannot describe a limit the product does not apply. It used to claim that while being a hand-written table that did not.

Inboxes are unlimited on every plan. What an inbox costs is the mail in it and the mail it sends, and those are what the plan meters. Creating addresses is paced instead: a free account creates up to 20 a day, and every account at most what its trust tier allows in 24 hours, so a script making hundreds is refused while a team never notices.

Daily sends are a ceiling, not an allowance. A trust tier grants a share of the number above. A new account starts with the share in the start column, which is a fifteenth, until it confirms its email address; then it gets all of it. A penalised account loses part of it, in proportion to the penalty, and drops back to the start only when the penalties are heavy.

A Free account's first three days have their own limits. It sends up to 20 messages a day, the same message to at most 5 people, and a company address on pidgeon.email receives mail at once but sends only after the three days. A few bounces or one spam complaint pause its sending for the rest of them. Some new accounts get a week at 5 a day instead. A paid plan lifts all of it.

Trust, which is not the plan

A brand-new domain cannot be made trustworthy overnight. An account that has not confirmed its email starts well below its plan's daily allowance, and one whose mail bounces or draws complaints falls back there, rather than keeping a large limit it could burn its reputation with.

Confirming your email is the step that matters. Verifying a domain, time, and mail that arrives without being reported all raise the score further, which is what keeps an account at its full plan when something does go wrong.

Rate limits

Per minute, per account, across every key.

A refusal tells you when to come back. Being refused carries Retry-After in seconds and the daily allowance alongside it, so a client that has hit a limit never has to guess how long to wait:

Retry-After: 85783
X-RateLimit-Limit-Day: 6
X-RateLimit-Remaining-Day: 0
X-RateLimit-Reset-Day: 1792170122

The send allowance is a rolling twenty-four hours, not a calendar day, so X-RateLimit-Reset-Day is when your oldest send ages out of the window — which is the only honest answer and is why it is a header rather than a rule you could work out yourself.

Every authenticated success also carries X-RateLimit-Limit, -Remaining and -Reset for the per-minute ceiling, so a client can pace itself rather than find the limit by hitting it (the headers).

Minting and rotating keys

Each of these issues a new secret, so they share an hourly budget per account, separate from the per-minute one:

Test traffic is any call made with a test key, and any key minting or rotating a test key. It has a bucket of its own, so CI can never use up what a live admin key needs to connect or replace a key. Creating a pod with a key spends from the same budget.

The 429 says when the hour's window ends, in Retry-After, and carries that budget's X-RateLimit-Limit, -Remaining and -Reset. The window is fixed, not rolling: it resets on the hour boundary it names.

Adding domains, and on Enterprise

Adding domains has an hourly budget of its own: 10 an hour per account, and 20 checks in ten minutes for verifying them. On Enterprise, for a platform onboarding its own users in bursts, these, writes, uploads and rules are twenty times higher, and an account in good standing may make 5,000 addresses a day. The limits that protect people (sign-in, sign-up) and an account's trust tier are the same on every plan.

When you hit one

An entitlement refusal is a 402 with a sentence naming the limit and the alternative, and saying when it lifts if it lifts by itself.