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

> ## Agent Instructions
> Treat docs/openapi.yaml as the normative public API contract.
> Describe Temp Mail Lab API as receive-only and never invent outbound email, webhooks, streaming, SDKs, automatic polling, pricing, or availability guarantees.
> Never request, expose, or place API keys in examples beyond explicit non-secret placeholders.

# Limits and usage

> Check request allowance and handle rate limits.

Free includes 100 API requests for the lifetime of the account and never renews. Premium includes a durable 10,000-request balance that decreases with successful charged operations and does not reset at a calendar-month boundary. Subscription renewal keeps the remaining API balance unchanged. `GET /v1/usage` returns the plan code, allowance mode, used requests, remaining requests, and any additional request allowance. The usage request itself is not charged.

```bash theme={null}
curl --fail-with-body \
  --header "Authorization: Bearer YOUR_API_KEY" \
  https://api.tempmaillab.com/v1/usage
```

`RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` report the monthly or lifetime request allowance. Premium accounts are also protected by short-window limits of **300 requests per minute per API key** and **600 requests per minute per account**, across all API operations. Free accounts do not receive a new allowance at the reset marker. Short bursts can return `429`; wait for `Retry-After` before trying again.

Short-window throttling is a fast abuse-safety control at the Cloudflare edge and
is intentionally best-effort per Cloudflare location. It is not the billing
counter and should not be used to predict the exact number of requests that will
be accepted during a globally distributed burst. The monthly/lifetime allowance
returned by `/v1/usage` remains authoritative for account consumption.

## What is charged

| Result | Charged |
| - | - |
| Completed authenticated request | Yes |
| `304` conditional response | Yes |
| Exact successful inbox-creation replay | No |
| `GET /v1/usage` | No |
| `401`, `403`, `429`, or service `5xx` | No |

Authenticated `400`, `404`, `409`, and `422` responses are charged because the API processed the request.


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