# Mailroom > Self-hosted mail on Amazon SES and Cloudflare. One company runs one instance, against its own Postgres and its own R2 bucket, with as many people in it as they invite. Mailroom exposes a REST API at `/api/v1` on your own instance, authenticated with a bearer key (`mk_live_…`). Keys carry scopes, which say what kind of call is allowed, and reach, which says which mailboxes those calls may touch. Lists are cursor-paginated; sends accept an `Idempotency-Key`. There is a typed Node SDK, `@shahriyardx/mailroom`, with no dependencies. ## Guide - [What it is](https://mailroom-docs.shahriyar.dev/guide/): Mailroom is a self-hosted email platform. You run one instance, on your own server, against your own database, for your own domains. - [How it fits together](https://mailroom-docs.shahriyar.dev/guide/architecture): Four moving parts. Knowing which one is at fault is most of debugging a mail problem, so it is worth five minutes. - [Self-hosting it](https://mailroom-docs.shahriyar.dev/guide/self-hosting): Start to finish. Deploy **before** the SES and Cloudflare steps: both have to reach a real URL, so nothing past step 3 works against `localhost`. - [Sending domains](https://mailroom-docs.shahriyar.dev/guide/domains): A domain has to be verified in SES before anything can be sent from it. Mailroom creates the SES identity for you and shows the DNS to publish. - [Receiving mail](https://mailroom-docs.shahriyar.dev/guide/receiving): Inbound mail arrives through Cloudflare Email Routing, which hands each message to a Worker, which posts it to your instance. The Worker is deployed **from the app** — there is no `wrangler` step o… - [Forwarding](https://mailroom-docs.shahriyar.dev/guide/forwarding): A copy of inbound mail, sent on to an address outside Mailroom. Useful for keeping an old inbox fed while you move over, for an archive copy, or for getting one mailbox onto a phone that is already… - [Campaigns](https://mailroom-docs.shahriyar.dev/guide/campaigns): One message, written once, sent to everybody on a list. Switched off by default — turn **Campaigns** on in [Settings → Features](/guide/features), and a switcher appears at the top of the sidebar t… - [Automations](https://mailroom-docs.shahriyar.dev/guide/automations): A campaign goes to everybody at once. An **automation** starts when one person does something, so its third email lands three days after *their* signup — whenever that was. - [Metrics](https://mailroom-docs.shahriyar.dev/guide/metrics): **Settings → Metrics**, or **Metrics** in the campaigns view. The same screen either way. - [Templates and media](https://mailroom-docs.shahriyar.dev/guide/templates): **Settings → Templates**, or **Templates** in the campaigns view. The same screen either way. - [Features](https://mailroom-docs.shahriyar.dev/guide/features): Two products share this app, and an instance says which of them it is: - [Mailboxes and people](https://mailroom-docs.shahriyar.dev/guide/mailboxes): **Settings → Mailboxes.** A mailbox is one address on one of your domains. There is no limit on how many you have. - [API keys](https://mailroom-docs.shahriyar.dev/guide/api-keys): A key is how your own code talks to your instance. It is shown once, when it is made, and stored only as a hash — there is no way to read it back. - [Test keys](https://mailroom-docs.shahriyar.dev/guide/test-mode): A key made in test mode runs everything a live one runs and stops one step short of handing the message to SES. - [The send queue](https://mailroom-docs.shahriyar.dev/guide/queue): A message that has not gone out yet lives in a queue: one SES could not take right now, and one that was scheduled for later. Both are the same problem — a message that exists and has not been sent… - [Desktop notifications](https://mailroom-docs.shahriyar.dev/guide/notifications): A notice on the desktop when mail arrives, whether or not Mailroom is open in a tab. It uses Web Push, so the browser itself is woken by the push service — there is no tab polling in the background… - [Browser extension](https://mailroom-docs.shahriyar.dev/guide/extension): Your inbox in the toolbar, for Chrome, Firefox and Edge. It tells you when mail arrives, shows the conversation, and hands you back to the dashboard the moment you want to write something. ## API - [Overview](https://mailroom-docs.shahriyar.dev/api/): Make a key under **Settings → API keys**. See [API keys](/guide/api-keys) for what the options mean. - [Scopes and reach](https://mailroom-docs.shahriyar.dev/api/scopes): A key carries two limits. Both are checked on every call, and neither substitutes for the other. - [Pagination](https://mailroom-docs.shahriyar.dev/api/pagination): Every list returns one page and, when there is more, an opaque cursor. - [Errors](https://mailroom-docs.shahriyar.dev/api/errors): `error` is for a human reading a log. `code` is for a program deciding what to do. - [Idempotency and limits](https://mailroom-docs.shahriyar.dev/api/idempotency): A send that times out leaves you with a hard question: did it go? - [Emails](https://mailroom-docs.shahriyar.dev/api/emails): `202`, not `200`: SES has accepted it, and whether it was *delivered* comes later — as a `status` on the message, and as an [`email.delivered` webhook](/webhooks/events). - [Templates](https://mailroom-docs.shahriyar.dev/api/templates): The point is that the wording stops living inside whatever service does the sending. Changing a receipt should not need a deploy, and the same receipt should read the same whichever service sent it. - [Threads](https://mailroom-docs.shahriyar.dev/api/threads): A thread is a conversation. Inbound mail lives in threads, and this is the endpoint that makes an inbox readable from outside the app. - [Messages and files](https://mailroom-docs.shahriyar.dev/api/messages): Threads are the better way to read a conversation. These endpoints are for when a program wants **messages themselves** — everything that arrived since a stamp, everything from one sender, everythi… - [Mailboxes](https://mailroom-docs.shahriyar.dev/api/mailboxes): Returns every address **this key can reach**, which is the quickest way for a client to discover what it is allowed to do. `?domain=example.com` narrows it. - [Domains](https://mailroom-docs.shahriyar.dev/api/domains): What this account can send from, and the DNS each one needs. - [Labels and contacts](https://mailroom-docs.shahriyar.dev/api/labels): The labels threads are filed under. Scoped to the account, not to a mailbox. - [Blocked addresses](https://mailroom-docs.shahriyar.dev/api/suppressions): Addresses this account will not send to again. Bounces and complaints fill this in automatically. - [Events](https://mailroom-docs.shahriyar.dev/api/events): Things that happen in your own product. Post one and whatever [automation](/guide/automations) is waiting for it starts, for that person. - [Webhooks](https://mailroom-docs.shahriyar.dev/api/webhooks): Managing endpoints and reading their history. For what the events *are* and how to check a signature, see [Webhooks](/webhooks/). - [Statistics](https://mailroom-docs.shahriyar.dev/api/stats): `bounce_rate`, `complaint_rate` and `open_rate` are **shares of sent mail out of 100** — so `1.64` is 1.64%, not 164%. ## SDK - [Getting started](https://mailroom-docs.shahriyar.dev/sdk/): The whole API, typed, with **no dependencies** — one `fetch` and Web Crypto. Node 18 or newer, and anywhere else `fetch` exists: Workers, Deno, Bun, the browser. Ships ESM, CommonJS and types. - [Sending](https://mailroom-docs.shahriyar.dev/sdk/sending): console.log(sent.id, sent.ses_message_id, sent.thread_id); ``` - [Reading mail](https://mailroom-docs.shahriyar.dev/sdk/reading): Inbound mail lives in **threads**. A thread is the conversation; a message is one item in it. - [Managing the account](https://mailroom-docs.shahriyar.dev/sdk/managing): await mail.mailboxes.create({ address: "billing@yourdomain.com", display_name: "Billing", signature: "— Accounts", }); - [Errors and retries](https://mailroom-docs.shahriyar.dev/sdk/errors): Anything other than a `2xx` throws. Every error extends `MailroomError` and carries `status`, `code`, `message` and the decoded `body`. ## Webhooks - [Overview](https://mailroom-docs.shahriyar.dev/webhooks/): `id` is also the **delivery id**, so a repeat — a retry after your endpoint timed out, or a replay you triggered — can be recognised and ignored. - [The events](https://mailroom-docs.shahriyar.dev/webhooks/events): Eleven, plus a test. Subscribe with a list of names, or `["*"]` for everything including events added later. - [Verifying a call](https://mailroom-docs.shahriyar.dev/webhooks/verifying): Your endpoint is a public URL. Anybody can post to it. The signature is what separates a real event from a stranger's. - [Retries and replays](https://mailroom-docs.shahriyar.dev/webhooks/retries): Each event is attempted up to **four times**, spread over about forty seconds: ## Optional - [Everything on one page](https://mailroom-docs.shahriyar.dev/llms-full.txt): every page above, concatenated. - [Source](https://github.com/shahriyardx/mailroom): the repository, MIT licensed.