Message source

Every message in Nextmail can be downloaded as its source: one message/rfc822 file with the headers and the MIME body, the file a mail app saves as .eml or shows under Show original. Each download says which of two sources it is.

Keep original is a setting of one address, off until somebody turns it on. While it is on, every message the address receives is also stored exactly as it arrived, sealed like an attachment, and its download answers original. Turning it off stops keeping new messages and leaves the ones already kept where they are.

• —An original belongs to its message. It is deleted when the conversation is deleted for good and when the workspace is deleted, and it moves with its conversation when a domain moves to another workspace.
• —Removing an address keeps its conversations, and with them their originals, until they are deleted.
• —Each address keeps its own copy, so a message sent to two addresses that keep originals is stored twice.
• —If an original cannot be stored, the message is still filed as usual and its download answers rebuilt.

• —In the web app, Keep original messages is a switch on the Delivery tab of the address page. In the phone app, the same switch is on the Delivery tab of the address screen.
• —Over REST, keepOriginal on POST /domains/{id}/addresses and PATCH /domains/{id}/addresses/{addressId}, and every address reports it.
• —In the SDKs, keepOriginal on domains.createAddress and domains.updateAddress, written the way each language writes names.
• —On the command line, nextmail domains update-address <domain-id> <address-id> --keep-original.
• —Over MCP and in the assistant, keepOriginal on addDomainAddress and updateDomainAddress.

GET /threads/{id}/messages/{messageId}/raw answers the file, named after the message id, with Content-Type: message/rfc822 and the source in the X-Message-Source header. It needs threads:read, and the thread is checked first and then the message, exactly as GET /threads/{id}/messages/{messageId} does, so a key limited to some addresses only reaches the mail that arrived at them. The emailId of an email.received webhook is the message id to pass, beside its threadId.

• —In the web app, open the conversation and choose Download original in the More menu of the message, the three dots beside it. The phone app has no Download original.
• —In the SDKs, threads.getRawMessage(threadId, messageId) returns the bytes, as a Uint8Array in TypeScript and the byte type of each other language.
• —On the command line, nextmail threads get-raw-message <thread-id> <message-id> --out message.eml writes the file, and without --out the bytes go to a pipe.
• —Over MCP and in the assistant, getRawMessage returns the source as text, at most the first 256 KiB, with source and whether it was truncated. Without a message id it reads the latest message of the thread.

nextmail threads get-raw-message <thread-id> <message-id> --out message.eml

An endpoint with includeRaw on gets a link to the source in every email.received event, as data.raw. The link downloads the message with no key, and is worked out again for every attempt, so a retry or a replay always carries a fresh one and the delivery log never holds it. Turning includeRaw on needs threads:read, as includeContent does, and the two can be on together. In the web app it is the Include the raw message switch in the form of the endpoint, and in the phone app the same switch is on the webhook screen. The webhooks guide covers the rest of the payload.