QMail Link Invite — Group 6, Code 86
Starts linking a new device. The caller names the coin of the device to be added and receives a 6-digit pairing code, valid for ten minutes, which that device redeems with Link Accept (87).
LIVE FLEET-WIDE since 1 October 2026
The four device-link commands (86–89) are dispatched on every RAIDA and the inbox rewrite for linked devices is switched on. Verified against the server source and a live probe of the fleet on 6 November 2026. The link registry is local to each RAIDA: a client pairs its devices on the beacon RAIDA(s) it actually polls.
Quick reference
| Command Group | 6 (QMail) |
| Command Code | 86 (0x56) |
| Server function | cmd_qmail_link_invite in cmd_qmail.c |
| Body layout | 48-byte QMail preamble + payload (5) + terminator (2) = 55 bytes |
| Transport | UDP or TCP |
| Encryption | As for any other QMail command |
| Authentication | Caller’s own coin: preamble denomination, serial number and AN checked against the coin database |
| Success response | Status 250 with a 17-byte payload |
Device-link model
One user can run QMail on several devices, each holding its own identity coin, so rotating one device’s password (a POWN of that coin) never locks out the others. Devices link under an authority mailbox, which is the public address. A subordinate device’s coin is a device credential only, never a visible identity: while the rewrite is on, a subordinate’s Ping and Peek are served the authority’s inbox, and its Tell is stamped as coming from the authority (the client must already put the authority in the blob’s sender fields, or the Tell is refused with 198). Uploads are not rewritten; objects stay owned by the device coin that uploaded them.
Each group has exactly one admin, normally the authority itself. The admin is the only device that may list (88) or revoke (89). Every device authenticates each of these commands with its own coin in the preamble, exactly like any other QMail command. The registry is kept per RAIDA in that node’s directory database and is never replicated, so a client repeats the pairing on each beacon RAIDA it uses.
Housekeeping the server does on its own
A device idle for more than 24 months is unlinked. An authority idle for more than 24 months with an active subordinate passes admin to the most senior subordinate (succession). Expired invites are purged. These sweeps run at most once a day, triggered by the open DRD sync command (147). Both 24-month windows are deliberately long for the first year of use.
Request body
After the preamble:
| Offset | Size | Field | Description |
|---|---|---|---|
| 48 | 1 | sub_den | Signed denomination of the device coin being invited. |
| 49–52 | 4 | sub_sn | Serial number of that coin, big-endian. |
| 53–54 | 2 | Terminator | Fixed clear-text terminator 3E 3E. |
The invitee must be an issued coin on this RAIDA (a serial number whose record is populated), and must not be the caller itself.
Which group the invite is for
The server decides whose group the new device joins from the caller’s own standing, and the response says which group that is:
| Caller is… | Result |
|---|---|
| an active subordinate of a group | Invites into its authority’s group and takes admin of it (recovery when the primary device is lost; the address does not change). |
| an authority (any status) | Invites into its own group and reclaims admin. |
| anything else: no row, only a pending invite, or a revoked device | Starts its own group, becoming its authority at slot 0. A revoked device therefore never re-enters its old group by inviting. |
Response body
| Offset | Size | Field | Description |
|---|---|---|---|
| 0–3 | 4 | pairing_code | Big-endian. A 6-digit decimal code (100000–999999) the new device must present to Accept. |
| 4–11 | 8 | invite_expires | Big-endian Unix seconds. Ten minutes after issue. |
| 12 | 1 | group_den | Denomination of the group’s authority coin. |
| 13–16 | 4 | group_sn | Serial number of the authority coin, big-endian. The new device names this pair in Accept. |
Status codes
| Code | Symbol | Meaning |
|---|---|---|
| 250 | STATUS_SUCCESS | Accepted. |
| 176 | ERROR_DEVICE_LIMIT | The group already has 255 devices, or 16 invites are already open for it (expired ones are purged first). |
| 40 | ERROR_INVALID_SN_OR_DENOMINATION | Also returned when the invitee is already an active device of some group, is itself an authority, or is the caller. |
| 16 | ERROR_INVALID_PACKET_LENGTH | Body length or terminator wrong. |
| 40 | ERROR_INVALID_SN_OR_DENOMINATION | A denomination is outside −8…+6, or the request names an impossible relationship (see each command). |
| 8 | ERROR_COIN_NOT_FOUND | The preamble coin (or, for Invite, the invitee) is not an issued coin on this RAIDA. |
| 200 | ERROR_INVALID_AN | The preamble Authenticity Number does not match this RAIDA’s record for the caller’s coin. |
| 194 | ERROR_FILESYSTEM | The registry database could not be read or written. Transient; retry. |
| 254 | ERROR_MEMORY_ALLOC | Server allocation failure. |
Common mistakes
Pairing on one RAIDA only
The registry is per RAIDA. Issue the invite, and have the new device accept it, on every beacon RAIDA the mailbox uses. Each RAIDA issues its own code.
Letting the code expire
The code is valid for ten minutes and is single-use. A second Invite for the same device before the first expires fails with 176 once 16 invites are open; revoke the stale invite (89) or wait.