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
- HTTP API examples: presence and the machine certificate
- Organisations: machine names and revocation
- Run your own relay: the same API on a machine of your own
- Go SDK:
mailboxclient,hookwire