Use parsed email fields and raw MIME for different jobs

Use structured fields for ordinary work

For classification and summarization, start with the message API’s text, preview, extracted_text, headers and attachment metadata. These fields let you select relevant information without asking a language model to parse transfer encodings or multipart boundaries. Retain the message_id and source inbox with every extracted fact. The convenient representation is still a transformation of a received message, so it should not be presented as an exact archive of every byte. When a question turns on original headers or a damaged body part, switch to the raw-source path deliberately.

Retrieve the raw message explicitly

GET /v0/emails/inboxes/:inbox_id/emails/:email_id/raw returns RFC822-style source with content type message/rfc822. Save those bytes as a private artifact and use a real mail parser to inspect them. Avoid applying the JSON-response helper used for ordinary API endpoints. A successful raw fetch does not require rendering the message as HTML in your operator interface. Show a text view or parsed structure with escaped content, and do not load remote images automatically. That keeps diagnostic inspection from quietly contacting sender-controlled infrastructure.

Understand multipart and encoding layers

MIME describes content types and transfer encodings; a multipart message can contain alternatives, nested multiparts and attachments. Decode transfer encoding and character sets with a maintained library rather than handwritten string splitting. Do not concatenate every text-bearing part into one prompt: the HTML and plain-text alternatives often repeat the same message. Preserve parser warnings and note when a part could not be decoded. The useful result is a small, attributable representation of the message, with opaque binary parts left outside model context unless a task specifically requires them.

Keep header claims in their lane

Message headers carry useful routing and threading information, but sender-controlled fields are not application authorization. Display names, subjects and arbitrary X- headers cannot prove a workspace role. Even an authenticated sender can send malicious instructions or incorrect facts. Use authentication results and your application’s trusted account mapping for policy decisions, then keep the received header values as evidence. If the parsed representation and raw source appear inconsistent, retain both and investigate the parser or ingestion path. Do not resolve the discrepancy by letting the model invent missing text.

Create fixtures for actual failure cases

A good MIME fixture suite includes multipart alternative, non-UTF-8 text, quoted-printable content, a base64 attachment, a folded header and a malformed boundary. Assert the extracted text, attachment count and error behavior rather than only that parsing did not crash. Keep synthetic addresses and harmless bytes in fixtures, and redact real messages before sharing diagnostic samples. The next step is to choose one parser boundary in your application, record its version and make its output explicit. Raw retrieval should remain available for targeted troubleshooting, while ordinary agent jobs consume bounded structured fields.

Preserve raw bytes when exactness matters

For a transport dispute or parser regression, store the raw-source artifact and its checksum in private diagnostic storage with a bounded retention window. A reconstructed message made from parsed headers and text is not byte-identical evidence. Keep the transformed model input separately so an investigator can compare what arrived with what the agent actually consumed.

Sources & verification

Reviewed against checked-in Lupin API handlers and documentation. Example requests were not executed against live providers.

• Lupin messages and raw source ↗Checked 2026-11-05
• RFC 2045 MIME ↗Checked 2026-11-05
• RFC 5322 Internet Message Format ↗Checked 2026-11-05

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.