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

# Receive mail and read threads

> Work with incoming messages, labels, complete threads, and real-time notifications.

## How receiving starts

Incoming mail reaches Startup Mail after the domain’s MX record is verified and a matching mailbox exists. Unknown recipients are not catch-all routed. Accepted messages appear in the web inbox and become available to API, SDK, webhook, and MCP integrations with the right access.

## List threads

Use `GET /v1/threads` or `mail.listThreads()`. Filter with a mailbox ID and one of these labels: `inbox`, `starred`, `sent`, `drafts`, `important`, or `spam`.

```ts
const threads = await mail.listThreads({
  mailboxId: "mbx_123",
  label: "inbox",
});
```

A thread summary includes subject, snippet, sender, last-message time, unread and message counts, starred and important state, and whether it has attachments.

## Read a complete thread

Use `GET /v1/threads/:id` or `mail.getThread(threadId)`. The response contains messages in the conversation, including direction, delivery status, addresses, plain and cleaned HTML bodies, timestamps, and attachment metadata.

Access is checked when the thread is requested. Knowing a thread ID does not bypass private mailbox permissions.

## React without polling

Subscribe to `message.received` with a signed webhook. Its payload identifies the mailbox, thread, and message so your worker can fetch the complete thread using `mail:read` scope.

> **Fetch after the event**
>
> Treat a webhook as a durable notification, not a replacement for the API response. Use its IDs to
> retrieve the current thread and make your processing idempotent.
