Limits
| Limit | Value | Enforced by | Answer when exceeded |
|---|---|---|---|
| Plaintext | 1 MiB (1,048,576 bytes) | Sender | too_large before sealing |
| Envelope | 38 B to 1 MiB + 38 B | Relay | 413 above, 400 below |
| Envelopes waiting per direction | 64 | Relay | 507 |
| Mailbox size, both directions | 32 MiB | Relay | 507 |
| Envelopes per fetch | 16 | Relay | Larger limit is reduced to 16 |
| Envelopes per wire body | 64 | Client | Body rejected as malformed |
| Sequence | 1 to 2^64 - 1 | Both | 404 for an invalid path segment |
| Idle mailbox | 30 days after the last write or claim | Relay | Mailbox erased |
What counts toward the quotas
Only envelopes waiting to be read. Pruning frees both the slot and the bytes immediately. A receiver that keeps up never comes close to either quota: the limits exist so that a link whose other device has gone away for good cannot grow without bound.
The idle timer
Every claim and every stored envelope restarts a 30-day timer. Fetching, pruning and watching do
not. When the timer fires, the relay erases the mailbox exactly as DELETE /mailbox/<id> would.
Consequences:
- A link where only one side writes stays alive as long as that side writes at least once every 30 days.
- A link where nobody writes for 30 days loses its mailbox. Both devices still hold the link key,
so the next request claims a fresh, empty mailbox under the same id and the link continues.
Envelopes that were waiting when it expired are lost.
X-Relay-Laststarts again from nothing, so a sender continues from 1. A receiver holding a higherlast_receivedwould refuse those as replays. See Link lifecycle for how to handle this.
Sizing your messages
With 64 slots and 32 MiB per mailbox, a direction can hold, for example, 64 messages of 512 KiB, or 32 messages of 1 MiB before the mailbox total runs out. If your companion may be offline for days while the primary keeps producing changes, coalesce changes into fewer, larger messages, or send a "full state" message that supersedes older ones. See Designing messages.