# Temp Mail API: Disposable Email API for Testing

> REST API for disposable inboxes. Create temp email addresses, stream new mail with Server-Sent Events and assert on verification codes in your tests.

Source: https://yelmail.com/developers

The YelMail Temp Mail API is a REST API for disposable inboxes. Create a temporary email address from your test suite, sign up like a real user, then read the verification code or magic link it receives.

Every response is JSON in the shape `{ data }` or `{ error: { code, message } }`. API keys come with [Premium](https://yelmail.com/pricing). Machine-readable spec: [OpenAPI](https://yelmail.com/api/v1/openapi.json). Walkthrough: [test sign-up emails with Playwright](https://yelmail.com/blog/test-signup-emails-with-api).

## Authentication

Send your Premium API key as a bearer token. Rate limits are returned in `X-RateLimit-Remaining`. Guest clients can instead pass the `token` returned by `POST /inboxes` in an `X-Inbox-Token` header.

```bash
# Create an inbox
curl -X POST https://yelmail.com/api/v1/inboxes \
  -H "Authorization: Bearer tm_your_key" \
  -H "Content-Type: application/json" -d '{}'

# Read its messages
curl https://yelmail.com/api/v1/inboxes/INBOX_ID/messages \
  -H "Authorization: Bearer tm_your_key"
```

## Endpoints

Base URL: `https://yelmail.com/api/v1`

| Method | Path | What it does | Auth |
| --- | --- | --- | --- |
| GET | `/domains` | List domains you can create addresses on | Optional |
| POST | `/inboxes` | Create an inbox (random, or custom with localPart + domainId) | Optional |
| GET | `/inboxes` | List your active inboxes | Required |
| GET | `/inboxes/{id}` | Get one inbox | Required |
| PATCH | `/inboxes/{id}` | Update label or forwarding target | Required |
| DELETE | `/inboxes/{id}` | Delete an inbox and its emails | Required |
| GET | `/inboxes/{id}/messages` | List messages (newest first, cursor pagination) | Required |
| GET | `/inboxes/{id}/stream` | Server-Sent Events stream of new messages | Required |
| GET | `/messages/{id}` | Get a message with text, sanitized HTML and attachments | Required |
| DELETE | `/messages/{id}` | Delete a message | Required |
| GET | `/messages/{id}/attachments/{attachmentId}` | Download an attachment | Required |
| GET | `/me` | Current user and plan entitlements | Optional |
| DELETE | `/me/session` | Sign out the bearer session token sent with the request (apps, extension) | Required |
| POST | `/extension/token` | Browser extension sign-in: trade a connect code and PKCE verifier for a session token | Optional |