# MeowMail API

> Free REST API for temporary, disposable email. Create throwaway inboxes and read the mail they receive.

## Docs

- [Introduction](https://docs.meowmail.in/introduction.md): Free REST API for temporary email. Create disposable inboxes and read the mail they receive — from your test suite, your script, or your app.
- [Quickstart](https://docs.meowmail.in/quickstart.md): Get a key, generate an inbox, wait for mail, and read it — in four copy-paste steps.
- [Authentication](https://docs.meowmail.in/authentication.md): Read endpoints work with no credentials. A free API key raises your limits and unlocks long-polling.
- [Waiting for mail](https://docs.meowmail.in/waiting-for-mail.md): Long-polling and the cursor contract. Do not write a polling loop.
- [Response shapes](https://docs.meowmail.in/response-shapes.md): Envelopes, cursors, timestamps, and the two fields that need care.
- [Errors](https://docs.meowmail.in/errors.md): One envelope, eight machine-readable error types. Branch on type, never on message.
- [Rate limits](https://docs.meowmail.in/rate-limits.md): Two tiers, two windows, and the headers that let you self-throttle.
- [Versioning & stability](https://docs.meowmail.in/versioning.md): What we promise not to change, and how breaking changes will reach you.
- [Fair use](https://docs.meowmail.in/fair-use.md): No contract, no SLA — just a request to be reasonable so this can stay free.
- [Service discovery](https://docs.meowmail.in/api-reference/meta/service-discovery.md): Endpoint index, docs links, and the current email TTL.
- [This document](https://docs.meowmail.in/api-reference/meta/this-document.md): The OpenAPI 3.1 document for this API. Outside the developer quota. Import it into Postman or Insomnia, or generate a typed client from it.
- [Health check](https://docs.meowmail.in/api-reference/meta/health-check.md): Liveness and dependency check: a single `SELECT 1` against the database plus the SMTP listener state. Outside the developer quota, so a monitoring system can poll it without burning the fair-use budget of everyone sharing its egress IP.
- [Create a free API key](https://docs.meowmail.in/api-reference/keys/create-a-free-api-key.md): No signup, no password, no email verification. The raw key is returned exactly once and cannot be recovered.
- [Who am I, and what have I used](https://docs.meowmail.in/api-reference/keys/who-am-i-and-what-have-i-used.md): Reports your tier, limits, and current usage. Reading your quota does not consume it.
- [List domains that accept mail](https://docs.meowmail.in/api-reference/domains/list-domains-that-accept-mail.md): Call this rather than hardcoding a domain — the set changes.
- [Generate an inbox address](https://docs.meowmail.in/api-reference/inboxes/generate-an-inbox-address.md): Inboxes are implicit: nothing is stored until mail arrives, and any address at an active domain already works. This endpoint exists so you don't have to reimplement our address format, and so the address you get back is guaranteed to be empty right now.
- [List emails, optionally waiting for new mail](https://docs.meowmail.in/api-reference/inboxes/list-emails-optionally-waiting-for-new-mail.md): Newest first by default.
- [Delete every email in an inbox](https://docs.meowmail.in/api-reference/inboxes/delete-every-email-in-an-inbox.md): Irreversible. Useful between test cases.
- [Get one email with bodies and attachment metadata](https://docs.meowmail.in/api-reference/emails/get-one-email-with-bodies-and-attachment-metadata.md): Bodies, headers, and attachment metadata for one email.
- [Delete one email](https://docs.meowmail.in/api-reference/emails/delete-one-email.md): Permanently deletes one email, ahead of its TTL. Irreversible, and there are no backups. Returns 204 with no body.
- [List attachment metadata](https://docs.meowmail.in/api-reference/emails/list-attachment-metadata.md): `GET /api/v1/emails/{id}` already inlines this. Use this endpoint when you only need the list.
- [Download attachment bytes](https://docs.meowmail.in/api-reference/emails/download-attachment-bytes.md): Returns raw binary, not JSON. Attachments over 5 MB are never stored, so they will not appear here.

## OpenAPI Specs

- [openapi](https://api.meowmail.in/api/v1/openapi.json)