> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage & Rate Limits

> Rate limits and quotas applied to API requests.

To protect service availability and maintain optimal sending queues, Mailofly applies rate limits across API endpoints.

***

## Default Rate Limits

| Plan Tier | Sending Burst | Read / List Endpoints |
| :- | :- | :- |
| **Free** | 5 requests / sec | 20 requests / sec |
| **Basic** | 20 requests / sec | 50 requests / sec |
| **Pro** | 50 requests / sec | 100 requests / sec |
| **Enterprise** | Custom | Custom |

When a rate limit is exceeded, the API returns an HTTP `429 Too Many Requests` status code with a `Retry-After` header indicating seconds to wait.

***

## Rate Limit Categories

Rate limits are evaluated using a sliding window per API key (or client IP for unauthenticated calls):

* **Sending Burst**: Applies to high-frequency email dispatching endpoints including `POST /emails`, `POST /emails/batch`, and `POST /campaigns/:id/send`.
* **Read / List Endpoints**: Applies to all retrieval operations (`GET /*`).
* **Other Mutations**: Applies to resource creation, updates, and deletions (`POST`, `PATCH`, `DELETE`).

***

## Response Headers

Every response from the Mailofly API includes headers indicating your current rate limit status:

| Header | Description |
| :- | :- |
| `X-RateLimit-Limit` | The maximum request rate permitted per second for this category under your plan. |
| `X-RateLimit-Remaining` | The number of requests remaining in the current sliding window. |
| `X-RateLimit-Reset` | The Unix timestamp (in seconds) when the current window resets. |
| `Retry-After` | Included when an HTTP `429` is returned, specifying the number of seconds to wait before retrying. |

***

## Rate Limit Exceeded Response

When your request rate exceeds the tier allowance, Mailofly responds with HTTP `429 Too Many Requests`:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 1
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1726050001
```

```json theme={null}
{
  "statusCode": 429,
  "name": "too_many_requests",
  "message": "Rate limit exceeded. Please try again in 1 second.",
  "retryAfter": 1
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.