MAIL / INBOUND

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.

EXAMPLE

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.