Signed webhooks that cannot leak across tenants
Webhooks are signed per the Standard Webhooks specification, retried on failure, and every attempt is kept in a delivery log you can read. Every subscription must state its scope: the organization, one pod or one inbox. A subscription with no scope is refused rather than widened to everything, so a missing field cannot send one customer's mail events to another's endpoint.
The SDKs verify deliveries for you: verifyWebhook in @nofeb/sdk checks the signature against the raw body and refuses timestamps more than five minutes off.
POST /v1/webhooks
{ "url": "https://example.com/nofeb/events",
"events": ["message.received", "approval.requested"],
"scope": "inbox", "inbox_id": "inb_..." } A feed for consumers without a public URL
The event feed returns the same events after a cursor, durably, for workers behind a firewall, batch jobs and agents that would rather pull than be called. Filter it by inbox or thread, or read it newest first.
A stream for clients that stay connected
The WebSocket stream carries the same events as webhooks and the feed, in the same order, each with a cursor. Reconnect with the last cursor and the stream resumes with no gap and no duplicates; a cursor older than the feed keeps is refused rather than silently skipped. Narrow it by inbox, pod or event type, never wider than the credential allows. A client that falls too far behind is disconnected without slowing anyone else, and a revoked credential is cut off at the next heartbeat.
GET wss://API_HOST/v1/stream?inbox_id=inb_...&types=message.*
Sec-WebSocket-Protocol: nofeb.v1
{ "type": "event", "cursor": "...", "event": { "type": "message.received", ... } } Hooks that decide, inside the pipeline
Hooks are called while mail is in flight and change what happens: at inbound.resolve, create an inbox for an unknown recipient or refuse it; at inbound.pre_deliver, accept, reject or quarantine a message and add keywords and metadata; at outbound.pre_send, allow, deny or hold a send and add headers. Each hook has a timeout and fails open or closed, and every call is logged.
A hook can be an HTTPS endpoint, signed like a webhook, or a WebAssembly module that runs inside the pipeline with no network round trip. Modules are built against a published, versioned interface, receive the same request and give the same answer as an HTTPS hook, and run sandboxed with limits on instructions, memory and time. A module can log, read and set metadata on what it is deciding about, and fetch only the URLs you allow. Upload new versions as you go; the last ten are kept for rollback.
POST /v1/hooks
{ "stage": "inbound.pre_deliver", "target": "wasm",
"scope": "inbox", "inbox_id": "inb_...",
"allow_urls": ["https://crm.example.com/api/"],
"failure_mode": "fail_open" }
POST /v1/hooks/{hook_id}/module
Content-Type: application/wasm
<component bytes> Events on a schedule you set
Not every event is caused by mail. Set follow_up_at on a thread and a thread.due event arrives through the same webhooks, feed and stream when that time passes, with the thread's metadata attached, so an agent can be woken by the clock as well as by a reply.
The event catalog
Event types are added, never renamed. Events with a known actor say whether an agent, a person, the console or the system acted, and mail events name their inbox and thread.
| Event | Meaning | Status |
|---|---|---|
message.received | An inbound message was delivered to an inbox. | Shipped |
message.quarantined | An inbound message was held for review: injection score, a hook, a rule, a sender list, spam, virus or DMARC. | Shipped |
message.released | A person released a quarantined message to the inbox. | Shipped |
message.sent | An outbound message was accepted for delivery. | Shipped |
message.delivered | The recipient's server accepted the message. | Shipped |
message.bounced | The message bounced. | Shipped |
message.complained | The recipient marked the message as spam. | Shipped |
message.send_failed | An outbound message failed permanently. | Shipped |
metadata.updated | Metadata on a message, thread or inbox changed. | Shipped |
approval.requested | A send is waiting for human approval. | Shipped |
approval.decided | A pending send was approved or rejected. | Shipped |
inbox.created | An inbox was created. | Shipped |
inbox.expired | A disposable inbox reached its expiry and was removed. | Shipped |
thread.due | A thread's follow_up_at time passed. | Shipped |
thread.driver_changed | A person took a thread over from the agent, or handed it back. | Shipped |
domain.verified | A custom domain passed DNS verification. | Shipped |
policy.violated | A governance policy refused a send (blocklist, allowlist or cap) or an inbound message (sender list). | Shipped |
message.rejected | An inbound message was not delivered because a sender blocklist or a rule rejected it. | Shipped |
forward.confirmation | A Gmail or Outlook forwarding confirmation arrived on a forwarding address, with its code and link. | Shipped |
export.completed | An export finished; it carries signed download links. | Shipped |
export.failed | An export could not be built. | Shipped |
retention.applied | A retention policy moved or deleted messages. | Shipped |
sending.paused | Outbound sending for the organization was paused, because the bounce or complaint rate crossed its threshold or on request. | Shipped |
sending.resumed | Outbound sending for the organization was resumed. | Shipped |
calendar.event.created | A calendar event was created. | Shipped |
calendar.event.updated | A calendar event, or one occurrence, changed or was answered. | Shipped |
calendar.event.deleted | A calendar event was deleted. | Shipped |
calendar.event.invited | An invitation, or an update to one, arrived by email and is on the calendar. | Shipped |
calendar.event.cancelled | The organizer cancelled an event, or one occurrence. | Shipped |
calendar.event.replied | A guest answered an event this inbox organizes. | Shipped |
calendar.event.counter_proposed | A guest proposed a new time for an event this inbox organizes. | Shipped |
calendar.changed | A calendar was created, changed or deleted. | Shipped |
Status of everything on this page
Every capability named above, with its status as reconciled against the engine.
| Capability | What it does | Status |
|---|---|---|
| Signed webhooks with required scope | Standard Webhooks signatures, retries and a delivery log. Scope (organization, pod or inbox) is required, so a subscription never silently widens to everything. | Shipped |
| Durable event feed | A pull feed of every event, oldest first after a cursor, for consumers that cannot receive webhooks. | Shipped |
| Realtime stream | A WebSocket stream of the same events as webhooks and the feed, in order, resumable from a cursor with no gap and no duplicates, and filtered by inbox, pod or event type within the credential's own reach. | Shipped |
| HTTPS hooks in the pipeline | Signed HTTPS callouts that change what happens: create or reject an inbox for an unknown recipient, accept, reject or quarantine a message before delivery, and allow, deny or hold a send, each with a timeout and a fail-open or fail-closed mode. | Shipped |
| WebAssembly hooks | The same pipeline stages as HTTPS hooks, run as a WebAssembly module you upload, built against a published, versioned interface. Modules run sandboxed with fuel, memory and time limits, can fetch only the URLs you allow, read and set metadata on what they decide about, and keep their last ten versions for rollback. | Shipped |
| Follow-up timers | Set follow_up_at on a thread and, when that time passes, a thread.due event carrying the thread's metadata goes to your webhooks and the event feed, so agents need no scheduler of their own. | Shipped |
| Change log per inbox | Every change to an inbox since a state you already hold, for sync without re-reading. | Shipped |
| Idempotent sends | Retry a send with the same Idempotency-Key and it is sent once. | Shipped |
| OpenAPI document | A published OpenAPI document kept identical to the served routes by a parity test. | Shipped |
| Published plan table | The plan table and overage prices are served publicly by the API, and this site's pricing is checked against it. | Shipped |
| TypeScript and Python SDKs | Official clients generated from the OpenAPI document: @nofeb/sdk for Node, Deno, Bun and edge runtimes, and nofeb for Python with sync and asyncio clients. Both chain long polls for waitForEmail, retry idempotent requests, page through lists and verify webhook signatures. | Shipped |