Startup gets 300 requests per minute and Enterprise gets 500. Limits are per account, shared across all your API tokens and any connected AI assistants. Each one-minute window absorbs a burst of up to 500 requests on Startup and 800 on Enterprise before the API returns HTTP 429 Too Many Requests with a Retry-After header. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Credential exports have their own limit of one every 5 seconds.
Limits by plan
| Plan | Steady rate | Burst cap per minute |
|---|---|---|
| Startup | 300 requests/minute | 500 |
| Enterprise | 500 requests/minute | 800 |
Limits apply per account across all tokens, so two scripts running at once share the same budget. The window resets at the start of each minute.
Response headers
Every authenticated API response includes:
X-RateLimit-Limit: your plan's steady rate per minute.X-RateLimit-Remaining: requests left in the current window at that rate.X-RateLimit-Reset: Unix timestamp when the window resets.
A 429 response also includes Retry-After, in seconds.
Handling 429 gracefully
if response.status_code == 429:
wait_seconds = int(response.headers.get("Retry-After", "60"))
time.sleep(wait_seconds)
# retry
Don't retry without waiting. Cap your retries (3 is plenty). Don't blindly retry POST, PATCH or DELETE calls: first check whether the original request went through, for example with GET /v1/jobs, so you don't buy or create something twice.
Best practices for bulk work
- Use bulk endpoints.
POST /v1/email-users/bulkcreates up to 100 mailboxes in one call.POST /v1/domains/search-bulkchecks many domains at once. - Page through lists. List endpoints return up to 100 items per page (
limit=100) with acursorfor the next page. - Cache slow-changing data. Account, plan and domain lists rarely change minute to minute.
- Use webhooks instead of polling. Events such as
domain.readyandemail_user.createdtell you when background jobs finish. See Webhooks.
Need more?
Enterprise has the higher limit. If you need more than that, contact support@winnr.app about your use case.
What's next
Frequently asked questions
What's the burst allowance?
Each one-minute window accepts up to 500 requests on Startup and 800 on Enterprise before requests are rejected. X-RateLimit-Remaining counts down against the steady rate (300 or 500), so it can reach 0 before you're actually blocked. Treat 0 as the signal to slow down.
Are exports rate-limited differently?
Yes. POST /v1/export is limited to one export every 5 seconds per account, and each export counts as one request no matter how many mailboxes it includes.
What happens when I hit 429?
The response includes a Retry-After header in seconds, which is the time until the current one-minute window resets. Wait that long, then retry.
Are jobs rate-limited?
Only the API call that starts a job counts. The background work doesn't. To create many mailboxes, use POST /v1/email-users/bulk (up to 100 per call on one domain) rather than one call per mailbox.
Do MCP tools count against the rate limit?
Yes. The MCP server calls the Winnr API, so each tool call is at least one API request. Assistants that call many tools quickly can hit the limit.
What limit applies if I only have pre-warmed mailboxes and no plan?
The Startup limit, 300 requests per minute.