Concepts.

OverviewQuickstartConceptsErrors and limits

Inboxes

An inbox is a real email address that belongs to one bot, such as support-bot@bots.emlbot.com. The address is also the inbox's id, so there is nothing extra to look up: wherever the API wants an inbox_id, you pass the address, URL-encoded in paths (support-bot%40bots.emlbot.com).

What happens to incoming mail

1. DeliveredRouted by the address it was delivered to, never by the To header.
2. CheckedRefused at delivery if the address has no inbox, or the message is over 25 MB.
3. StoredWith its raw source and attachments. A second copy of the same Message-ID is dropped.
4. Threaded and labelledJoined to a thread.
   receivedunread
5. AnnouncedAs an event.
   message.received

Because routing uses the delivery address, a forged header cannot push mail into another inbox.

Deleting an inbox

Keys and scopes

Every API call is made with a key, sent as Authorization: Bearer emb_live_.... It is shown in full once, in the response that creates it. A lost key cannot be recovered: create a new one and revoke the old one.

Scopes

A key's scopes decide which calls it may make. Give each bot only what it needs.

A call without the scope it needs answers 403 forbidden with a message naming the missing scope.

Inbox-limited keys

A key created with inbox_ids works only on those inboxes. Every other inbox behaves as if it did not exist: the API answers 404 not_found, not 403, so the key cannot even learn which other addresses you have. Lists, the event log and the approval queue are filtered the same way.

Admin calls (keys, webhooks, inbox create and delete, audit) need the admin scope and no inbox list. An admin key limited to inboxes acts with every scope on its own inboxes but cannot change account-wide settings.

Rotating a key

1. Create the replacementPOST /keys
2. Deploy it to the botCheck last_used_at on the old key (updated at most once a minute) to see whether it is still in use.
3. Revoke the old keyDELETE /keys/{id} Takes effect on the next request.

Request budgets

A key or a bot is limited to 600 requests a minute, and to 120 writes a minute. A write is any request that is not a GET. Over either budget the call answers 429 rate_limited with Retry-After, and the message "This key passed its request budget (600/min, 120 writes/min). Retry after the Retry-After header." The admin token and signed-in people are not counted. Long-poll GET /v0/me/wait counts once per request, not again while the wait stays open.

Users and roles

People use the console; bots use keys. People sign in with Google, and only invited addresses can: anyone else sees a "Not invited" page and nothing is created. The first owner is set up when the account is opened; after that the owner invites everyone else.

The send policy below is a property of keys. Owners and admins sending from the console are not held to any key's allowlist or cap, which is what lets a person step in when a bot cannot.

Send policy

Each key carries three sending rules, set when the key is created:

Allowlist entries

Matching ignores case and display names: Dana Lee <DANA@yourco.com> matches dana@yourco.com.

What happens on every send and reply

The same checks run for send and reply, in this order:

1. 1Collect recipientsEveryone in to, cc and bcc, including addresses added by reply_all.
2. 2Check the allowlistIf allow_recipients is not empty and any recipient matches no entry, then:
   202 pending_approval

   With approval: "outside", nothing is sent. The whole message is parked, the call answers 202 {"status": "pending_approval", "approval_id": "..."}, and a message.approval_requested event is emitted. A parked send does not use the cap yet.

   403 forbidden

   Otherwise the call answers 403 forbidden naming the first address that was not allowed, and nothing is sent.

3. 3Reserve one send from the daily capThe cap counts sends (one call), not recipients, per UTC day. If it is already spent, the call answers 429 rate_limited with a Retry-After header.
4. 4Send and storeThe message is saved to the inbox with the sent label and a message.sent event is emitted. If delivery fails (502 send_failed), the reserved send is given back.

Successful sends, and cap refusals, carry three headers so a bot can pace itself:

That 429 is the daily send cap. A key can also be refused earlier, on any call, when it passes its request budget of 600 a minute and 120 writes a minute. Both use name: "rate_limited".

Approvals

Approvals are how a bot can ask before writing to someone new. When a key with approval: "outside" tries to mail an address outside its allowlist, the send is parked in the approval queue with everything needed to perform it later, attachments included. The bot gets an approval_id straight away and can carry on.

A person, or another key with the approve scope, then reviews it in the console or with GET /approvals. Each pending item shows the recipients, subject, a preview of the body, attachment names and which key asked.

Rules that keep the gate honest:

How long a mail approval lasts

A mail approval expires 72 hours after it is created. It is stored as rejected with outcome expired, and the expiry is audited as approval.expire. Its draft, if still pending_approval, is marked failed with send_error The approval expired. Deciding it answers 409 approval_expired: "This approval expired after 72 hours. Ask the bot to send again."

A mail approval is bound to the exact content and recipients it was created with. Carrying it out sends that stored request, and policy is checked again first. If the content no longer matches a sha256 over to, cc, bcc, subject, text, html and the attachment ids, the call answers 409 approval_stale.

A new mail approval for the same inbox and the same draft or thread supersedes older pending ones. Each older one is stored as rejected with outcome superseded, and superseded_by set to the new approval id. Deciding one that is no longer pending answers 409 conflict.

To be told when one arrives, subscribe a webhook to message.approval_requested.

Events

An event is a record that something happened. There are three types today. Every payload also has type: "event", event_type and event_id.

The durable log

Each event is written to the event log first and only then handed to webhook delivery. The log is the source of truth: if your receiver was down, a delivery failed for good, or you never set up a webhook, everything is still there.

Read it with GET /events?after=<seq>. Each event has a seq number that only goes up. The pattern is a cursor:

1. 1StartWith after=0, or with the last next_after you saved.
2. 2Handle the batchOldest first.
3. 3Save next_afterOnly after they are handled, then ask again.

If your process crashes between steps 2 and 3 you will see the last batch again, so make handlers safe to repeat by keying on event_id. Many bots combine both delivery styles: webhooks for speed, and a periodic pass over the log to fill any gaps.

Webhooks

A webhook pushes events to your HTTPS endpoint as they happen. Each one has a URL, the event_types it wants (all three if you leave it out) and optionally the inbox_ids it cares about (every inbox if you leave it out).

What a delivery looks like

A POST with a JSON body, which is the event payload, and these headers:

POST /emlbot HTTP/1.1
Host: hooks.yourco.com
Content-Type: application/json
User-Agent: emlbot-webhooks/1
webhook-id: evt_9b2c4d6e8f0a1b3c5d7e9f1a2b4c6d8e
webhook-timestamp: 1792687083
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
svix-id: evt_9b2c4d6e8f0a1b3c5d7e9f1a2b4c6d8e
svix-timestamp: 1792687083
svix-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{"type":"event","event_type":"message.received","event_id":"evt_9b2c...","message":{...},"thread":{...}}

The svix-* headers repeat the webhook-* ones, so any Standard Webhooks or Svix verification library works unchanged.

How the signature is made

1. 1The keyTake your secret, drop the whsec_ prefix and base64-decode the rest. Those bytes are the HMAC key.
2. 2The signed contentwebhook-id, a dot, webhook-timestamp, a dot, then the raw request body exactly as received.
   ${id}.${timestamp}.${body}
3. 3The MACCompute HMAC-SHA256 over it and base64-encode the result.
4. 4The headerv1, followed by that value. The header may carry several space-separated signatures; accept the request if any one matches.

Verifying in Node.js

Verify against the raw body bytes, before any JSON parsing, or the signature will not match.

import crypto from "node:crypto";

// secret is the whsec_... value from POST /webhooks or rotate-secret
export function verifyEmlbotWebhook(rawBody, headers, secret) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures) return false;

  // Refuse stale or future timestamps so a captured request cannot be replayed.
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(age) || age > 5 * 60) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = crypto
    .createHmac("sha256", key)
    .update(`${id}.${timestamp}.${rawBody}`)
    .digest("base64");

  return signatures.split(" ").some((part) => {
    const [version, sig] = part.split(",");
    if (version !== "v1" || !sig) return false;
    const a = Buffer.from(sig);
    const b = Buffer.from(expected);
    return a.length === b.length && crypto.timingSafeEqual(a, b);
  });
}

And a receiver built on Express that verifies, stores the event in SQLite, handles it, and only then answers. Insert or ignore on event_id, handle the row when processed is still 0, mark it processed, then answer 204. A row that is stored but not yet processed is handled on the next delivery. Duplicates are expected; the primary key makes a second insert harmless. This example uses node:sqlite (Node 22, marked experimental). Any SQLite library works with the same INSERT … ON CONFLICT DO NOTHING.

import express from "express";
import { DatabaseSync } from "node:sqlite";
import { verifyEmlbotWebhook } from "./verify.js";

const app = express();
const db = new DatabaseSync("emlbot-events.sqlite");
db.exec(`CREATE TABLE IF NOT EXISTS emlbot_events (
  event_id TEXT PRIMARY KEY,
  body TEXT NOT NULL,
  processed INTEGER NOT NULL DEFAULT 0
)`);
const insertEvent = db.prepare(
  "INSERT INTO emlbot_events (event_id, body) VALUES (?, ?) ON CONFLICT DO NOTHING"
);
const loadEvent = db.prepare(
  "SELECT body, processed FROM emlbot_events WHERE event_id = ?"
);
const markProcessed = db.prepare(
  "UPDATE emlbot_events SET processed = 1 WHERE event_id = ?"
);

app.post("/emlbot", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString("utf8");
  if (!verifyEmlbotWebhook(raw, req.headers, process.env.EMLBOT_WEBHOOK_SECRET)) {
    return res.status(401).end();
  }

  const event = JSON.parse(raw);
  insertEvent.run(event.event_id, raw); // insert or ignore; a second delivery keeps the row
  const row = loadEvent.get(event.event_id);
  if (row.processed) return res.status(204).end(); // already handled

  const saved = JSON.parse(row.body);
  // handle saved.event_type from the table; a throw skips the 204 so the delivery retries
  markProcessed.run(event.event_id);
  res.status(204).end(); // only after the event is stored and marked processed
});

app.listen(3000);

Answer 204 only after the event is stored and marked processed. A row that is stored but not yet processed is handled on the next delivery. Duplicates are expected; the primary key makes a second insert harmless.

The five-minute timestamp window is a choice on your side, recommended by the Standard Webhooks scheme. Every attempt, including a retry, is signed with a fresh timestamp, so retries pass it.

Retries

A delivery succeeds when your endpoint answers any 2xx within 10 seconds. Anything else is a failure, including a timeout and any redirect (redirects are never followed). After a failure the delivery is retried on this schedule:

After the eighth retry the event is no longer pushed, but it stays in the event log for you to read.

Disabled webhooks

Turning a webhook back on

POST /v0/webhooks/{id}/enable uses the same auth as creating a webhook. A webhook that is not in this workspace answers 404.

Enable sends one signed webhook.test event first. Redirects are not followed, the request times out after 10 seconds, and the URL has to pass the same destination rules as create. If that check fails, the call answers 422 webhook_unhealthy and the webhook stays disabled. The body is name, message and status. The message is "Your endpoint answered <status> (or timed out). Fix it, then call enable again."

If the check passes, the webhook is enabled, failures is reset to 0, and the change is audited as webhook.enable. The response is { webhook, replay }. replay.failed_events is the count of event_deliveries rows with status failed for this webhook, and replay.hint is GET /v0/events?after=<seq> to catch up. That preview does not replay the events.

Secrets and destinations

The whsec_ secret is returned only by create and rotate-secret. Rotating takes effect on the next delivery. Webhook URLs must be public HTTPS hosts; the full rules are on the errors and limits page.

Threads and labels

Threads

A thread is a conversation inside one inbox. When mail arrives, EMLbot reads its In-Reply-To and References headers and, if they point at a message already in that inbox, adds it to that message's thread. Otherwise it starts a new one. Threads never span inboxes, so mail to one bot cannot attach itself to another bot's conversation.

A reply made through the API joins the thread of the message it answers and sets In-Reply-To and References so the other side's mail client threads it too. A new send starts a new thread. Each thread keeps its subject, the senders and recipients across its messages, a preview of the latest message, message_count and the time of the last message.

Labels

Labels are short tags on messages that your bot uses to keep track of work. EMLbot sets three itself:

1. Every inbound message
   receivedunread
2. Your bot finishes a sent replyAfter a 200, PATCH with add_labels: ["handled"] and remove_labels: ["unread"]. After a 202 pending_approval, add waiting-approval and keep unread. After 403 or 429, leave unread in place.
   handledwaiting-approvalneeds:human
3. Every message sent from an inbox
   sent

Nothing removes unread automatically, so it works as a to-do flag: list with labels=unread, and remove unread only after a reply or send answered 200. Add your own labels the same way, or pass labels when sending. A thread's labels are all the labels on its messages, and both messages and threads can be filtered by label; naming several labels returns only items that carry all of them.

Labels are 1 to 64 characters from a-z 0-9 . _ : -, so names like billing, needs:human or v2.triaged all work. Up to 20 can be added and 20 removed per call.

Digest wake

A bot can be woken by email. PUT /v0/bots/{id}/digest-address refuses any address that resolves to an inbox in any EMLbot workspace. The call answers 422 digest_loop with the message "That address is delivered into EMLbot itself; a wake email to it would wake the bot again. Use the bot's outside address." The same check runs when a wake is updated and email_digest.to is set.

Domains

Audit log

The audit log records every security-relevant change, so you can answer "who did that, and when?". Read it with GET /audit using an admin key. Recorded actions:

Each entry has:

Secrets and message content are never written to it; for webhooks only the host is kept, not the path. The API has no way to edit or delete entries.

Read next