QMail Overview (Group 6)
The RAIDA messaging surface. The core commands cover the full lifecycle: upload encrypted file fragments, upload large file pages, notify the recipient’s beacon RAIDA, poll or peek the beacon for new mail, and download the stored fragments.
Overview
QMail is RAIDA’s store-and-forward messaging service. A message is split into stripes (typically 7 data + 1 parity) and one stripe is uploaded to each of 8 RAIDA servers. Current clients upload each stripe with the resumable Object Transfer commands 76–79; the legacy one-shot upload command 70 and page upload command 75 remain accepted for older senders. The sender then notifies the recipient’s “beacon” RAIDA — a single RAIDA agreed in advance with the recipient — that mail is waiting. The recipient long-polls (ping) or non-blocking-checks (peek) the beacon, downloads the private file_type=0 meta object first, and then reassembles the body and attachments locally.
Public Tell, private meta
The Tell is public to the beacon operator and carries routing, server locations, object sizes/checksums, and the inbox-fee locker needed for fee validation. Human-readable fields such as subject, filenames, labels, and preview text are private CBDF metadata and must be stored in file_type=0, not in the Tell.
Current QMail commands are wrapped in the standard 32-byte RAIDA AES-128 packet header. The 48-byte QMail preamble documented below is not that packet header; it is the first 48 bytes of the decrypted request body after the RAIDA header has been parsed.
All six active commands are encrypted at the wire level using AES-128 keyed by the caller’s selected coin AN. For upload, upload large page, tell, ping, and peek, the handler also compares the preamble AN against the stored coin record identified by the preamble. Download currently relies on wire decryption and file/ACL checks.
Object Transfer v1
The stable QMail Object Transfer contract preserves commands 70–75 for compatibility and assigns commands 76–84 to resumable byte-range transfer, object information, live capability discovery, and owner-authorized deletion.
Per-command wire formats live on the dedicated pages linked from the sidebar: upload, upload large page, tell, ping, peek, and download. The stable resumable-transfer contract is documented on the Object Transfer overview and its nine per-command pages (76 begin through 84 delete).
Command index
Every Group 6 command number, what it is for, and whether it is actually running on the fleet. The status column was verified against the server source and a live probe of all 25 RAIDAs on 6 November 2026 (22 answered; RAIDAs 5, 18 and 19 were unreachable over TCP that day). "Live fleet-wide" means every reachable RAIDA dispatches the command. Behaviour that is implemented but compiled out is noted per row; the full list of switches is on the Pending Protocol Changes page.
| Code | Command | What it does | Status |
|---|---|---|---|
| 70 | upload | Legacy one-shot upload of one encrypted file stripe (up to 256 KB) under a 16-byte GUID and file_type. Still accepted for compatibility; new clients use 76–79. | Live fleet-wide. Legacy path. |
| 71 | tell | Tells the recipient’s beacon RAIDA that mail is waiting: routing header, recipient entries, server locations and the file manifest. Authenticated by the sender’s coin; gated per recipient by the DRD white/black lists and inbox fee. | Live fleet-wide. Inbox-fee funding check is not enforced (Phase 1). |
| 72 | ping | Long-poll the beacon for new Tells. The connection parks until a Tell arrives or the timeout expires. Non-destructive: a Tell stays for 30 days and can be fetched by every device. | Live fleet-wide |
| 73 | peek | Non-blocking check of the beacon inbox; returns waiting Tells immediately. Same non-destructive semantics as ping. | Live fleet-wide |
| 74 | download | Legacy page download of a stored stripe by GUID, file_type and page number (256 KB pages). Still serves files written by 70/75; objects written by 76–79 are read with 81/82. | Live fleet-wide. Legacy path. |
| 75 | upload large page | Additive page upload for files over one page, same GUID model as 70, with a 1 GiB per-GUID accumulation cap. The shipped client does not use it. | Live fleet-wide. Legacy path. |
| 76 | object_begin | Opens a resumable transfer: declares size, hash, storage class, retention and generation; reserves capacity; returns the accepted chunk size. Also the replace path (operation 1, owner only, higher generation). | Live fleet-wide. Streaming to disk on; payment gate returns free (Phase 1). |
| 77 | object_put_range | Uploads one byte range of the object, in any order, idempotent on identical overlaps. | Live fleet-wide |
| 78 | object_transfer_status | Lists the ranges the server already holds so a dropped upload can resume; also used to poll an asynchronous commit. | Live fleet-wide |
| 79 | object_commit | Verifies completeness and the whole-object hash, then atomically publishes the generation. Opt-in asynchronous mode returns 246 and the client polls 78. | Live fleet-wide |
| 80 | object_abort | Releases an incomplete transfer and its reservation. | Live fleet-wide |
| 81 | object_info | Returns committed metadata (size, hash, generation, expiry) for the latest or a named generation. | Live fleet-wide |
| 82 | object_get_range | Downloads an arbitrary byte range pinned to a generation; can append per-chunk hashes on request. | Live fleet-wide |
| 83 | object_capabilities | Returns the live server limits and storage classes. Response is still schema 1 and does not advertise the newer extensions. | Live fleet-wide |
| 84 | object_delete | Owner-only deletion; publishes a tombstone generation. | Live fleet-wide |
| 85 | subscribe | An allow-listed vendor tops up a mailbox’s prepaid storage credit (v1 32-bit or v2 64-bit payload). | Live fleet-wide. Credit is recorded, but the upload gate that spends it is switched off. |
| 86 | link_invite | Multi-device: a device issues a 6-digit pairing code that invites another coin into its mailbox group. | Live fleet-wide since 1 October 2026. |
| 87 | link_accept | Multi-device: the invited device redeems the code and joins the group as a subordinate device. | Live fleet-wide since 1 October 2026. |
| 88 | link_list | Multi-device: the group admin lists linked devices and open invites. | Live fleet-wide since 1 October 2026. |
| 89 | link_revoke | Multi-device: the group admin removes a device or cancels its invite. | Live fleet-wide since 1 October 2026. |
| 90 | object_extend_retention | Moves a committed object’s expiry forward without re-uploading it. An ordinary preamble command, not part of the 76–84 framing family. | Live fleet-wide. Duration billing is off, so it charges nothing. |
| 91 | object_set_acl | Would replace the access-control list on a committed object so it can be shared with specific coins or made private. | Proposed, not implemented. Returns 6. |
| 92 | object_get_acl | Would read back an object’s access-control list. | Proposed, not implemented. Returns 6. |
| 93 | object_exists (no page yet) | Unauthenticated existence check that a beacon sends to an independent content server named in a Tell. RAIDAs send it; they do not answer it. | Not a RAIDA command. Returns 6 on every RAIDA. |
Three command families
Legacy paged storage (70, 74, 75) stores fixed 256 KB pages under a GUID and is kept for compatibility. Object Transfer (76–84, plus 90) is the resumable byte-range model every new client should use; it is TCP-only with a 32-bit body length in the request header. Mailbox commands (71–73, 85–89) are ordinary preamble-authenticated commands over UDP or TCP. Commands 91–93 are reserved numbers with no handler on any RAIDA.
End-to-end flow
Sender Storage RAIDAs (x8) Beacon RAIDA Recipient
| | | |
|-- upload 70 or 75 ----->| one/page per RAIDA, parallel| |
|<-- 250 OK --------------| | |
| | | |
|-------------------- tell (cmd 71) --------------------->| |
|<------------------- 250 OK -----------------------------| |
| | |
| |<-- ping (cmd 72) -------|
| | long-poll, parks fd |
| | |
| |-- 250 + tell blob ----->|
| | |
| |<------------------------- download (cmd 74) -----------|
| | one per RAIDA, parallel |
| |-- 250 + 256KB page ------------------------------------>|
| (reassemble locally)
Universal preamble (48 bytes)
Every QMail request body begins with a 48-byte preamble that authenticates the caller/mailbox identity. The preamble is the same for all six active commands and is separate from the RAIDA packet header. Its layout matches qmail_preamble_t in the raidax source:
Offset convention note: raidax counts the encrypted challenge(16) plus the QMail identity block as this 48-byte preamble; rest_core often names only the identity block QMAIL_PREAMBLE_SIZE = 32 because the protocol layer prepends the challenge separately. These are the same bytes with different offset origins.
| Offset | Size | Field | Description |
|---|---|---|---|
| 0–15 | 16 | Challenge | 12 random bytes followed by a 4-byte big-endian CRC32 of the random bytes. Required for replay protection. |
| 16–23 | 8 | Session ID | Set to all zeros for the standard QMail encryption mode. |
| 24–25 | 2 | Coin Type | Fixed 00 06 — the QMail/CloudCoin network ID. |
| 26 | 1 | Denomination | Caller/mailbox coin denomination (signed; valid range −8 to +6). |
| 27–30 | 4 | Serial Number | Caller/mailbox coin serial number (big-endian). Identifies the AN-bearer being authenticated. |
| 31 | 1 | Reserved | Was Device ID. Server reads and ignores — available for future use. Set to 0. |
| 32–47 | 16 | Authenticity (AN) | Caller/mailbox 16-byte AN for this RAIDA. Upload, tell, ping, and peek compare this to the stored AN for the (denom, SN) and reject with ERROR_INVALID_AN on mismatch. |
Status codes
QMail uses the standard RAIDA status enum from protocol.h. The codes any QMail handler can return:
| Decimal | Hex | Symbol | Meaning |
|---|---|---|---|
| 8 | 0x08 | ERROR_COIN_NOT_FOUND | The (denom, SN) in the preamble is not loaded on this RAIDA. |
| 16 | 0x10 | ERROR_INVALID_PACKET_LENGTH | Body too short for the command, missing terminator, or declared payload size doesn’t match the body length. |
| 18 | 0x12 | ERROR_WRONG_RAIDA | For tell: no recipient inbox could be written (zero deliveries). |
| 34 | 0x22 | ERROR_INVALID_ENCRYPTION | Wire-level decryption failed before the command body was reached. Most often caused by sending a zero-AN preamble or selecting an encryption coin the RAIDA doesn’t hold. |
| 40 | 0x28 | ERROR_INVALID_SN_OR_DENOMINATION | Denomination outside the allowed −8…+6 range. |
| 167 | 0xA7 | ERROR_PAYMENT_PROCESSING | Temporary payment or inbox-fee validation dependency failure; retry the operation. |
| 169 | 0xA9 | ERROR_PAYMENT_REQUIRED | Upload enforce mode: storage fee is due but the locker is all-zero, empty, underfunded, or already claimed for another GUID. (Zero fee / welfare: all-zero locker is accepted.) Also used by Tell when an inbox fee is due and no locker was supplied. |
| 194 | 0xC2 | ERROR_FILESYSTEM | Server failed to create a directory, write a file, or arm an inotify watch. |
| 198 | 0xC6 | ERROR_INVALID_PARAMETER | Field validation failed (bad coin type, timestamp out of range, stripe count out of range, page beyond end of file, etc.). |
| 200 | 0xC8 | ERROR_INVALID_AN | Preamble AN does not match the server’s stored AN for the (denom, SN). |
| 202 | 0xCA | ERROR_FILE_NOT_EXIST | For download: the requested (GUID, file_type) is not stored. |
| 250 | 0xFA | STATUS_SUCCESS | Command completed successfully. |
| 254 | 0xFE | ERROR_MEMORY_ALLOC | Server allocation failure. |
Reserved bytes available for protocol extension
The current QMail wire structures contain the following reserved fields. Each is currently zero-filled by the sender and ignored by the server. They are catalogued here so future protocol extensions know which slots are available without breaking the existing layouts.
| Structure | Field | Bytes | Notes |
|---|---|---|---|
| Universal preamble | byte 31 (was Device ID) | 1 | Per-request, all six active commands. Server reads but ignores. |
tell routing header (qmail_tell_req_t) | reserved_1[4] at offset 20–23 | 4 | Sits between total_file_size and client_timestamp. |
| tell routing header | reserved_2[1] at offset 47 | 1 | Tail of the 48-byte routing header. |
tell recipient entry (qmail_address_entry_t) | reserved[8] at offset 24–31 | 8 per recipient | One entry per recipient (To/CC/BCC). Multiplies with recipient count. |
tell file header (qmail_file_header_t) | reserved[5] at offset 59–63 | 5 per email | Tail of the manifest header. Bytes 57 (edit_sequence) and 58 (parity_algo) of the same region used to be reserved and now carry defined meanings. Pass-through — the recipient reads these bytes verbatim through tell → ping → download. |
| tell file manifest entry | reserved[2] at entry offset 2–3 | 2 per file | One per manifest entry (private meta + body + N attachments). Pass-through, sits between file_flags and original_size. |
tell file header (qmail_file_header_t) | manifest_flags bits 2–7 at offset 56 | 6 bits per email | Bits 0 (footer_removed) and 1 (crc32_present) are defined. Bits 2–7 are available for future flags. |
download request (qmail_download_req_t) | bytes_per_page at offset 32 | 1 | Server hard-codes 256 KB pages and ignores this byte. |
ping/peek response array header (qmail_response_array_header_t) | reserved[5] at offset 3–7 | 5 | Sits between total_tells and the first 64-byte file-header that follows. |
Largest contiguous pass-through region today: the 8 bytes per recipient in qmail_address_entry_t.reserved[8], plus the per-email 5-byte tail of the manifest header (file_header.reserved[59..63]). The address-entry reserved bytes are beacon-local (the beacon validates the address record); the manifest-header tail is pass-through and reaches the recipient verbatim.
Defined fields formerly listed as reserved. File-header bytes 57 (edit_sequence) and 58 (parity_algo) used to be part of the manifest-header reserved tail. They now carry sender-controlled meanings — see the tell page for details.
Legacy footer migration note. Pre-manifest .tell files on disk include an 18-byte recipient footer (tag 0x50, length 16, recipient locker). Current manifest v1 records have no footer. Implementations may strip the legacy footer when migrating pre-manifest .tell files; new code should not emit, parse, or expect a footer on the wire.