Email Parsing

When an email arrives on your inbound domain, it is received and parsed by SparkPost, the mail infrastructure behind Lettr’s inbound servers, and posted to your forwarding URL as JSON. This page explains every field in that payload and how to read the parts of the email that are not broken out into fields, such as attachments.

Payload Structure

Inbound emails are posted to your inbound domain’s forwarding URL as a JSON array of events. Each event contains a relay message with the email’s content:

[
  {
    "msys": {
      "relay_message": {
        "msg_from": "sender@example.com",
        "friendly_from": "John Doe <sender@example.com>",
        "rcpt_to": "support@mail.example.com",
        "customer_id": "1234",
        "webhook_id": "4839201967643219",
        "content": {
          "subject": "Question about my order",
          "text": "Plain text content of the email...",
          "html": "<html><body><p>HTML content...</p></body></html>",
          "to": ["support@mail.example.com"],
          "cc": ["team@mail.example.com"],
          "headers": [
            { "From": "John Doe <sender@example.com>" },
            { "To": "support@mail.example.com" },
            { "Cc": "team@mail.example.com" },
            { "Subject": "Question about my order" },
            { "Date": "Mon, 15 Jan 2024 10:30:00 +0000" },
            { "Message-ID": "<unique-id@example.com>" },
            { "In-Reply-To": "<previous-id@example.com>" },
            { "References": "<original-id@example.com> <previous-id@example.com>" },
            { "Content-Type": "multipart/mixed; boundary=\"abc123\"" }
          ],
          "email_rfc822": "...raw RFC 822 MIME message...",
          "email_rfc822_is_base64": false
        }
      }
    }
  }
]

Payloads are always a JSON array of events. A single delivery may contain one or more events, so loop over the array instead of reading only the first item.

Field Reference

Field	Type	Description
`msg_from`	string	Envelope sender (SMTP `MAIL FROM`)
`friendly_from`	string	Display name and address from the `From` header
`rcpt_to`	string	Envelope recipient, the address on your inbound domain that received the email
`customer_id`	string	Internal account identifier on the mail infrastructure. You can ignore it
`webhook_id`	string	Identifier of the relay webhook that delivered the message
`content.subject`	string	Subject line
`content.text`	string	Plain text body. Absent when the email has no text part
`content.html`	string	HTML body. Absent when the email has no HTML part
`content.to`	array	Addresses from the `To` header
`content.cc`	array	Addresses from the `Cc` header, when present
`content.headers`	array	The email’s headers, each as an object with a single key
`content.email_rfc822`	string	The complete raw MIME message, including attachments and inline images
`content.email_rfc822_is_base64`	boolean	When `true`, `email_rfc822` is base64-encoded and must be decoded before parsing

There is no attachments field. Attachments are only available inside email_rfc822. See Raw MIME Parsing and Attachments.

Reading the Payload

app.post('/webhooks/inbound', express.json({ limit: '50mb' }), async (req, res) => {
  for (const event of req.body) {
    const relay = event.msys?.relay_message;
    if (!relay) continue;

    console.log(relay.rcpt_to, relay.friendly_from, relay.content.subject);
  }

  res.sendStatus(200);
});

The examples on the rest of this page assume relay is one event.msys.relay_message object.

Sender Information

From Address

The relay message provides two sender fields:

msg_from: the envelope sender (SMTP MAIL FROM). For mailing lists and bulk senders this is often a bounce address, not the person who wrote the email.
friendly_from: the display name and address from the From header. This is usually the address you want to show or reply to.

console.log(relay.msg_from);      // "sender@example.com"
console.log(relay.friendly_from); // "John Doe <sender@example.com>"

To extract just the email address or display name from friendly_from:

function parseFriendlyFrom(friendlyFrom) {
  const match = friendlyFrom.match(/^(.+?)\s*<([^>]+)>$/);
  if (match) {
    return { name: match[1].trim().replace(/^"|"$/g, ''), email: match[2] };
  }
  return { name: null, email: friendlyFrom };
}

Reply-To Address

The Reply-To address is in the content.headers array, when the sender set one (getHeader is defined under Email Headers):

const replyTo = getHeader(relay.content.headers, 'Reply-To');
const replyAddress = replyTo || parseFriendlyFrom(relay.friendly_from).email;

Recipients

The relay message provides:

rcpt_to: the envelope recipient, the address on your inbound domain that received the email
content.to: the addresses from the To header
content.cc: the addresses from the Cc header, when there are any

// Envelope recipient (your inbound address)
const recipient = relay.rcpt_to; // "support@mail.example.com"

// Header recipients
const toAddresses = relay.content.to ?? []; // ["support@mail.example.com"]
const ccAddresses = relay.content.cc ?? []; // ["team@mail.example.com"]

Use rcpt_to to decide which of your addresses the email was meant for. It can differ from the To header, for example when your address was in Bcc or the email was forwarded.

BCC recipients are not visible in received emails. If your address was BCC’d, it appears only in rcpt_to.

Subject Line

The subject is in content.subject:

const subject = relay.content.subject || '(No Subject)';

The original header is also in content.headers under Subject.

Email Body

Plain Text and HTML

Emails can contain plain text, HTML, or both. The bodies are in content.text and content.html, and either one can be missing:

const { text, html } = relay.content;

// Use HTML if available, fall back to plain text
const displayContent = html || `<pre>${escapeHtml(text ?? '')}</pre>`;

// Or prefer plain text for processing
const processableContent = text || stripHtml(html ?? '');

Extracting Text from HTML

import { convert } from 'html-to-text';

function getPlainText(content) {
  if (content.text) {
    return content.text;
  }

  if (content.html) {
    return convert(content.html, {
      wordwrap: 130,
      selectors: [
        { selector: 'a', options: { ignoreHref: true } },
        { selector: 'img', format: 'skip' }
      ]
    });
  }

  return '';
}

const plainText = getPlainText(relay.content);

Handling Quoted Content

Strip quoted replies to get just the new content:

function stripQuotedContent(text) {
  const lines = text.split('\n');
  const newContent = [];

  for (const line of lines) {
    // Stop at common quote markers
    if (line.match(/^>/) ||
        line.match(/^On .+ wrote:/) ||
        line.match(/^-{3,}.*Original Message.*-{3,}/i) ||
        line.match(/^From:.*@/)) {
      break;
    }
    newContent.push(line);
  }

  return newContent.join('\n').trim();
}

const newReplyContent = stripQuotedContent(getPlainText(relay.content));

Email Headers

Standard Headers

Headers are in content.headers as an array of objects, each with a single key (the header name) and a string value. A header that appears several times in the email, such as Received, appears several times in the array. Which headers are present depends on the sender. Common ones:

Header	Description
`Message-ID`	Unique identifier for this email
`Date`	When the email was sent
`In-Reply-To`	Message-ID of the email being replied to
`References`	Chain of Message-IDs in the conversation
`Reply-To`	Address the sender wants replies sent to
`Content-Type`	MIME type of the email
`X-Mailer`	Email client used to send
`X-Priority`	Email priority (1=High, 3=Normal, 5=Low)

Header names keep the capitalization the sender used (Message-ID, Message-Id), so look them up case-insensitively:

const { headers } = relay.content;

// Returns the first value of a header, or null
function getHeader(headers, name) {
  const wanted = name.toLowerCase();

  for (const header of headers) {
    const [key, value] = Object.entries(header)[0];
    if (key.toLowerCase() === wanted) return value;
  }

  return null;
}

// Get the message thread
const messageId = getHeader(headers, 'Message-ID');
const inReplyTo = getHeader(headers, 'In-Reply-To');
const references = getHeader(headers, 'References')?.split(/\s+/) || [];

// Check priority
const priority = getHeader(headers, 'X-Priority');
const isHighPriority = priority?.startsWith('1') || priority?.startsWith('2');

Message-ID is also the right key for deduplication: the same email can be delivered to your endpoint more than once, so store the Message-IDs you have processed and skip repeats.

Custom Headers

Access any header using the helper:

// Custom headers set by the sender
const customHeader = getHeader(headers, 'X-Custom-Header');
const mailingList = getHeader(headers, 'List-Id');
const unsubscribeUrl = getHeader(headers, 'List-Unsubscribe');

Date and Time

Sent Timestamp

The original send time is in the Date header:

const dateHeader = getHeader(relay.content.headers, 'Date');
const sentAt = dateHeader ? new Date(dateHeader) : null;

The Date header is set by the sender’s client and can be missing or wrong. Record your own received time as well.

Character Encoding

content.subject, content.text and content.html are JSON strings, so you read them as ordinary Unicode text. If you need exact control over how a part’s declared charset is decoded, parse email_rfc822 with a MIME library, which reads each part’s charset and Content-Transfer-Encoding itself.

Multipart Emails

Most emails are multipart: a plain text version, an HTML version, and possibly attachments and inline images. The payload breaks out only the bodies:

// A multipart email:
// - text/plain part → relay.content.text
// - text/html part  → relay.content.html
// - everything, including attachments and inline images → relay.content.email_rfc822

const hasBothVersions = Boolean(relay.content.html && relay.content.text);

Attachments and inline images are not extracted into separate fields. To get them, parse email_rfc822.

Raw MIME Parsing

content.email_rfc822 holds the complete raw message. Parse it with a MIME library when you need attachments, inline images, or MIME structure that the structured fields don’t cover. When content.email_rfc822_is_base64 is true, base64-decode the field first.

import { simpleParser } from 'mailparser';

export function parseRawEmail(relay) {
  const { email_rfc822, email_rfc822_is_base64 } = relay.content;

  const raw = email_rfc822_is_base64
    ? Buffer.from(email_rfc822, 'base64')
    : email_rfc822;

  return simpleParser(raw);
}

const parsed = await parseRawEmail(relay);

parsed.from?.value;   // [{ address, name }]
parsed.to?.value;
parsed.subject;
parsed.messageId;
parsed.text;
parsed.html;
parsed.attachments;   // includes inline images (cid, related: true)

import base64
from email import message_from_bytes, policy


def parse_raw_email(relay):
    content = relay["content"]
    raw = content["email_rfc822"]

    if content.get("email_rfc822_is_base64"):
        raw_bytes = base64.b64decode(raw)
    else:
        raw_bytes = raw.encode("utf-8")

    return message_from_bytes(raw_bytes, policy=policy.default)


message = parse_raw_email(relay)

message["From"]
message["Subject"]
message["Message-ID"]
body = message.get_body(preferencelist=("plain", "html"))
attachments = list(message.iter_attachments())

<?php

use ZBateson\MailMimeParser\Message;

function parseRawEmail(array $relay): Message
{
    $content = $relay['content'];
    $raw = $content['email_rfc822'];

    if (!empty($content['email_rfc822_is_base64'])) {
        $raw = base64_decode($raw);
    }

    return Message::from($raw, false);
}

$message = parseRawEmail($relay);

$message->getHeaderValue('From');
$message->getSubject();
$message->getHeaderValue('Message-ID');
$message->getTextContent();
$message->getHtmlContent();
$message->getAllAttachmentParts(); // includes inline images

See Attachments for extracting, validating and storing files.

Parsing Examples

Extract Email Signature

function extractSignature(text) {
  // Common signature delimiters
  const delimiters = [
    /^--\s*$/m,           // Standard delimiter
    /^_{3,}$/m,           // Underscores
    /^-{3,}$/m,           // Dashes
    /^Sent from my /m,    // Mobile signatures
    /^Get Outlook for /m  // Outlook mobile
  ];

  let signatureStart = text.length;

  for (const delimiter of delimiters) {
    const match = text.match(delimiter);
    if (match && match.index < signatureStart) {
      signatureStart = match.index;
    }
  }

  return {
    body: text.substring(0, signatureStart).trim(),
    signature: text.substring(signatureStart).trim()
  };
}

const { body, signature } = extractSignature(relay.content.text ?? '');

Detect Email Client

function detectEmailClient(headers) {
  const mailer = getHeader(headers, 'X-Mailer') || getHeader(headers, 'User-Agent') || '';

  if (mailer.includes('Microsoft Outlook')) return 'Outlook';
  if (mailer.includes('Apple Mail')) return 'Apple Mail';
  if (mailer.includes('Thunderbird')) return 'Thunderbird';

  return 'Unknown';
}

Parse Structured Data

// Extract order number from confirmation emails
function extractOrderNumber(content) {
  const body = content.text || content.html || '';

  const patterns = [
    /order\s*#?\s*:?\s*([A-Z0-9-]+)/i,
    /order\s+number\s*:?\s*([A-Z0-9-]+)/i,
    /confirmation\s*#?\s*:?\s*([A-Z0-9-]+)/i
  ];

  for (const pattern of patterns) {
    const match = body.match(pattern);
    if (match) return match[1];
  }

  return null;
}

const orderNumber = extractOrderNumber(relay.content);

Handling Edge Cases

Empty Content

function getEmailContent(content) {
  const text = content.text?.trim();
  const html = content.html?.trim();

  if (!text && !html) {
    return {
      hasContent: false,
      content: '',
      contentType: 'none'
    };
  }

  return {
    hasContent: true,
    content: text || stripHtml(html),
    contentType: text ? 'text' : 'html'
  };
}

An email with an empty body can still carry attachments, so check email_rfc822 before discarding it.

Malformed Addresses

function parseEmailAddress(address) {
  if (!address) return null;

  // Handle various formats
  const match = address.match(/<([^>]+)>/) || // "Name <email>"
                address.match(/([^\s<>]+@[^\s<>]+)/); // bare email

  return match ? match[1].toLowerCase() : null;
}

Inbound Setup

Create an inbound domain and forwarding URL

Attachments

Extract files from the raw message

Reply Tracking

Track conversation threads

Routing

Route emails based on content

Documentation

Quickstart

Learn

Integrations

Resources

Email Parsing

Payload Structure

Field Reference

Reading the Payload

Sender Information

From Address

Reply-To Address

Recipients

Subject Line

Email Body

Plain Text and HTML

Extracting Text from HTML

Handling Quoted Content

Email Headers

Standard Headers

Custom Headers

Date and Time

Sent Timestamp

Character Encoding

Multipart Emails

Raw MIME Parsing

Parsing Examples

Extract Email Signature

Detect Email Client

Parse Structured Data

Handling Edge Cases

Empty Content

Malformed Addresses

Inbound Setup

Attachments

Reply Tracking

Routing

Payload Structure

Field Reference

Reading the Payload

Sender Information

From Address

Reply-To Address

Recipients

Subject Line

Email Body

Plain Text and HTML

Extracting Text from HTML

Handling Quoted Content

Email Headers

Standard Headers

Custom Headers

Date and Time

Sent Timestamp

Character Encoding

Multipart Emails

Raw MIME Parsing

Parsing Examples

Extract Email Signature

Detect Email Client

Parse Structured Data

Handling Edge Cases

Empty Content

Malformed Addresses

Related Topics

Inbound Setup

Attachments

Reply Tracking

Routing