Mailboxes and Webhooks

A mailbox is a queue of opaque messages the relay keeps for an account until a reader acknowledges them. Machines that are never online at the same time talk through one: one appends, another reads later from where it left off. A webhook turns outside HTTP POSTs (CI, alerting, GitHub) into messages of a mailbox, each body sealed to a key only the account holds. Everything here is the JSON API of nfltr.xyz, and of a relay of your own (nfltr relay serve).


What a mailbox is

A mailbox belongs to an account and has a name of 1 to 128 letters, digits, ., _ and -. The first append or read creates it. Each message (an envelope) carries opaque bytes of at most 1 MiB, which the relay stores and never reads, so a payload is often end-to-end encrypted by its sender. The relay gives each envelope a seq, increasing within the mailbox, and keeps it until a reader acknowledges it or its lifetime ends.

Delivery is at least once. A read never removes anything: a reader that crashes before its acknowledgement reads the same envelopes again, with a higher delivery_count, and skips the ones it already handled by seq.

The full contract is the OpenAPI document of the relay (nfltr.mailbox.v1, the MailboxService and WebhookService operations) and the Go SDK's mailboxclient package.


Authentication

Every call below presents a machine's certificate, the same one the CLI uses, as in the HTTP API examples. nfltr config login saves it as machine.json (the chain in its chain field) and machine.key beside the config file:

D=~/.config/nfltr                        # the directory of NFLTR_CONFIG, when it is set
jq -r .chain "$D/machine.json" > "$D/machine.pem"
C=(--cert "$D/machine.pem" --key "$D/machine.key")
R=https://nfltr.xyz                      # or the address of your own relay

A machine reads and writes the mailboxes of its own account only. A signed-in dashboard session of the account is a caller too.


Appending

The payload is base64 in JSON. Every field but payload is optional:

curl -s "$R/api/v1/mailboxes/inbox/messages" "${C[@]}" -H 'Content-Type: application/json' \
  -d "{\"payload\":\"$(printf 'build 42 passed' | base64)\",\"content_type\":\"text/plain\",\"idempotency_key\":\"build-42-done\"}"
{"seq":"1795065155730399","duplicate":false,"owner":"you@example.com"}

seq is a 64-bit integer, so JSON carries it as a string. It increases within the mailbox, with gaps. owner is the account the mailbox belongs to.

field meaning
idempotency_key At most 128 bytes. The same key from the same sender within 24 hours stores nothing and answers the first append's seq with "duplicate":true, so a sender retries a failed append without making a copy.
replace_key At most 128 bytes. The append removes the mailbox's unacknowledged envelopes with the same key: a reader sees only the newest status of a thing, not every step.
content_type A media type for the reader, at most 128 bytes.
ttl How long the envelope waits unacknowledged, as a duration ("3600s"). Unset or "0s" is the ceiling, 7 days.
notify true sends each browser push subscriber of the mailbox one push with no content (at most one per 30 seconds per mailbox).

Reading from a cursor

A read returns the envelopes after after_seq, oldest first. With wait, it is a long-poll: when there are none, the relay holds the request until one arrives or the wait ends (at most 25 seconds), and then answers an empty list.

curl -s "$R/api/v1/mailboxes/inbox/messages:pull" "${C[@]}" -H 'Content-Type: application/json' \
  -d '{"after_seq":"0","max_messages":100,"wait":"25s"}'
{
  "envelopes": [
    {
      "seq": "1795065155730399",
      "idempotency_key": "build-42-done",
      "replace_key": "",
      "sender_kind": "SENDER_KIND_MACHINE",
      "sender": "…",
      "content_type": "text/plain",
      "payload": "YnVpbGQgNDIgcGFzc2Vk",
      "appended_at": "2026-11-19T10:12:35Z",
      "expires_at": "2026-11-26T10:12:35Z",
      "delivery_count": 1,
      "dropped_before": "0"
    }
  ],
  "owner": "you@example.com"
}

The reader passes the last seq it handled as the next after_seq. max_messages is at most 100 (0 is 100). A reader loop:

AFTER=0
while :; do
  OUT=$(curl -s "$R/api/v1/mailboxes/inbox/messages:pull" "${C[@]}" -H 'Content-Type: application/json' \
    -d "{\"after_seq\":\"$AFTER\",\"wait\":\"25s\"}")
  echo "$OUT" | jq -r '.envelopes[] | .payload | @base64d'
  AFTER=$(echo "$OUT" | jq -r --arg a "$AFTER" '.envelopes[-1].seq // $a')
done

Sender kinds

sender_kind says how the relay authenticated the sender; the sender cannot set it.

sender_kind sender
SENDER_KIND_MACHINE A machine of the account, by its certificate (or a token the relay's identity provider authenticated as that machine). sender is the machine's principal.
SENDER_KIND_SESSION A signed-in dashboard session of the account.
SENDER_KIND_WEBHOOK A webhook of the account. sender is the webhook id.
SENDER_KIND_LOOPBACK_TRUST A relay started in its local development mode, which trusts loopback callers.

Acknowledgement

An acknowledgement removes every envelope up to and including through_seq:

curl -s "$R/api/v1/mailboxes/inbox/messages:ack" "${C[@]}" -H 'Content-Type: application/json' \
  -d '{"through_seq":"1795065155730399"}'
{"removed":1}

GET $R/api/v1/mailboxes?prefix=in lists the account's mailboxes whose name starts with the prefix, each with its newest seq (last_seq) and what waits in it (queued, queued_bytes).


Who reaches a mailbox

Inside an account, a mailbox is held by the machine that touched it first. Another machine of the account reaches it only when it may reach the holder, under the same reach rules that decide which machines it lists and dials (nfltr groups allow, in the CLI reference). A dashboard session reaches all of the account's mailboxes. When a machine is revoked, the mailboxes it holds are deleted with it.

A mailbox that several machines share is declared shared by its client with the header X-Nfltr-Mailbox-Share: holder or member on its requests. There are two kinds, and the first declaring request decides which:

kind made by the holder every other machine of the account
broadcast the holder's append, or a member's read appends and acknowledges reads
drop box the holder's read or acknowledgement, or a member's append reads and acknowledges appends

A broadcast carries what one machine publishes to all (a certificate revocation list, a status); a drop box collects requests for one machine. Reach policy does not enter a shared mailbox's decision. A revoked holder leaves its shared mailboxes in place, with their messages, and the next machine that declares holder takes the hold. A holder gives its hold up with X-Nfltr-Mailbox-Share: release on an acknowledgement. Webhooks and push subscriptions of a shared mailbox are its holder's.


Webhooks

A webhook is an HTTPS address that something outside the account (CI, an alerting system, GitHub) POSTs to. The relay checks each POST with the webhook's secret, seals the body to a public key the account gave it, and appends the sealed body to the webhook's mailbox. The relay stores no body it can read: only the holder of the private key opens one.

The recipient key

The key is P-256, given as its uncompressed point (65 bytes, base64). With OpenSSL:

openssl ecparam -name prime256v1 -genkey -noout -out hook.key
PUB=$(openssl ec -in hook.key -pubout -outform DER -conv_form uncompressed 2>/dev/null | tail -c 65 | base64)

hook.key stays on the machine that reads the mailbox.

A new webhook

auth is WEBHOOK_AUTH_BEARER (the sender presents Authorization: Bearer <secret>) or WEBHOOK_AUTH_GITHUB (the sender signs the body: X-Hub-Signature-256: sha256=<hex HMAC-SHA256 of the body under the secret>, as GitHub does):

curl -s "$R/api/v1/webhooks" "${C[@]}" -H 'Content-Type: application/json' \
  -d "{\"mailbox\":\"ci\",\"auth\":\"WEBHOOK_AUTH_BEARER\",\"recipient\":{\"key_id\":\"k1\",\"public_key\":\"$PUB\"}}"
{
  "webhook": {
    "webhook_id": "wh-0c1f…",
    "mailbox": "ci",
    "auth": "WEBHOOK_AUTH_BEARER",
    "limits": {"max_events_per_minute": 600, "max_body_bytes": 65536},
    "ingress_path": "/api/v1/webhooks/wh-0c1f…/deliveries",
    "recipient": {"key_id": "k1", "public_key": "BH…"},
    "counters": {"dropped_rate_limited": "0", "dropped_mailbox_full": "0", "rejected_too_large": "0", "duplicates": "0"},
    "created_at": "2026-11-19T10:20:00Z"
  },
  "secret": "nfltr_whk_…"
}

The secret is in this answer only. limits can set lower ceilings at creation (max_events_per_minute up to 600, max_body_bytes up to 64 KiB; 0 is the ceiling). A mailbox has at most 16 webhooks.

Deliveries

The webhook's address is the relay's address and its ingress_path. A bearer delivery:

curl -s -X POST "$R/api/v1/webhooks/$HOOK/deliveries" \
  -H "Authorization: Bearer $SECRET" -H 'Idempotency-Key: run-7' \
  -H 'Content-Type: application/json' -d '{"status":"failed","job":"nightly"}'
{"accepted":true,"seq":"1795065162004211"}

For a GitHub webhook, the repository's webhook settings take the address as the payload URL, application/json as the content type and the secret as the secret; GitHub's X-GitHub-Delivery header keeps a redelivery from being stored twice. Any other sender signs the same way:

SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')
curl -s -X POST "$R/api/v1/webhooks/$HOOK/deliveries" -H "X-Hub-Signature-256: sha256=$SIG" \
  -H 'X-GitHub-Delivery: d-1' -H 'Content-Type: application/json' -d "$BODY"
answer when
202 {"accepted":true,"seq":"…"} stored
200 {"duplicate":true} the X-GitHub-Delivery or Idempotency-Key value was seen within 24 hours: nothing stored
401 a wrong or missing secret or signature
404 no such webhook (or a deleted one)
413 the body is over the webhook's max_body_bytes
429 over max_events_per_minute (ERROR_REASON_LIMIT_EXCEEDED), or the mailbox is full (ERROR_REASON_MAILBOX_FULL)

A refused POST counts on the webhook (counters, in GET $R/api/v1/webhooks?mailbox=ci), and the next accepted envelope says how many POSTs were dropped before it (dropped_before). Repeated 401 and 404 answers from one address are rate limited.

Opening a delivery

A delivery is an envelope with sender_kind SENDER_KIND_WEBHOOK and sender the webhook id. Its payload is the sealed body (HPKE, RFC 9180: DHKEM(P-256), HKDF-SHA256, AES-256-GCM), and its content_type is empty: the sender's content type is inside the seal. The Go SDK opens it with hookwire:

import (
	"crypto/x509"
	"encoding/pem"

	"github.com/nfltr/relay/client/mailboxclient"
	"github.com/nfltr/relay/proto/wire/hookwire"
)

block, _ := pem.Decode(hookKeyPEM) // hook.key
ec, err := x509.ParseECPrivateKey(block.Bytes)
if err != nil {
	return err
}
key, err := ec.ECDH()
if err != nil {
	return err
}
mb := mailboxclient.Client{ProxyURL: "https://nfltr.xyz", HTTP: machineClient} // machineClient presents the machine certificate
envs, owner, err := mb.Pull(ctx, "ci", after, 0, 25*time.Second)
for _, e := range envs {
	if e.SenderKind != mailboxclient.SenderWebhook {
		continue
	}
	keyID, _ := hookwire.KeyID(e.Payload)
	contentType, body, err := hookwire.Open(key, hookwire.Binding{Owner: owner, Mailbox: "ci", WebhookID: e.Sender, KeyID: keyID}, e.Payload)
	// ...
}

The seal binds the account, the mailbox, the webhook and the key id, so a sealed body moved to another mailbox does not open. PUT $R/api/v1/webhooks/$HOOK/recipient with a new recipient seals later bodies to a new key (stored ones keep theirs, named by their key id); DELETE $R/api/v1/webhooks/$HOOK deletes the webhook and its unacknowledged deliveries, and refuses its POSTs from then on.


Limits

The same for every account, on nfltr.xyz and on nfltr relay serve:

limit value past it
payload of one envelope 1 MiB ERROR_REASON_LIMIT_EXCEEDED
unacknowledged envelopes in one mailbox 500, and 8 MiB ERROR_REASON_MAILBOX_FULL until an acknowledgement makes room
unacknowledged bytes in all of an account's mailboxes 64 MiB ERROR_REASON_MAILBOX_FULL
mailboxes of an account 256 (at 256, an empty mailbox idle for 7 days makes room for a new one) ERROR_REASON_LIMIT_EXCEEDED
lifetime of an unacknowledged envelope 7 days the envelope is dropped
envelopes per read 100
long-poll wait 25 seconds
idempotency keys remembered 24 hours, the newest 1000 per mailbox
webhooks per mailbox 16 ERROR_REASON_LIMIT_EXCEEDED
webhook body 64 KiB 413
webhook POSTs 600 per minute 429

Errors

A refusal is google.rpc.Status JSON. Code branches on details[0].reason, never on the message: ERROR_REASON_MAILBOX_FULL and ERROR_REASON_LIMIT_EXCEEDED (HTTP 429), ERROR_REASON_UNAUTHENTICATED (401), ERROR_REASON_WEBHOOK_NOT_FOUND (404), ERROR_REASON_FEATURE_UNSUPPORTED (a relay that serves no mailboxes, or no webhooks). A machine outside a mailbox's reach gets 403.


Related docs