Reply Tracking

Reply tracking lets you connect incoming replies to the emails you sent, for threaded conversations, support tickets, and automated workflows. Lettr’s part is delivery: you send with a reply_to address on your inbound domain, and when someone replies, the reply is posted to that domain’s forwarding URL. Matching the reply to the original email, threading it, and filtering auto-replies all happen in your code.

How Reply Tracking Works

Send with Reply-To

Send an email whose reply_to is an address on your inbound domain that encodes a conversation ID.

Recipient Replies

The reply goes to that address, and Lettr posts it to your inbound domain’s forwarding URL.

Match Reply (your code)

Your handler extracts the conversation ID from the recipient address and looks up the conversation.

Thread Together (your code)

Your handler adds the reply to the conversation in your own database.

Variable Reply-To Addresses

The most reliable way to track replies is variable (plus) addressing in the reply_to field. Every address at an inbound domain is forwarded, so you don’t need to create these addresses anywhere:

// Send an email with a trackable reply-to address
const { data, error } = await lettr.emails.send({
  from: 'support@example.com',
  to: ['customer@example.com'],
  subject: 'Re: Your support request',
  html: '<p>Thanks for contacting us...</p>',
  reply_to: `reply+ticket_${ticketId}@mail.example.com`,
  reply_to_name: 'Support Team'
});

Here mail.example.com is your inbound domain. When the customer replies, the reply is posted to its forwarding URL:

[
  {
    "msys": {
      "relay_message": {
        "rcpt_to": "reply+ticket_TKT-1234@mail.example.com",
        "msg_from": "customer@example.com",
        "friendly_from": "Customer Name <customer@example.com>",
        "content": {
          "subject": "Re: Your support request",
          "text": "Thanks, that fixed my issue!",
          "headers": [
            { "Message-ID": "<reply-id@example.com>" },
            { "In-Reply-To": "<original-message-id@example.com>" },
            { "References": "<original-message-id@example.com>" }
          ]
        }
      }
    }
  }
]

This example is shortened. See Email Parsing for every field.

Processing Replies

Extract the conversation ID from rcpt_to and match it to the original in your handler:

// Read a header from the headers array (case-insensitive)
function getHeader(headers = [], name) {
  const wanted = name.toLowerCase();
  for (const header of headers) {
    for (const [key, value] of Object.entries(header)) {
      if (key.toLowerCase() === wanted) return value;
    }
  }
  return null;
}

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;

    const { rcpt_to, msg_from, content } = relay;

    // Extract ticket ID from the reply address
    const match = rcpt_to.match(/^reply\+ticket_([^@]+)@/i);
    if (!match) continue;

    const ticketId = match[1];

    // Add the reply to the ticket in your database
    await addReplyToTicket(ticketId, {
      from: msg_from,
      subject: content.subject,
      body: content.text || stripHtml(content.html || ''),
      messageId: getHeader(content.headers, 'Message-ID'),
      inReplyTo: getHeader(content.headers, 'In-Reply-To'),
      receivedAt: new Date()
    });

    // Optionally notify the support agent
    await notifyAgent(ticketId, { from: msg_from, subject: content.subject });
  }

  res.sendStatus(200);
});

Anyone can send mail to any address at your inbound domain, including made-up reply+... addresses. Check that the ticket exists and that the sender belongs to it before you add the message, or use an unguessable token instead of a sequential ID.

Using Email Headers for Threading

Standard email headers can help your code group messages into threads:

Header	Purpose
`Message-ID`	Unique identifier for each email
`In-Reply-To`	Message-ID of the email being replied to
`References`	Chain of Message-IDs in the thread

Lettr’s send API returns a request_id, not the Message-ID of the email it sends, and doesn’t let you set Message-ID yourself. So header-based matching works against Message-IDs you have stored from earlier inbound messages, for example the customer’s previous reply in the same conversation:

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;

    const { msg_from, content } = relay;

    const inReplyTo = getHeader(content.headers, 'In-Reply-To');
    const references = getHeader(content.headers, 'References');

    let thread = null;

    if (inReplyTo) {
      // Find by direct reply to a message you stored earlier
      thread = await findThreadByMessageId(inReplyTo);
    }

    if (!thread && references) {
      // Find by any message in the reference chain
      for (const refId of references.split(/\s+/)) {
        thread = await findThreadByMessageId(refId);
        if (thread) break;
      }
    }

    const message = {
      from: msg_from,
      subject: content.subject,
      body: content.text,
      messageId: getHeader(content.headers, 'Message-ID')
    };

    if (thread) {
      await addMessageToThread(thread.id, message);
    } else {
      await createNewThread(message);
    }
  }

  res.sendStatus(200);
});

Building a Conversation Thread

Store and display threaded conversations in your own data model:

// Data model for conversation threads
class ConversationThread {
  constructor(id) {
    this.id = id;
    this.messages = [];
    this.participants = new Set();
    this.subject = '';
    this.createdAt = null;
    this.updatedAt = null;
  }

  addMessage(message) {
    this.messages.push({
      id: message.id || generateId(),
      from: message.from,
      body: message.body,
      direction: message.direction, // 'inbound' or 'outbound'
      timestamp: message.timestamp || new Date()
    });

    this.participants.add(message.from);
    this.updatedAt = new Date();

    if (!this.createdAt) {
      this.createdAt = this.updatedAt;
    }
  }

  getChronological() {
    return [...this.messages].sort((a, b) =>
      new Date(a.timestamp) - new Date(b.timestamp)
    );
  }
}

// Usage
const thread = await getOrCreateThread(ticketId);

// When receiving a reply: use the Message-ID header
thread.addMessage({
  id: getHeader(relay.content.headers, 'Message-ID'),
  from: relay.msg_from,
  body: relay.content.text,
  direction: 'inbound'
});

// When sending a response: use the request_id from the send API
const { data, error } = await lettr.emails.send(responseEmail);
if (!error) {
  thread.addMessage({
    id: data.request_id,
    from: 'support@example.com',
    body: responseText,
    direction: 'outbound'
  });
}

await saveThread(thread);

Auto-Reply Detection

Out-of-office replies and delivery reports also arrive at your reply addresses. Lettr doesn’t flag them, so detect them in your handler:

function isAutoReply(relay) {
  const { content } = relay;
  const subject = (content.subject || '').toLowerCase();

  // Check standard auto-reply headers
  const autoSubmitted = getHeader(content.headers, 'Auto-Submitted');
  if (autoSubmitted && autoSubmitted.toLowerCase() !== 'no') {
    return true;
  }

  if (getHeader(content.headers, 'X-Auto-Response-Suppress')) {
    return true;
  }

  const precedence = (getHeader(content.headers, 'Precedence') || '').toLowerCase();
  if (['auto_reply', 'bulk', 'junk'].includes(precedence)) {
    return true;
  }

  // Check common auto-reply subject patterns
  const autoReplyPatterns = [
    /^out of office/i,
    /^automatic reply/i,
    /^auto:/i,
    /^autoreply/i,
    /^vacation/i,
    /^away from/i,
    /delivery (status )?notification/i,
    /^undeliverable:/i,
    /^returned mail/i
  ];

  return autoReplyPatterns.some((pattern) => pattern.test(subject));
}

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;

    if (isAutoReply(relay)) {
      // Log but don't create a ticket or notify anyone
      await logAutoReply(relay);
      continue;
    }

    await processReply(relay);
  }

  res.sendStatus(200);
});

Don’t send an automatic response to an auto-reply. Two auto-responders answering each other can loop indefinitely.

Reply Matching Strategies

Strategy 1: Variable Address (Recommended)

Mail clients send the reply to the reply_to address, so the ID always comes back in rcpt_to:

// Encode data in the reply-to address
const replyTo = `reply+${encodeData(conversationId)}@mail.example.com`;

function encodeData(id) {
  return Buffer.from(id).toString('base64url');
}

function decodeData(encoded) {
  return Buffer.from(encoded, 'base64url').toString();
}

Some systems lowercase the local part of an address. If your IDs are case-sensitive, use an encoding that survives lowercasing, such as hex.

Strategy 2: Subject Line Tokens

Most mail clients keep the subject when replying, prefixed with Re::

// Add a token to the subject
const subject = `[Ticket #${ticketId}] Your support request`;

// Parse the token from replies
function extractTicketFromSubject(subject = '') {
  const match = subject.match(/\[Ticket #([^\]]+)\]/);
  return match ? match[1] : null;
}

Recipients can edit the subject, so use this as a fallback rather than your only signal.

Strategy 3: Message-ID Headers

Match In-Reply-To and References against Message-IDs of inbound messages you have stored, as shown in Using Email Headers for Threading. This connects follow-up replies within a conversation. It can’t connect the first reply to your original email, because the send API doesn’t return that email’s Message-ID.

Custom Headers Don’t Come Back

You can add custom headers to outgoing email with the headers field, but mail clients don’t copy them into replies. Don’t rely on headers such as X-Conversation-ID for reply matching; put the ID in the reply-to address instead.

Handling Reply Chains

When several people take part in a conversation:

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;

    const { rcpt_to, msg_from, content } = relay;

    // Find the conversation
    const conversationId = extractConversationId(rcpt_to);
    const conversation = await getConversation(conversationId);

    if (!conversation) continue;

    // Add the new message
    await addMessage(conversationId, {
      from: msg_from,
      body: content.text,
      messageId: getHeader(content.headers, 'Message-ID'),
      inReplyTo: getHeader(content.headers, 'In-Reply-To')
    });

    // Track all participants from the To and CC headers
    const toAddresses = content.to || [];
    const ccAddresses = content.cc || [];
    for (const recipient of [...toAddresses, ...ccAddresses]) {
      if (!recipient.toLowerCase().includes('@mail.example.com')) {
        await addParticipant(conversationId, recipient);
      }
    }

    // Notify internal team members
    await notifyTeam(conversation, { from: msg_from, subject: content.subject, body: content.text });
  }

  res.sendStatus(200);
});

Complete Support Ticket Example

import express from 'express';
import { Lettr } from 'lettr';

const app = express();
const lettr = new Lettr(process.env.LETTR_API_KEY);

// Send a support response with a trackable reply-to address
async function sendTicketResponse(ticket, responseText) {
  const { data, error } = await lettr.emails.send({
    from: 'support@example.com',
    from_name: 'Support Team',
    to: [ticket.customerEmail],
    subject: `Re: ${ticket.subject}`,
    html: `
      <p>${escapeHtml(responseText)}</p>
      <hr>
      <p style="color: #666; font-size: 12px;">
        Ticket #${ticket.id} - Please reply above this line
      </p>
    `,
    reply_to: `reply+${ticket.id}@mail.example.com`,
    metadata: {
      ticket_id: String(ticket.id),
      type: 'support_response'
    }
  });

  if (error) {
    throw new Error(`Send failed: ${error.message}`);
  }

  // Store the outgoing message, keyed by the send request ID
  await addTicketMessage(ticket.id, {
    from: 'support@example.com',
    body: responseText,
    direction: 'outbound',
    requestId: data.request_id
  });

  return data;
}

// Handle incoming replies
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;

    const { rcpt_to, msg_from, content } = relay;

    // Skip auto-replies
    if (isAutoReply(relay)) {
      continue;
    }

    // Extract ticket ID
    const match = rcpt_to.match(/^reply\+([^@]+)@/i);

    if (!match) {
      // Not a reply to a ticket: create a new ticket
      const ticket = await createTicket({
        customerEmail: msg_from,
        subject: content.subject || '(no subject)',
        body: content.text || stripHtml(content.html || '')
      });

      // Send acknowledgment
      await sendTicketResponse(ticket,
        'Thank you for contacting us. We\'ve received your request and will respond shortly.'
      );

      continue;
    }

    const ticketId = match[1];
    const ticket = await getTicket(ticketId);

    if (!ticket) {
      console.warn(`Ticket not found: ${ticketId}`);
      continue;
    }

    // Add customer reply to ticket
    await addTicketMessage(ticketId, {
      from: msg_from,
      body: content.text || stripHtml(content.html || ''),
      direction: 'inbound',
      messageId: getHeader(content.headers, 'Message-ID'),
      inReplyTo: getHeader(content.headers, 'In-Reply-To')
    });

    // Update ticket status
    await updateTicket(ticketId, {
      status: 'awaiting_response',
      lastCustomerReply: new Date()
    });

    // Notify assigned agent
    if (ticket.assignedTo) {
      await notifyAgent(ticket.assignedTo, {
        ticketId,
        customerEmail: msg_from,
        preview: (content.text || '').substring(0, 100)
      });
    }
  }

  res.sendStatus(200);
});

In production, respond with a 2xx before doing slow work such as sending the acknowledgment, and skip messages whose Message-ID you have already processed. See Best Practices.

Email Parsing

The inbound payload structure

Routing

Route emails to handlers

Metadata

Track emails with metadata

Documentation

Quickstart

Learn

Integrations

Resources

Reply Tracking

How Reply Tracking Works

Variable Reply-To Addresses

Processing Replies

Using Email Headers for Threading

Building a Conversation Thread

Auto-Reply Detection

Reply Matching Strategies

Strategy 1: Variable Address (Recommended)

Strategy 2: Subject Line Tokens

Strategy 3: Message-ID Headers

Custom Headers Don’t Come Back

Handling Reply Chains

Complete Support Ticket Example

Email Parsing

Routing

Metadata

​How Reply Tracking Works

​Variable Reply-To Addresses

​Processing Replies

​Using Email Headers for Threading

​Building a Conversation Thread

​Auto-Reply Detection

​Reply Matching Strategies

​Strategy 1: Variable Address (Recommended)

​Strategy 2: Subject Line Tokens

​Strategy 3: Message-ID Headers

​Custom Headers Don’t Come Back

​Handling Reply Chains

​Complete Support Ticket Example

​Related Topics

Email Parsing

Routing

Metadata

How Reply Tracking Works

Variable Reply-To Addresses

Processing Replies

Using Email Headers for Threading

Building a Conversation Thread

Auto-Reply Detection

Reply Matching Strategies

Strategy 1: Variable Address (Recommended)

Strategy 2: Subject Line Tokens

Strategy 3: Message-ID Headers

Custom Headers Don’t Come Back

Handling Reply Chains

Complete Support Ticket Example

Related Topics