<!-- Canonical: https://startupmail.dev/docs/api-reference -->
<!-- Documentation index: https://startupmail.dev/llms.txt -->

# API reference

> The complete public endpoint surface for mailboxes, threads, messages, attachments, and webhooks.

## Mailboxes

**GET `/v1/mailboxes`** — Scope: `mailboxes:read`

Lists mailboxes accessible to the key. Each item includes `id`, `address`, `displayName`, `visibility`, capability flags, and `unreadCount`.

## Threads

**GET `/v1/threads`** — Scope: `mail:read`

Lists thread summaries. Optional query parameters are `mailbox=<mailbox_id>` and `label=inbox|starred|sent|drafts|important|spam`.

**GET `/v1/threads/:id`** — Scope: `mail:read`

Returns a thread and its messages. A missing or inaccessible thread returns `404`.

## Messages

**POST `/v1/messages`** — Scope: `mail:send`

Queues a new message or reply.

```json
{
  "mailboxId": "mbx_123",
  "to": ["customer@example.com"],
  "cc": [],
  "bcc": [],
  "subject": "Re: Account access",
  "text": "I reset the link for you.",
  "html": "<p>I reset the link for you.</p>",
  "replyToMessageId": "msg_456",
  "attachmentIds": []
}
```

`to` requires 1–10 addresses. `cc` and `bcc` each accept up to 10. Subject is limited to 240 characters; text and HTML bodies are limited to 250,000 characters each. `replyToMessageId`, `html`, `cc`, and `bcc` are optional.

## Attachments

**POST `/v1/attachments`** — Scope: `mail:send`

Accepts `multipart/form-data` with one file in the `file` field. Returns attachment metadata and an expiry time.

**GET `/v1/attachments/:id`** — Scope: `mail:read`

Downloads an authorized attachment as bytes with its content type and safe filename.

## Webhooks

**GET `/v1/webhooks`** — Scope: `webhooks:write`

Lists configured endpoints without exposing their signing secrets.

**POST `/v1/webhooks`** — Scope: `webhooks:write`

Creates an HTTPS endpoint. `eventTypes` must include at least one supported event. The signing secret is returned once.

```json
{
  "url": "https://example.com/startupmail/events",
  "description": "Production mail worker",
  "eventTypes": ["message.received", "message.failed"]
}
```

**DELETE `/v1/webhooks/:id`** — Scope: `webhooks:write`

Deletes an endpoint and returns `204`.

## Supported webhook events

`message.received`, `message.sent`, `message.delivered`, `message.failed`, and `domain.verified`.