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

# Mails

> List, read, and delete emails in a temporary inbox.

## List emails

`GET /api/mails?limit=20&offset=0`

Returns emails for the authenticated address, newest first.

| Parameter | Type    | Required | Max | Description                |
| --------- | ------- | -------- | --- | -------------------------- |
| `limit`   | integer | Yes      | 100 | Number of emails to return |
| `offset`  | integer | Yes      | —   | Pagination offset          |

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://tempinbox.dev/api/mails?limit=20&offset=0" \
    -H "Authorization: Bearer <jwt>"
  ```

  ```javascript Node.js theme={null}
  const res = await fetch('/api/mails?limit=20&offset=0', {
    headers: { Authorization: `Bearer ${jwt}` },
  });
  const { results, count } = await res.json();
  ```

  ```python Python theme={null}
  r = requests.get(
    'https://tempinbox.dev/api/mails',
    params={'limit': 20, 'offset': 0},
    headers={'Authorization': f'Bearer {jwt}'}
  )
  emails = r.json()['results']
  ```
</CodeGroup>

**Response**

```json theme={null}
{
  "results": [
    {
      "id": 42,
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "source": "noreply@example.com",
      "address": "swift-cloud-7x4@tempinbox.dev",
      "metadata": "{\"subject\":\"Your verification code is 847291\"}",
      "created_at": "2026-05-28T10:00:00Z",
      "message_id": "<abc123@example.com>"
    }
  ],
  "count": 1
}
```

<Tip>
  For polling, call `GET /api/mails?limit=1&offset=0` repeatedly until `count > 0`. Add a delay of 2–5 seconds between polls to avoid rate limiting.
</Tip>

***

## Get a single email

`GET /api/mail/:uuid`

Returns the full email including the raw RFC 2822 body. Parse `raw` client-side to extract subject, body HTML, and attachments.

```bash theme={null}
curl "https://tempinbox.dev/api/mail/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <jwt>"
```

**Response**

```json theme={null}
{
  "id": 42,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "source": "noreply@example.com",
  "address": "swift-cloud-7x4@tempinbox.dev",
  "raw": "From: noreply@example.com\r\nTo: swift-cloud-7x4@tempinbox.dev\r\nSubject: Your code\r\n\r\n847291",
  "metadata": "{\"subject\":\"Your code\"}",
  "created_at": "2026-05-28T10:00:00Z",
  "message_id": "<abc123@example.com>"
}
```

### Extracting a verification code

```javascript theme={null}
const mail = await getMail(uuid);
const code = mail.raw.match(/\b\d{6}\b/)?.[0]; // extract 6-digit OTP
```

***

## Delete an email

`DELETE /api/mails/:uuid`

Soft-deletes a single email. Returns immediately.

```bash theme={null}
curl -X DELETE \
  "https://tempinbox.dev/api/mails/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <jwt>"
```

***

## Clear inbox

`DELETE /api/clear_inbox`

Deletes all emails in the inbox at once.

```bash theme={null}
curl -X DELETE https://tempinbox.dev/api/clear_inbox \
  -H "Authorization: Bearer <jwt>"
```

**Response**

```json theme={null}
{ "success": true }
```