Inbound Domains

An inbound domain is a domain configured to receive incoming emails through Lettr. By pointing your domain’s MX records to Lettr’s mail servers and giving Lettr a forwarding URL to deliver each message to, you can capture replies to transactional emails, process incoming support messages, or trigger automated workflows when emails arrive. This is useful for building reply tracking, support ticket systems, or any application that needs to programmatically handle incoming email.

Why Use Inbound Domains?

Inbound domains let your application participate in two-way email communication:

Capture replies: Feed replies to transactional emails (such as order confirmations or password resets) back into your system
Trigger workflows: Process incoming mail in your handler to create support tickets, update CRM records, or route messages to the right team
Real-time delivery: Every received email is posted to your forwarding URL, so you can react in real time without polling
Any address works: Mail sent to any address at the domain is forwarded, so you can build dedicated inboxes (like support@inbound.yourcompany.com) or per-record addresses without creating them first

How Inbound Email Works

A sender emails support@inbound.yourcompany.com
Their email server looks up MX records for inbound.yourcompany.com
MX records point to Lettr’s mail servers
Lettr receives the email
Lettr posts the email to your domain’s forwarding URL as JSON, including the full raw MIME message

Lettr doesn’t score, filter, or store the mail it forwards. Spam checks, routing, and attachment handling happen in your handler.

Adding an Inbound Domain

Via Dashboard

Navigate to Inbound Domains

Go to Domains → Inbound in your dashboard.

Create the Domain

Click Create Inbound Domain (New Inbound Domain once you already have one) and enter your domain name. A subdomain such as inbound.example.com is strongly recommended, so your root domain keeps its existing mailbox provider.

Enter a Forwarding URL

Enter the Forwarding URL that should receive mail sent to this domain (a full http:// or https:// address), and optionally an Auth token. The token is sent to your endpoint in the X-MessageSystems-Webhook-Token header so you can verify each request. Click Create Inbound Domain.

Add MX Records

Add the provided MX records to your DNS. These tell email servers to route mail to Lettr. If your DNS is hosted on Cloudflare, you can click Configure with Cloudflare on the domain’s page to add them automatically.

Verify Domain

Click Verify MX Records on the domain’s page to confirm MX record configuration.

Try it in the app

Follow an interactive walkthrough of this guide inside Lettr.

Forwarding URL Test

The forwarding URL is required and is tested before the domain is created: SparkPost, the mail infrastructure behind Lettr’s inbound servers, sends a POST request to it and needs a 2xx response. If your endpoint rejects the test, the dashboard shows the status it returned (for example “Your forwarding URL answered SparkPost with HTTP 403”) and the domain is not created.

A firewall or WAF such as Cloudflare commonly blocks the test with a challenge page. Allow server-to-server POST requests on your forwarding URL’s path. SparkPost publishes no fixed source IP addresses, so verify requests with the auth token rather than an IP allowlist. See Inbound Security.

Inbound domains are managed through the Lettr dashboard. API endpoints for inbound domains are not currently available. The Lettr MCP server can list your inbound domains but not create or change them.

Want to see what an email looks like when it arrives, before touching your DNS? Every team gets a dedicated sandbox inbox: send an email to your sandbox address and inspect it in the dashboard, no MX records required. Sandbox mail is not forwarded to your forwarding URL, so use an inbound domain on a test subdomain to test your endpoint.

DNS Configuration

Add these MX records to your domain’s DNS settings:

Type	Host/Name	Priority	Value
MX	`@` or subdomain	10	`rx1.sparkpostmail.com`
MX	`@` or subdomain	10	`rx2.sparkpostmail.com`
MX	`@` or subdomain	10	`rx3.sparkpostmail.com`

All three records are required.

If using a subdomain like mail.example.com, set the Host/Name field to mail instead of @.

Understanding MX Priority

All three MX records use the same priority (10), which means email servers will distribute delivery across all three servers equally. If one server is unavailable, senders automatically try the others.

Verifying Your Inbound Domain

Via Dashboard

Go to Domains → Inbound and open your domain
Click Verify MX Records
Lettr checks that all MX records are configured correctly

If the domain has no MX records, the failed check tells you where mail sent to it is actually going. A domain without MX records falls back to its A record, so mail is delivered to that host instead of reaching Lettr.

Inbound Domain Status

Each inbound domain shows one status: either it is receiving mail, or what is missing. The Inbound Domains list shows:

Status	Description
Receiving mail	MX records are verified and a forwarding URL is set
MX not verified	MX records are not yet detected or incomplete, so mail never reaches Lettr
No forwarding URL	Mail that arrives is accepted and then discarded, because there is nowhere to forward it

A domain can show both problems at once. On the domain’s page, the same verdict reads This domain is receiving mail or This domain is not receiving mail yet, with each missing piece listed.

Mail Forwarding

Every inbound domain’s page has a Mail Forwarding card showing where its mail is delivered. Use it to add or change the Forwarding URL and Auth token, then click Save forwarding URL. The new URL is tested before it is saved. Leave Auth token blank to keep the token already set.

Inbound domains created before forwarding URLs were required have none, so their mail is accepted and then discarded. Their Mail Forwarding card shows Not configured until you add a URL.

Using Subdomains

We recommend using a subdomain for inbound email to separate it from your main domain’s email:

Configuration	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

Using subdomains lets you keep your root domain’s MX records pointing to your regular email provider (Gmail, Microsoft 365, etc.) while routing specific addresses through Lettr.

Processing Inbound Emails

Forwarding URL Payload

Each email sent to the domain is posted to your forwarding URL as a JSON array of events (one request can carry more than one email), each holding an msys.relay_message object:

[
  {
    "msys": {
      "relay_message": {
        "msg_from": "sender@external.com",
        "rcpt_to": "support@mail.example.com",
        "friendly_from": "Sender <sender@external.com>",
        "content": {
          "subject": "Question about my order",
          "text": "Hello, I have a question...",
          "html": "<p>Hello, I have a question...</p>",
          "headers": [
            { "Message-ID": "<abc123@external.com>" },
            { "Date": "Mon, 15 Jan 2024 10:30:00 +0000" }
          ],
          "to": ["support@mail.example.com"],
          "email_rfc822": "...raw MIME content...",
          "email_rfc822_is_base64": false
        }
      }
    }
  }
]

Attachments are not sent as separate fields. They are inside the raw message in email_rfc822, which you parse with a MIME library. If you set an auth token, it arrives in the X-MessageSystems-Webhook-Token header. See Email Parsing for a breakdown of each field and Attachments for extracting files.

Delete an Inbound Domain

Deleting an inbound domain stops forwarding: mail sent to addresses on this domain no longer reaches your forwarding URL. This cannot be undone. Remove or repoint the domain’s MX records if you no longer use it.

Via Dashboard

Go to Domains → Inbound
Find the domain and click its delete (trash) icon
Type the domain name to confirm, then click Delete Inbound Domain

Use Cases

Reply Tracking

Capture replies to transactional emails:

Set up reply.example.com as an inbound domain
Send emails with reply_to: reply+{ticket_id}@reply.example.com
Receive the reply at your forwarding URL when the customer replies
Read the ticket ID from the recipient address (rcpt_to) to match the original email

See Reply Tracking for the full pattern.

Support Ticketing

Create a support email system:

Set up support.example.com as an inbound domain
Point its forwarding URL at your ticketing endpoint
Create tickets in your system from email content
Use the Message-ID, In-Reply-To, and References headers to track conversation threads

Data Extraction

Extract structured data from incoming emails:

Receive order confirmations, receipts, or notifications
Read the content posted to your forwarding URL (text, html, or the raw email_rfc822)
Extract relevant data in your handler and store it in your database

Troubleshooting

MX records not verified

DNS changes can take up to 48 hours to propagate
Verify all three MX records are added with correct priorities
Use a tool like MXToolbox to check your MX records
Ensure no conflicting MX records exist

Emails not being received

Confirm the domain shows Receiving mail in the dashboard. If it shows No forwarding URL, add one on the domain’s Mail Forwarding card.
Verify your forwarding URL is reachable and returns a 2xx status
Check that your firewall or WAF isn’t blocking server-to-server POST requests to the forwarding URL
Lettr doesn’t filter inbound mail, so check your handler’s logs for requests it received but rejected, discarded, or failed to process

Forwarding URL rejected when creating the domain

The dashboard shows the HTTP status your endpoint returned to the test request, and the domain is not created
Make sure the endpoint accepts POST requests and returns a 2xx status
If it sits behind Cloudflare or another WAF, allow server-to-server POST requests on that path
SparkPost publishes no fixed source IPs, so don’t rely on an IP allowlist. Use the auth token instead.

Partial MX records detected

All three MX servers must be configured
Check for typos in server hostnames
Ensure all three records have priority 10

Conflict with existing email provider

Use a subdomain instead of your root domain
You can only have one set of MX records per domain/subdomain
Consider using mail.example.com while keeping example.com with your current provider

Best Practices

Use subdomains - Keep inbound separate from your main email
Test your forwarding URL early - Make sure your endpoint receives inbound mail before going live
Handle attachments carefully - Validate and scan files you extract from email_rfc822
Handle spam yourself - Lettr doesn’t filter inbound mail, so add your own checks in your handler
Test with multiple senders - Verify emails arrive from various email providers

Sending Domains

Configure domains for sending

Inbound Setup

Forwarding URL and MX setup step by step

Inbound

Learn about inbound email

Tracking Domains

Custom tracking domains

Documentation

Quickstart

Learn

Integrations

Resources

Inbound Domains

Why Use Inbound Domains?

How Inbound Email Works

Adding an Inbound Domain

Via Dashboard

Try it in the app

Forwarding URL Test

DNS Configuration

Understanding MX Priority

Verifying Your Inbound Domain

Via Dashboard

Inbound Domain Status

Mail Forwarding

Using Subdomains

Processing Inbound Emails

Forwarding URL Payload

Delete an Inbound Domain

Via Dashboard

Use Cases

Reply Tracking

Support Ticketing

Data Extraction

Troubleshooting

Best Practices

Sending Domains

Inbound Setup

Inbound

Tracking Domains

​Why Use Inbound Domains?

​How Inbound Email Works

​Adding an Inbound Domain

​Via Dashboard

Try it in the app

​Forwarding URL Test

​DNS Configuration

​Understanding MX Priority

​Verifying Your Inbound Domain

​Via Dashboard

​Inbound Domain Status

​Mail Forwarding

​Using Subdomains

​Processing Inbound Emails

​Forwarding URL Payload

​Delete an Inbound Domain

​Via Dashboard

​Use Cases

​Reply Tracking

​Support Ticketing

​Data Extraction

​Troubleshooting

​Best Practices

​Related Topics

Sending Domains

Inbound Setup

Inbound

Tracking Domains

Why Use Inbound Domains?

How Inbound Email Works

Adding an Inbound Domain

Via Dashboard

Forwarding URL Test

DNS Configuration

Understanding MX Priority

Verifying Your Inbound Domain

Via Dashboard

Inbound Domain Status

Mail Forwarding

Using Subdomains

Processing Inbound Emails

Forwarding URL Payload

Delete an Inbound Domain

Via Dashboard

Use Cases

Reply Tracking

Support Ticketing

Data Extraction

Troubleshooting

Best Practices

Related Topics