QMail Tell — Group 6, Code 71

Quick reference

Purpose

After uploading the stripes, the sender calls tell on each recipient’s beacon RAIDA. The tell is a public delivery envelope: a 64-byte file header, M 32-byte server-location entries, and a file manifest. The server-location entries tell the recipient which RAIDAs hold the stripes; the manifest tells the recipient which stored files exist and the original byte size of each file. The beacon writes the record to the recipient’s inbox directory; when the recipient’s ping or peek arrives, the beacon reads back the record and returns it.

The sender pays a per-recipient inbox fee by attaching a funded locker key to each address entry. The same funded inbox-fee locker is also copied into the routing header's beacon_payment_locker field so the beacon can validate the fee before accepting the delivery and pass the locker code on to the recipient.

Request body

Preamble (48)                             universal QMail preamble
Routing header (48)                       qmail_tell_req_t
R × Address entry (32 each)             qmail_address_entry_t
File header (64)                          qmail_file_header_t (start of blob)
M × Server location (32 each)           pass-through storage server map
F × File manifest entry (16 each)        pass-through file list (manifest v1)
Terminator (2)                            3E 3E

Server validates: body_size == 48 + 48 + R×32 + 64 + M×32 + manifest_len + 2. Here R is the recipient count, M is the storage-server count, and F is the file count in the manifest. This is the layout for an email tell (tell_type 0); a payment tell (tell_type 3) uses the same first three sections but carries no server locations and no manifest.

The sections below are in wire order, starting from byte 0.

Preamble (48 bytes, offsets 0–47)

The standard QMail preamble — the first 48 bytes of every QMail request. It carries the sender’s address coin (denomination, serial number) and this RAIDA’s 16-byte AN, which authenticates the sender; the whole request is AES-128 encrypted under that AN. See QMail Overview — Universal preamble for the byte-level breakdown.

Routing header (48 bytes, offsets 48–95)

Layout matches qmail_tell_req_t:

Address entries (N × 32 bytes)

Layout per recipient matches qmail_address_entry_t. The server iterates the N entries and writes one .tell file to each recipient’s inbox. Offsets below are relative to the start of each entry.

Notification blob (64 + M × 32 + manifest_len bytes)

The blob is the pass-through payload — the beacon stores it verbatim and the recipient reads it back through ping/peek. For current manifest v1 records, the first 64 bytes are the file header (qmail_file_header_t), followed by M 32-byte server-location entries and then F 16-byte file manifest entries. There is no trailing recipient footer in manifest v1 records; the manifest entries are the last bytes of the blob.

Two of the manifest-header bytes carry sender-controlled metadata that the beacon also acts on:

• edit_sequence (file-header offset 57) is a monotonic byte set by the sender. The beacon stores the blob verbatim, but on duplicate-GUID delivery it first reads byte 57 of any existing .tell in the recipient’s inbox and rejects the new tell when incoming < existing. Senders revising a previously-sent email bump edit_sequence; replayed older tells are dropped. 0 = original, 1+ = edits. LEGACY manifest-version-0 senders are treated as 0 by definition.
• parity_algo (file-header offset 58) names the fault-tolerance algorithm the sender used to stripe the email. 0 = RAID-5 XOR (1 parity stripe). Reserved for future Reed-Solomon / GF(2^8) IDs. The beacon uses this to compute its body-size estimate for total_file_size validation; unknown algorithms skip the size check.

File header (64 bytes)

The two bytes ES (edit_sequence, offset 57) and PA (parity_algo, offset 58) are the sender-controlled extension fields introduced by PR 2. ES drives the beacon's "newer edit wins" guard on duplicate-GUID delivery; PA selects the fault-tolerance algorithm the sender used and gates the beacon's total_file_size sanity check. See the offset 57 and offset 58 rows in the table below for the semantics. Field-key for the diagram: DN=denomination, DV=sender_device_id, TT=tell_type, SC=stripe_count, VR=version, MV=manifest_version, FC=file_count, FES=file_entry_size, MFL=manifest_flags, tfs=total_file_size.

Server location entries (32 bytes each)

The 32-byte format is partially structured (the recipient’s ping parser reads the first three bytes), partially opaque. The rest_core sender writes:

File manifest entries (N × 16 bytes)

The manifest is the authoritative public object list for this email. New QMail beta senders list the private CBDF meta object first with file_type=0x00, the body/content object second with file_type=0x01, and attachments afterward using sequential file types 0x0A, 0x0B, and so on. The receiver downloads file_type=0 first, parses private subject/filename/display metadata locally, and then downloads the body and attachments described by that private meta. The server validates manifest structure but does not read or interpret private CBDF keys.

Object-stored mail uses this same manifest. Senders that store files through Object Transfer (commands 76–84) upload every file under object_id = the email GUID at generation 1, so the receiver derives the full object key from the tell itself: object_id from the routing header, file_type and original_size from the manifest entry. The receiver fetches via object-info/get-range (cmd 81/82), falls back to the legacy striped pages when the object does not exist, and verifies the reconstructed file against the entry’s sender-authored CRC32. No richer manifest entry is needed or permitted on the wire.

Payment tells (tell_type 3)

A payment tell transfers CloudCoins instead of announcing mail. The sender funds a locker with the payment, then sends a tell whose locker_code is the locker key. The recipient’s client recognizes tell_type 3, skips the download flow, and automatically claims the locker into its wallet, recording the sender, timestamp, and purpose code in its transaction log. Nothing is displayed as a message.

There is deliberately no memo field. The only sender-chosen content is one payment_purpose byte. This is what keeps the tell system from becoming a free messaging channel: anyone who wants to say something sends an email tell and pays the inbox fee; a payment tell can only say “here is money, for this standard reason.”

Body layout (exactly 194 bytes)

Preamble (48)                 unchanged — AES-128 + AN authentication as always
Routing header (48)           tell_type=3, address_count=1, server_count=0,
                              beacon_payment_locker = zero
Address entry (32, one only)  recipient mailbox; locker_payment_key = payment locker key
File header (64)              tell_type=3, stripe_count=0, locker_code = payment locker key,
                              total_file_size=0, version=0x02, bytes 51-58 zero,
                              byte 59 = payment_purpose, bytes 60-63 zero
Terminator (2)                3E 3E

Server validates: body_size == 48 + 48 + 32 + 64 + 2 == 194. Exactly one recipient per payment tell — paying N people means funding N lockers and sending N tells. Every fixed byte of the layout is enforced: the routing header’s beacon_payment_locker and reserved bytes must be zero, the address entry must be type To with coin ID 00 06 and zero reserved bytes, the file-header version must be 0x02, and the routing and file-header email_id GUIDs must match (the GUID is the payment ID and drives the same duplicate-delivery protection). Sender authentication applies exactly as for email tells, and both the routing-header and file-header timestamps must be within ±60 seconds.

payment_purpose codes (file header byte 59)

The beacon passes the byte through without validating it; recipients display unknown codes as “Other”. New codes are allocated on this page.

Payment gate

Instead of the email inbox-fee gate, a payment tell passes this per-recipient gate:

1. Blacklist — applies exactly as for email tells (ERROR_SENDER_BLACKLISTED).
2. Class rejection — skipped. A funded payment supersedes the sender-class filter.
3. Locker verification — mandatory, even for whitelisted senders. Payment tells are exempt from the recipient’s inbox fee — they carry no message, so there is nothing to charge attention for. Instead the beacon peeks the supplied locker and requires its value to meet the flat minimum payment of 5000 CC. A zero locker key → ERROR_PAYMENT_REQUIRED; a locker below 5000 CC (including empty or nonexistent) → ERROR_PAYMENT_INSUFFICIENT; a temporary verification-backend failure → ERROR_PAYMENT_PROCESSING (sender keeps the tell queued and retries). The client also rejects below-minimum amounts locally before funding a locker.

The 5000 CC floor is the anti-abuse economics: with no memo field, the only nuisance a payment tell could create is dust-value notifications cluttering the transaction log — the minimum makes every unwanted payment tell deliver a substantial amount to its “victim.” The primary use case is subscription payouts: a webserver holding subscriber mailbox addresses sends each member their coins monthly with purpose 0x00, and each member’s client claims automatically. Unlike the email-tell fee path, locker verification for payment tells is not stubbed and not waivable.

Delivery and claim

Accepted payment tells are written to the recipient’s inbox and served by ping/peek exactly like email tells — the pass-through record is just the 64-byte file header. The recipient’s beacon loop then claims the locker (13-of-25 consensus download), deposits the coins into the wallet, and records the transaction. The sender can confirm pickup at any time by peeking the locker: an empty locker means the payment was claimed. No receipt protocol is needed.

Local REST test calls

These calls are for a two-client local test setup where client1 is the sender on port 8081 and client2 is the receiver on port 8082.

# Confirm both local identities
GET http://127.0.0.1:8081/api/qmail/local/identity/whoami
GET http://127.0.0.1:8082/api/qmail/local/identity/whoami

# Optional: stop receiver background beacon so manual peek/ping can consume the Tell deterministically
GET http://127.0.0.1:8082/api/qmail/local/beacon/control?action=stop

# Sender uploads body + one attachment and sends Tell to the receiver
GET http://127.0.0.1:8081/api/qmail/net/messages/upload_and_tell?to=<CLIENT2_QMAIL_ADDRESS>&subject=ManifestTest&body=Hello%20from%20client1&attachment_file_path=C%3A%5Ctmp%5Catt1.txt

# Poll the async task returned by upload_and_tell
GET http://127.0.0.1:8081/api/system/tasks?task_id=<TASK_ID>

# Inspect sender receipt after the task returns file_guid
GET http://127.0.0.1:8081/api/qmail/receipts?guid=<FILE_GUID>

# Receiver consumes the Tell and sees manifest_version/file_count/files[] in JSON
GET http://127.0.0.1:8082/api/qmail/net/beacon/peek?since=0

# Receiver downloads the body and all manifest-listed attachments
GET http://127.0.0.1:8082/api/qmail/net/messages/download?file_guid=<FILE_GUID>

# Confirm downloaded attachment rows and file_type values
GET http://127.0.0.1:8082/api/qmail/db/attachments/list?email_id=<FILE_GUID>
GET http://127.0.0.1:8082/api/qmail/db/attachments/get?email_id=<FILE_GUID>&attachment_id=<ATTACHMENT_ID>&info=1

Response

No body. Status only.

DRD white/black list & inbox-fee gate

Before writing to each recipient’s inbox, the beacon consults its DRD (Group 16) data. The sender’s identity is the AN-authenticated preamble coin, so it cannot be spoofed. Per recipient, in order:

1. Blacklist — if the recipient’s list has the sender as black (list_type 0x01), the recipient is skipped. If nothing delivers, the Tell returns ERROR_SENDER_BLACKLISTED (236).
2. Whitelist — a whitelisted sender (list_type 0x00) delivers free: no locker code, no fee, and no class-rejection check.
3. Class rejection — if the recipient’s DRD record sets a nonzero class-rejection byte, senders whose address denomination is below it are refused with ERROR_SENDER_CLASS_REJECTED (237) — paying more does not help; only a higher-denomination address or a whitelist entry does. The byte is signed denomination encoding (0xFF = −1 = 0.1 CC, which ranks below 0x00 = 1 CC).
4. Inbox fee — for everyone else, the fee is the recipient’s DRD record fee. A recipient with no DRD record is charged the beacon’s default Tell fee (10 CC, configurable per server in config.toml [drd] and toggleable off) so that spammers cannot sweep guessed serial numbers with free Tells. A DRD record with an explicit fee of 0 means a deliberately free inbox.
5. Locker — when a fee is due the sender must supply a locker code (the per-recipient locker_payment_key, falling back to the routing header’s beacon_payment_locker). Missing locker → ERROR_PAYMENT_REQUIRED (169). The locker-value comparison against the fee is currently stubbed to accept any supplied locker; when Phase 2 lands, an underfunded locker returns ERROR_PAYMENT_INSUFFICIENT (168).

With multiple recipients, allowed recipients still deliver and the Tell returns 250. Only when zero recipients deliver does the most specific failure win: blacklisted > class rejected > insufficient > payment required > ERROR_WRONG_RAIDA.

Payment tells use a different gate. For tell_type 3 only the blacklist step above applies; the class-rejection and inbox-fee steps are replaced by mandatory locker verification — see Payment tells — Payment gate.

Status codes

Server-side delivery

For each accepted recipient the server writes:

Path: /opt/raidax/QMail_Data/mailboxes/{denom_hex}/{sn}/inbox/00000000{GUID_hex}.tell

Body: pass-through Tell record
      64-byte file header
      M×32 server entries
      N×16 file manifest entries

Migration note: pre-manifest .tell files on disk include an 18-byte recipient
footer (tag=0x50, length=16, recipient_locker). Implementations may strip that
footer when migrating older files. Current manifest v1 records have no footer.

Writes use atomic publish: open a hidden tempfile (.tmp.PID.TIME.SEQ.GUID.tell; payment tells use the disjoint prefix .tmpp.) with O_CREAT|O_EXCL, write, fsync, and rename() into the final .tell path. The recipient’s long-poll inotify watch fires on IN_MOVED_TO only after the rename, guaranteeing the watcher never sees a partial file. Any .tmp.* orphan from a crashed sender is ignored by the directory scanner because the dotfile prefix.

Before each per-recipient write, the beacon checks for an existing .tell at the target path. If one exists and its edit_sequence (byte 57) is greater than the incoming blob’s, the recipient is skipped (the older revision is not allowed to clobber the newer one). Equal-or-greater edit_sequence values overwrite, matching the documented idempotent re-send / edit semantics.

After delivery, when the recipient’s ping or peek reads the file into the response, the server remove()s the file. Tells are one-shot; once read they are gone.

Common mistakes

Points of confusion

1. The server doesn’t verify file existence. tell just writes the notification blob to the recipient’s inbox; it does not contact the storage RAIDAs to confirm the stripes are actually there. If you call tell before upload finishes, the recipient will be told about a file they cannot download.
2. Inbox-fee lookup failure is retryable, not free. A definite no-fee result means an authoritative zero-fee response (for example success:true with inbox_fee:0) or an explicitly documented server-side mapping such as contact-not-found to fee=0. Do not treat success:false, an error envelope, a missing success field, bad JSON, or no response as free. If the beacon cannot determine the recipient’s inbox fee because rest_core or another payment dependency failed, the beacon returns ERROR_PAYMENT_PROCESSING (167) so the client keeps the Tell queued for retry.
3. stripe_type is not attachment identity. It remains 0=data or 1=parity. Attachment identity belongs in the file manifest’s file_type field.
4. Atomic-publish is recent. Older raidax builds wrote the .tell file in place. The current build uses temp+rename so the inotify watcher never sees a partial file. Senders see no behavior change; recipients see a smaller race window.
5. Multiple reserved regions. Three structures in this command have reserved bytes: reserved_1[4] + reserved_2[1] in the routing header (beacon-local), reserved[8] per recipient address entry (beacon-local), and reserved[5] at offsets 59–63 of the file header (pass-through). Per-file reserved[2] in each manifest entry is also pass-through but only 2 bytes wide. Bytes 57 (edit_sequence) and 58 (parity_algo) of the file header used to be reserved; they now carry defined meanings.