Inbound Introduction

Lettr allows you to receive and process incoming emails programmatically. By configuring an inbound domain with a forwarding URL, your application can capture replies to transactional emails, process support requests, parse incoming data, and trigger automated workflows whenever an email arrives.

What You Can Build

Support Ticket Systems - Automatically create tickets from customer emails
Reply Tracking - Capture replies to your transactional emails and thread conversations
Email-to-Action Workflows - Trigger processes when specific emails arrive
Data Extraction - Parse structured data from incoming emails (orders, receipts, notifications)
Per-User Addresses - Give each user, record, or workflow its own address, since mail to any address at the domain is forwarded
Unsubscribe Processing - Handle unsubscribe requests via email

How It Works

Lettr’s inbound email processing follows a four-step flow. You configure DNS to route emails to Lettr’s mail servers, and Lettr posts each email to your application’s forwarding URL as JSON.

Build a Receiving Endpoint

Create an endpoint in your application that accepts POST requests and returns a 2xx status. This is your forwarding URL.

Configure Inbound Domain

Add an inbound domain in your Lettr dashboard with your forwarding URL, then configure MX records to route incoming emails to Lettr’s mail servers.

Receive and Process

When someone sends an email to any address on your inbound domain, Lettr posts it to your forwarding URL as JSON.

Build Your Logic

Route emails, extract data, trigger workflows, and respond programmatically.

Sender → MX Records → Lettr Inbound Servers → Forwarding URL (JSON POST) → Your Application

Lettr’s inbound servers handle SMTP reception and post each message to your forwarding URL. Your application receives JSON with the email’s sender, recipients, subject, body (plain text and HTML, when present), headers, and the complete raw MIME message. Attachments and inline images are only available inside that raw message. Lettr doesn’t score, filter, or store the messages it forwards: anything beyond delivery, such as spam checks, routing, or saving attachments, happens in your handler.

Quick Start

1. Add an Inbound Domain

Navigate to Domains → Inbound in your dashboard and click Create Inbound Domain. Enter your domain (e.g., mail.example.com), a Forwarding URL for your endpoint (e.g., https://yourapp.com/webhooks/inbound), and optionally an Auth token. The forwarding URL is required and is tested with a POST request before the domain is created. If your endpoint doesn’t answer with a 2xx status, the dashboard shows the status it returned and the domain is not created. See the Setup Guide for what to do when a firewall blocks the test.

Inbound domain management is available through the Lettr dashboard. There is no public API endpoint for creating or managing inbound domains.

2. Configure DNS

Add the provided MX records to your domain:

Type	Priority	Value
MX	10	`rx1.sparkpostmail.com`
MX	10	`rx2.sparkpostmail.com`
MX	10	`rx3.sparkpostmail.com`

Multiple MX records with equal priority provide load balancing: sending servers distribute email across all three servers. If one is unavailable, the others handle delivery. See the Setup Guide for DNS propagation details.

3. Handle Incoming Emails

Handle incoming emails at your forwarding URL:

import crypto from 'node:crypto';
import express from 'express';

const app = express();

app.post('/webhooks/inbound', (req, res, next) => {
  // Verify the auth token you set on the inbound domain
  const token = req.get('X-MessageSystems-Webhook-Token') ?? '';
  const expected = process.env.INBOUND_AUTH_TOKEN;

  if (
    token.length !== expected.length ||
    !crypto.timingSafeEqual(Buffer.from(token), Buffer.from(expected))
  ) {
    return res.sendStatus(401);
  }

  next();
}, express.json(), async (req, res) => {
  const events = req.body;

  for (const event of events) {
    const relayMessage = event.msys?.relay_message;
    if (!relayMessage) continue;

    const { msg_from, rcpt_to, content } = relayMessage;

    await processIncomingEmail({
      sender: msg_from,
      recipient: rcpt_to,
      subject: content.subject,
      body: content.text || content.html,
      headers: content.headers
    });
  }

  res.sendStatus(200);
});

Always verify the auth token before processing incoming emails to ensure requests are genuinely from Lettr. Set the token in the Auth token field when you create the inbound domain, or later on the domain’s Mail Forwarding card. Lettr sends it in the X-MessageSystems-Webhook-Token header.

Webhook Payload

When an email is received, Lettr posts it to your domain’s forwarding URL. The payload is a JSON array of event objects (one request can carry more than one email), each containing an msys.relay_message:

[
  {
    "msys": {
      "relay_message": {
        "msg_from": "sender@example.com",
        "rcpt_to": "support@mail.example.com",
        "friendly_from": "John Sender <sender@example.com>",
        "customer_id": "1234",
        "webhook_id": "4839201967643219",
        "content": {
          "html": "<p>HTML content of the email...</p>",
          "text": "Plain text content of the email...",
          "subject": "Help with my order",
          "headers": [
            { "Message-ID": "<abc123@example.com>" },
            { "Date": "Mon, 15 Jan 2024 10:30:00 +0000" },
            { "In-Reply-To": "<original@example.com>" }
          ],
          "to": ["support@mail.example.com"],
          "email_rfc822": "...raw MIME content...",
          "email_rfc822_is_base64": false
        }
      }
    }
  }
]

The payload was produced by SparkPost, the mail infrastructure behind Lettr’s inbound servers. Alongside the convenience fields (subject, text, html, headers), email_rfc822 holds the complete raw message, base64-encoded when email_rfc822_is_base64 is true. Either text or html can be missing, so handle both cases. There is no attachments array, spam score, or event ID in the payload. For a complete breakdown of each field, see Email Parsing.

Key Capabilities

Email Routing

Mail sent to any address at your inbound domain is forwarded to the same URL, so routing happens in your handler. Route incoming emails based on recipient, content, or your own rules:

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

    const recipient = relay.rcpt_to.toLowerCase();
    const { msg_from, content } = relay;

    if (recipient.startsWith('support@')) {
      await createSupportTicket({ from: msg_from, subject: content.subject, body: content.text });
    } else if (recipient.startsWith('sales@')) {
      await notifySalesTeam({ from: msg_from, subject: content.subject, body: content.text });
    } else if (recipient.match(/^reply\+/)) {
      const ticketId = recipient.match(/^reply\+([^@]+)@/)[1];
      await addReplyToTicket(ticketId, { from: msg_from, body: content.text });
    }
  }

  res.sendStatus(200);
});

The reply+ pattern above is called variable addressing (or plus addressing). It’s a common way to encode context in the recipient address so you can route replies back to the right record. See Routing for more patterns including routing by subject, sender domain, and content.

Spam Filtering

Lettr adds no spam score and doesn’t filter, quarantine, or drop inbound mail for you. Every message that reaches your inbound domain is forwarded. If you want spam handling, implement it in your handler, for example by checking authentication results when the receiving server added them, the sender’s domain, or a third-party filter:

// Headers arrive as an array of single-key objects
function getHeader(headers, name) {
  for (const header of headers ?? []) {
    for (const [key, value] of Object.entries(header)) {
      if (key.toLowerCase() === name.toLowerCase()) return value;
    }
  }
  return undefined;
}

function looksSuspicious(relay) {
  // Not every message carries this header, so treat a missing one as "unknown"
  const authResults = getHeader(relay.content.headers, 'Authentication-Results');
  return Boolean(authResults && /dmarc=fail/i.test(authResults));
}

See Spam Filtering for more patterns you can build in your handler.

Attachment Handling

Attachments aren’t sent as separate fields or URLs. They are inside the raw MIME message in content.email_rfc822, so parse it with a MIME library such as mailparser for Node.js:

import { simpleParser } from 'mailparser';

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

const parsed = await simpleParser(raw);

for (const attachment of parsed.attachments) {
  // filename, contentType, size, and the file itself as a Buffer
  await saveToStorage(attachment.filename, attachment.content);
}

Lettr doesn’t store inbound messages or their attachments, so the payload is your only copy. Save what you need when the request arrives. See Attachments for storage examples and security practices such as file type checks and malware scanning.

Reply Tracking

Track replies to your transactional emails by using variable reply-to addresses:

// When sending an email
await lettr.emails.send({
  from: 'support@example.com',
  to: ['customer@example.com'],
  subject: 'Your support request',
  html: content,
  reply_to: `reply+ticket_${ticketId}@mail.example.com`
});

// When receiving the reply
const match = relay.rcpt_to.toLowerCase().match(/^reply\+ticket_([^@]+)@/);
if (match) {
  const ticketId = match[1];
  await addReplyToTicket(ticketId, { from: relay.msg_from, body: relay.content.text });
}

For more advanced threading, use email headers like Message-ID, In-Reply-To, and References to build full conversation threads. See Reply Tracking for header-based threading, auto-reply detection, and a complete support ticket example.

Real-World Examples

Support Ticket System

Create support tickets from incoming emails and track the conversation thread:

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

    const recipient = relay.rcpt_to.toLowerCase();
    const { msg_from, friendly_from, content } = relay;

    // Check if this is a reply to an existing ticket
    const replyMatch = recipient.match(/^reply\+ticket_([^@]+)@/);

    if (replyMatch) {
      // Add reply to existing ticket
      const ticketId = replyMatch[1];
      await db.ticketReplies.create({
        ticketId,
        from: msg_from,
        body: content.text
      });
    } else {
      // Create new ticket
      const ticket = await db.tickets.create({
        from: msg_from,
        fromName: friendly_from,
        subject: content.subject,
        body: content.text,
        status: 'open'
      });

      // Send acknowledgment with reply-to address for threading
      await lettr.emails.send({
        from: 'support@example.com',
        to: [msg_from],
        subject: `Re: ${content.subject}`,
        html: '<p>We received your request and will respond shortly.</p>',
        reply_to: `reply+ticket_${ticket.id}@mail.example.com`
      });
    }
  }

  res.sendStatus(200);
});

Email-to-Task Automation

Parse incoming emails to create tasks in your project management system:

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

    const { msg_from, content } = relay;

    // Create task from email
    const task = await projectManager.createTask({
      title: content.subject,
      description: content.text,
      reporter: msg_from
    });

    // Confirm task creation
    await lettr.emails.send({
      from: 'tasks@example.com',
      to: [msg_from],
      subject: `Task created: ${content.subject}`,
      html: `<p>Task <strong>${task.id}</strong> has been created from your email.</p>`
    });
  }

  res.sendStatus(200);
});

Using Subdomains

We recommend using a subdomain for inbound email to keep it separate from your primary email:

Subdomain	Use Case
`mail.example.com`	General inbound processing
`reply.example.com`	Reply tracking for transactional emails
`support.example.com`	Customer support emails
`inbound.example.com`	Automated workflow triggers

This lets you keep your root domain’s MX records pointing to your regular email provider while routing specific subdomains through Lettr.

Processing Best Practices

Respond quickly: Return a 2xx status as soon as you have the payload, and do slow work asynchronously via a queue.
Handle duplicates: The same email can be delivered more than once. The payload has no event ID, so deduplicate on the email’s Message-ID header.
Store before processing: Save the raw request body before doing any processing, so you can replay it if something fails. Lettr keeps no copy.
Validate attachments: If you extract attachments from email_rfc822, verify file types and scan for malware before using them.

See Best Practices for architecture patterns, reliability strategies, and monitoring recommendations.

Learn More

Setup Guide

Step-by-step domain and forwarding URL configuration

Routing

Route emails to different handlers

Attachments

Get attachments out of the raw MIME message

Spam Filtering

Add your own spam checks in your handler

Reply Tracking

Track and thread email replies

Email Parsing

Every field in the forwarding URL payload

Security

Secure your inbound processing

Best Practices

Build reliable email processing

Inbound Domains

Domain configuration details

Webhooks Overview

Lettr webhooks for event notifications, including relay delivery status

Building a Support Inbox

Turn customer emails into tickets with inbound email.

Documentation

Quickstart

Learn

Integrations

Resources

Inbound Introduction

What You Can Build

How It Works

Quick Start

1. Add an Inbound Domain

2. Configure DNS

3. Handle Incoming Emails

Webhook Payload

Key Capabilities

Email Routing

Spam Filtering

Attachment Handling

Reply Tracking

Real-World Examples

Support Ticket System

Email-to-Task Automation

Using Subdomains

Processing Best Practices

Learn More

Setup Guide

Routing

Attachments

Spam Filtering

Reply Tracking

Email Parsing

Security

Best Practices

Inbound Domains

Webhooks Overview

Building a Support Inbox

What You Can Build

How It Works

Quick Start

1. Add an Inbound Domain

2. Configure DNS

3. Handle Incoming Emails

Webhook Payload

Key Capabilities

Email Routing

Spam Filtering

Attachment Handling

Reply Tracking

Real-World Examples

Support Ticket System

Email-to-Task Automation

Using Subdomains

Processing Best Practices

Learn More

Setup Guide

Routing

Attachments

Spam Filtering

Reply Tracking

Email Parsing

Security

Best Practices

Related Topics

Inbound Domains

Webhooks Overview

Building a Support Inbox