API reference

Mailboxes

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

Threads

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

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

Messages

Queues a new message or reply.

{
  "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

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

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

Webhooks

Lists configured endpoints without exposing their signing secrets.

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

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

Deletes an endpoint and returns 204.

Supported webhook events

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