---
name: mailboxes
description: tinysend mailboxes — programmatic email addresses that receive inbound mail. create persistent or disposable (TTL) addresses, read parsed messages and attachments, send outbound from a mailbox. use when an agent needs its own email address to receive mail.
license: MIT
compatibility: requires network access to api.tinysend.com (see the platform skill for auth)
---

# mailboxes

addressable email endpoints in tinysend. receive inbound email, create disposable addresses, route messages to handlers.

## what mailboxes are

a mailbox is an email address that tinysend manages. inbound mail arrives, gets parsed, and flows through handlers. each list auto-creates a mailbox (listname@tinysend.com). you can also create standalone mailboxes.

## types

- persistent — long-lived address, tied to a list or standalone
- disposable — auto-generated readable address with a TTL, self-destructs after expiry

## endpoints

```
GET    /v1/mailboxes                      list all mailboxes
POST   /v1/mailboxes                      create a mailbox
GET    /v1/mailboxes/:id                  mailbox details + handlers
PATCH  /v1/mailboxes/:id                  update settings
DELETE /v1/mailboxes/:id                  deactivate
```

```
GET    /v1/mailboxes/:id/emails           list emails in a mailbox
POST   /v1/mailboxes/:id/emails           create outbound email
GET    /v1/mailboxes/:id/emails/:eid      email detail
PATCH  /v1/mailboxes/:id/emails/:eid      update email status
```

## creating a mailbox

persistent with explicit address:

```json
{
  "address": "support@tinysend.com",
  "name": "Support",
  "type": "persistent"
}
```

disposable with auto-generated address:

```json
{
  "type": "disposable",
  "name": "Temp inbox",
  "ttl": "24h"
}
```

ttl accepts: 1h, 6h, 12h, 24h, 48h, 7d, 30d. or pass `expires_at` as ISO 8601.

## inbound email flow

1. email arrives at mailbox address
2. tinysend parses headers, body, attachments
3. email stored with full metadata (from, to, subject, message-id, thread-id)
4. attachments stored in R2
5. handlers execute in priority order
6. `email.received` webhook fires

## statuses

mailbox statuses: active, disabled. emails: received, processing, processed, failed.