Startup plan gets 300 requests per minute. Enterprise gets 500. Limits are per account, shared across all your API tokens. Exceeding returns HTTP 429 Too Many Requests with a Retry-After header. Every response includes X-RateLimit-Remaining and X-RateLimit-Reset so you can back off before hitting the limit.
Response headers
Every API response includes:
X-RateLimit-Limit— your plan's cap per minute.X-RateLimit-Remaining— how many requests are left in the current window.X-RateLimit-Reset— unix timestamp when the window resets.
Use these to back off preemptively. A well-behaved client keeps Remaining above 20 and slows down as it approaches zero.
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. Don't retry more than 3 times. Don't retry non-idempotent operations (POST/PATCH) without checking whether the first request actually succeeded.
Best practices for bulk work
- Provision domains sequentially or in small batches (5-10 at a time), with 100ms between requests.
- Batch reads — fetch lists rather than individual gets. GET /email-users returns hundreds in one call.
- Cache aggressively — account state, plan info, and other slow-changing data can be cached for 5+ minutes.
- Use webhooks — for status updates on long-running jobs, webhooks are cheaper than polling.
Upgrading for higher limits
The main reason to upgrade to Enterprise if you're already at ~200 mailboxes — the 500 req/min limit is enough for most AI SDR pipelines running full-tilt. Beyond that, contact support about custom rate limits.
What's next
Frequently asked questions
What's the burst allowance?
There's headroom above the steady per-minute rate. Startup absorbs up to 500 requests within a minute-window, Enterprise up to 800, before the limiter kicks in. Sustained sending above your plan's rate gets throttled.
Are heavy endpoints (export) rate-limited differently?
Export generates a downloadable file and is treated as one request regardless of how many mailboxes it includes.
What happens when I hit 429?
Server returns 429 with a Retry-After header (in seconds). Wait that long, then retry. Aggressive retry loops without respecting Retry-After will get you rate-limited longer.
Are jobs rate-limited?
The API call to create a job counts against your rate limit. The job itself running in the background doesn't. So provisioning 100 mailboxes = 100 POST calls (~20 seconds on Startup at 5/sec), plus background processing time (unaffected by rate limits).
Do MCP tools count against the rate limit?
Yes — MCP calls Winnr's API under the hood, so each MCP tool invocation is at least one API request. Agents that hammer many tools quickly can hit rate limits.