Every mail-sending feature ships with limits: per-user caps to stop spam, per-mailbox caps to protect inboxes, provider quotas to protect reputation. The engineering question is never whether limits exist — it is whether they behave correctly when hit: clean errors, honest Retry-After headers, and a user-facing notification that says what happened and when it resets. Testing this against real users is a good way to lose real users. Fresh disposable inboxes make the whole surface testable without inconveniencing anyone.
Map the limits before you test them
You cannot assert against limits nobody wrote down. Inventory first:
- Per-mailbox caps: maximum messages per mailbox per window.
- Per-account caps: verification or reset mail per hour per user — the password-reset flow is where this shows up most, covered in how to test password reset emails.
- Per-IP and per-tenant caps: org-wide or infrastructure-level limits.
- Provider quotas: your sending provider's own throttles, whose errors your application must translate, never leak.
For each, record from config or code: the window, the cap, the action on breach — queue, reject with a 429, or the unforgivable silent drop — and whether a notification email should fire. That table becomes your assertion checklist.
The rate limit test workflow
1. Provision a fresh inbox per run. [Create a temporary inbox](/), or provision via API as described in temporary email for QA test accounts. Fresh state matters: leftover counters are the top source of confusing results. 2. Find the real cap. Read it from config. If it is not configurable, probe until behavior changes, then confirm the boundary with exactly-at-cap and cap-plus-one sends. 3. Fire a controlled burst. Hit the endpoint in a tight loop, recording every response: status, headers, body. You want the first throttled response and proof the ones before it were clean. 4. Verify the 429 semantics. Correct status code — not a 500, not a 200 followed by nothing — a machine-readable Retry-After that matches the actual window, a stable error payload clients can parse, and no partial sends: queued or rejected, never both. 5. Check the notification email. Where the design says users get told — quota approached, quota exceeded — assert the email arrives in the temp inbox, states the limit and reset time, and matches reality. 6. Verify recovery. After the window expires, sending must work again with no manual unstick, and a limits-lifted notification, if you send one, must fire exactly once. 7. Repeat with steady traffic just under the cap for several windows; the next section explains why.
Prototyping the loop is quicker in the API playground, and a receiver like the webhook tester captures notification arrivals without polling lag.
Burst versus steady: why you must test both
Rate limiters are algorithms, and algorithms have shapes. A fixed-window limiter behaves politely under a steady stream but resets its entire budget at the window edge — two bursts straddling a boundary can effectively double the cap. A token bucket absorbs bursts up to the bucket size, then throttles smoothly. A sliding window is fairer but costlier to verify. Test only one traffic shape and you have tested one mode and shipped the others unverified. The same applies to notifications: a burst test shows whether the exceeded email fires once, while a steady test reveals whether you warn on every rejected send or once per window.
What to assert
- Status and headers: 429 where documented, Retry-After consistent with the configured window, rate limit headers present if you promise them.
- Error payload stability: the error code clients branch on must not drift between releases; pin it with a test.
- Notification content: the limit value, the reset time, and a way forward are present, and the reset time matches observed behavior.
- Deduplication: exactly one exceeded email per window — not one per rejected request.
- State hygiene: after recovery a normal send works, and counters do not leak across users or mailboxes.
- No silent drops: every send is delivered, queued, or explicitly rejected, and rejections are visible in logs.
Common false positives
- Dirty counters: yesterday's test consumed today's budget, the limiter fires early, and the bug you file is against yourself. Fresh inbox and fresh account per run.
- Provider throttling misread as application throttling: the provider's quota error surfaces as your 429. Check which layer rejected the send before filing; the send logs usually settle it in one look.
- Clock skew at boundaries: if the test machine and the limiter disagree on time, boundary tests flap. Drive assertions from server timestamps in responses where possible.
- Parallel suites sharing a tenant cap: two pipelines running at once split one budget and both observe throttling earlier than expected.
FAQ
How do I test rate limits without a real provider in the loop? Point staging at a sink or mock provider for pure limiter logic, but keep at least one path through the real pipeline — the notification emails themselves need genuine delivery to verify, which is where disposable inboxes earn their keep.
Should the quota-exceeded email go to the inbox that is over quota? Usually, if that inbox can still receive. If the cap is upstream, send to the account's primary address instead. What must never happen is the notification being silently blocked by the very limiter it reports on — exempt system notifications from user-level caps and test that exemption explicitly.
What is the most commonly missed assertion? Recovery. Teams hammer the throttle and never verify that sending works again after the window, or that counters reset per mailbox rather than globally.
How many sends does each test need? Enough to cross the boundary from both sides: exactly at the cap, cap plus one, and one burst well past it. If the cap is large, make it configurable in test environments instead of sending thousands of real messages.
Bottom line
Rate limiting is a feature with a user interface, and much of that interface is email: quota warnings, exceeded notices, reset confirmations. Test limits like any other contract — burst and steady, boundary-exact, asserting status codes, headers, payload stability, and the content and timing of notification emails. Fresh disposable inboxes per run keep counter state clean, so what you measure is the limiter, not leftovers.