# Rate limits

> Mailmanny API request limits, rate-limit headers, and how sending caps work.

Source: https://www.mailmanny.com/docs/rate-limits
All docs for AI agents: https://www.mailmanny.com/llms.txt

Two separate things limit how fast you can go: request rate limits on the API, and sending caps on email. The first protects the API; the second protects your deliverability.

## Request limits

- `Per second` (10 requests): Short bursts, per API key.
- `Per minute` (600 requests): Sustained traffic, per API key, on Essentials, Standard and Pro.
- `Per minute (Free)` (10 requests): For the whole workspace on the Free plan.

On paid plans limits count per key, so separate integrations with separate keys don't slow each other down. For bulk work, use the endpoints built for it: [batch sending](https://www.mailmanny.com/docs/sending.md#batch) sends 100 emails in one request.

## Headers

Every authenticated response tells you where you stand, for whichever window is closer to running out:

```http
HTTP/1.1 200 OK
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1
X-Request-Id: req_4f1c9a0e2b7d4c8e9a6b3d2f1e0c5a7b
```

- `X-RateLimit-Limit` (number): Requests allowed in the current window.
- `X-RateLimit-Remaining` (number): Requests left in it.
- `X-RateLimit-Reset` (seconds): Seconds until the window resets.
- `Retry-After` (seconds): On 429 responses only: how long to wait.

**429 Too Many Requests**

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 1

{
  "statusCode": 429,
  "name": "rate_limit_exceeded",
  "message": "Too many requests. Retry in 1s.",
  "details": { "retry_after": 1 }
}
```

> **Note:** The SDK backs off for you
> It retries 429s after `Retry-After` on safe requests. If you call the HTTP API directly, wait at least `Retry-After` seconds, and add jitter if many workers share a key.

## Plan limits

Every plan includes the API and the SDK. Free is for trying it out and small projects; paid plans have a monthly API allowance of their own, starting with 10,000 emails a month on Essentials (from $9 a month).

- `API emails a day` (100): One per recipient in to. Resets at 00:00 UTC.
- `Emails a month` (1,000): Shared by campaigns and the API. Resets on the 1st (UTC).
- `API keys` (1): Audience-restricted keys need a paid plan. Keys you made on a paid plan keep working.
- `Templates push and events` (Paid): PUT /templates (mailmanny templates push) needs Essentials, POST /events needs Standard: both answer 402 plan_required on Free.

Over a limit, the API answers `429 quota_exceeded` with `Retry-After` set to when it resets. Nothing is dropped silently: the email in that request isn't accepted, so you know to send it later. The SDK returns these errors to you instead of waiting hours to retry.

**429 quota_exceeded**

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 18720

{
  "statusCode": 429,
  "name": "quota_exceeded",
  "message": "Free includes 100 API emails a day, and today's are used up (100 of 100). They reset at 00:00 UTC, in 5h 12m. Essentials ($9 a month) includes 10,000 API emails a month with no daily cap.",
  "details": { "period": "day", "limit": 100, "used": 100, "requested": 1, "plan": "free", "required_plan": "essentials", "retry_after": 18720 }
}
```

## Sending caps

Separately, every workspace has a daily and an hourly sending cap. New workspaces start small and the caps grow as your bounce and complaint rates stay healthy. This is how Mailmanny keeps one sender's bad list from hurting everyone's delivery.

- When a cap is reached, API emails aren't rejected. They wait (`last_event: "delivery_delayed"`) and go out automatically when capacity frees up.
- Transactional email gets a reserved share of capacity, so a big campaign can't hold up your password resets.
- You can see today's usage in [Settings → Sending](https://www.mailmanny.com/settings/sending). Need more? Contact support with your expected volume.