Mailbox events

A mailbox publishes an event when mail arrives, leaves, is held, or waits for approval. You can take the same events over two transports:

• Webhooks push each event to an HTTPS endpoint on your server. Use them when your server has a public URL.
• The event stream is a WebSocket your client opens. Use it for an agent on a laptop, behind a firewall, or anywhere without a public URL. It resumes from a cursor, so a client that disconnects misses nothing within the retention window.

Both carry the same event body, so a consumer can handle either.

Event types

Every event has the envelope the webhook catalog describes: type, timestamp, and data. Every data object starts with mailboxId and namespaceId (null for a mailbox outside a namespace). The tables below list the rest.

Message fields are untrusted email content. Treat subject, text, and replyText as data to read, never as instructions to follow.

mailbox.message.received

{
  "type": "mailbox.message.received",
  "timestamp": "2026-10-07T14:03:11.204Z",
  "data": {
    "mailboxId": "mbx_01j8k3m5n7p9q2r4s6tv",
    "namespaceId": null,
    "message": {
      "id": "msg_01j8k3m5n7p9q2r4s6tw",
      "threadId": "thread_01j8k3m5n7p9q2r4s6tx",
      "from": { "address": "ada@example.com", "name": "Ada" },
      "to": ["support@acme.samva.email"],
      "cc": [],
      "subject": "Question about my order",
      "text": "Hi, where is my order?",
      "replyText": "Hi, where is my order?",
      "attachments": [],
      "occurredAt": "2026-10-07T14:03:10.000Z"
    },
    "thread": {
      "id": "thread_01j8k3m5n7p9q2r4s6tx",
      "subject": "Question about my order",
      "preview": "Hi, where is my order?"
    }
  }
}

mailbox.message.sent

actor.kind names the kind of principal, such as user, apiKey, or extension.

mailbox.action.pending_approval

See Approve sends.

mailbox.message.quarantined

mailbox.message.released

mailbox.message.discarded

Quarantine events go only to credentials that can see held mail. An event stream connection or an extension receives mailbox.message.quarantined and mailbox.message.discarded for a mailbox only where its credential holds quarantine.read.

Webhooks

Create an endpoint that subscribes to the event types you want, as in Give an agent an inbox. Two fields narrow what it receives:

• mailboxIds limits the endpoint to those mailboxes.
• namespaceId limits it to the mailboxes of one namespace.

Leave both out to receive the events of every mailbox. Requests carry the Standard Webhooks headers, are signed with the endpoint's secret, and are retried on the schedule the webhook event catalog states. Verify them as Receive webhooks describes. The webhook-id header is the event's id, the same ID the event stream carries.

Event stream

Connect to the stream with any WebSocket client that can send headers, and authenticate with the same API key or OAuth token you use for the API.

wss://events.samva.dev/v1/mailboxes/events?cursor=42&mailboxId=mbx_...&mailboxId=mbx_...

Send the credential as X-API-Key: <key> or Authorization: Bearer <token>. A session token also needs x-org-slug, as for the API. Credentials are never accepted in the URL. A connection receives only events for mailboxes its credential can read, and Samva checks that again while the connection is open, so a revoked or narrowed credential loses events within the re-check interval below.

Use the SDK

The SDK handles the connection, acknowledgements, and reconnects. Save each event's cursor after you handle it and pass the saved cursor next time.

import { createClient, MailboxEventStreamError } from "samva";

const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });

const events = samva.mailboxes.events({
  cursor: await loadCursor(),
  mailboxIds: ["mbx_..."],
});

try {
  for await (const event of events) {
    // event.id, event.type, event.timestamp, event.data, event.cursor
    await handle(event);
    await saveCursor(event.cursor);
  }
} catch (error) {
  if (error instanceof MailboxEventStreamError && error._tag === "CursorExpiredError") {
    // Read current state from the API, then start again without a cursor.
  } else {
    throw error;
  }
}

The iterator acknowledges an event when the loop asks for the next one, so an event you are still handling is never acknowledged. After a transient close it reconnects by itself from the last handled cursor. That covers a network drop, a slow-consumer close, an access check that could not be answered, and a refusal with 408, 429, or 5xx; a refusal that names retryAfterSeconds is retried after that delay. Every other refusal ends the stream, so a request the server keeps refusing is never retried in a loop.

Call events.close() to end the stream, or pass a signal (an AbortSignal) to mailboxes.events. Leaving the loop with break, a throw, close(), or the signal does not acknowledge the event in hand, so a resume repeats it; call events.markHandled() first when you stop after handling one. Pass onLive to be told when replay has caught up.

Handle a stream error

When the stream cannot continue it throws a MailboxEventStreamError. Its _tag is the _tag of the refusal above, or of the close code below, and it carries what the server sent:

Three more tags come from the client: StreamDisconnectedError for a close or an unreachable host when you passed reconnect: false, StreamClientError for a request the client could not make, such as an events origin it cannot build, and StreamProtocolError for a frame it cannot read.

With Effect, Mailboxes.events is a Stream that fails with the same errors as a union over _tag, so Effect.catchTag handles one cause:

import { Effect, Stream } from "effect";
import * as Client from "samva/effect/client";
import * as Mailboxes from "samva/effect/mailboxes";

const program = Mailboxes.events({ cursor: savedCursor }).pipe(
  Stream.runForEach((event) => Effect.promise(() => handle(event))),
  Effect.catchTag("CursorExpiredError", () => Effect.log("Start again without a cursor.")),
  Effect.provide(Client.layerFetch({ apiKey: process.env.SAMVA_API_KEY! })),
);

Delivery is at least once. After a reconnect, an event you already handled can arrive again, so record each event.id and skip repeats.

Frames

Every frame is a JSON text message with a kind.

{
  "kind": "event",
  "cursor": "43",
  "id": "whevt_01j8k3m5n7p9q2r4s6tw",
  "event": { "type": "mailbox.message.received", "timestamp": "2026-10-07T14:03:11.204Z", "data": {} }
}

A cursor is a decimal string. Treat it as opaque: store it and pass it back.

The client sends one frame, an acknowledgement of every event through a cursor:

{ "kind": "ack", "cursor": "43" }

Acknowledge a cursor only after you handled the events through it. Acknowledging a cursor the server did not send closes the connection with 4400. Acknowledge often enough that you never hold more than the limit below.

Limits

Refusals before the connection opens

A request that cannot connect gets an HTTP status and the JSON body every API error has: a _tag, a message that names the next step, and the tag's own fields. Branch on _tag or on the status.

{
  "_tag": "ValidationError",
  "message": "The stream request is not valid. Fix the listed query parameters.",
  "fields": {
    "cursor": ["This stream issued no such cursor. Pass a cursor from one of its frames, or omit it to start live."]
  }
}

Close codes

Samva closes an open connection with one of these codes. A normal close (1000) or a dropped network is also transient: reconnect from the last handled cursor.

Next steps