Building a Support Inbox with Inbound Email

Customer → MX records → Lettr inbound servers → Forwarding URL (JSON POST) → Your app (ticket)
Your app (agent reply) → Send API → Customer

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

const app = express();

function verifyToken(req, res, next) {
  const token = req.get('X-MessageSystems-Webhook-Token') ?? '';
  const expected = process.env.INBOUND_AUTH_TOKEN ?? '';

  const ok =
    token.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(token), Buffer.from(expected));

  return ok ? next() : res.sendStatus(401);
}

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

    await handleSupportEmail(relay);
  }

  res.sendStatus(200);
});

// Headers arrive as an array of single-key objects
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 undefined;
}

// "Name <a@b.com>" or "a@b.com" -> "a@b.com"
function extractAddress(value) {
  const match = value?.match(/<([^>]+)>/);
  return (match ? match[1] : value ?? '').trim();
}

// Reply-To header first, then the From header, then the envelope sender
function customerAddress(relay) {
  const replyTo = getHeader(relay.content.headers, 'Reply-To');
  return extractAddress(replyTo) || extractAddress(relay.friendly_from) || relay.msg_from;
}

async function handleSupportEmail(relay) {
  const { rcpt_to, content } = relay;
  const customer = customerAddress(relay);

  if (await isSpam(relay)) return; // still answer 2xx, see Step 5

  const messageId = getHeader(content.headers, 'Message-ID');
  const references = getHeader(content.headers, 'References');

  // Reuse the ticket if this message belongs to an existing conversation
  let ticket = await findTicketByThread({
    inReplyTo: getHeader(content.headers, 'In-Reply-To'),
    references,
  });

  if (!ticket) {
    ticket = await createTicket({
      from: customer,
      mailbox: rcpt_to.toLowerCase(),
      subject: content.subject,
    });
  }

  await addMessage(ticket.id, {
    from: customer,
    body: content.text || content.html,
    messageId,
    references,
    subject: content.subject,
  });
}

async function isSpam(relay) {
  const { content } = relay;

  // Auto-replies and bulk mail
  const autoSubmitted = (getHeader(content.headers, 'Auto-Submitted') ?? 'no').toLowerCase();
  if (autoSubmitted !== 'no') return true;

  const precedence = (getHeader(content.headers, 'Precedence') ?? '').toLowerCase();
  if (['bulk', 'junk', 'list'].includes(precedence)) return true;

  // Failed authentication, when the header is present
  const authResults = getHeader(content.headers, 'Authentication-Results');
  if (authResults && /dmarc=fail/i.test(authResults)) return true;

  // Add your own checks: blocked senders, rate per sender, a third-party filter
  return false;
}

curl -X POST https://app.lettr.com/api/emails \
  -H "Authorization: Bearer lttr_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-4821-reply-17" \
  -d '{
    "from": "support@example.com",
    "from_name": "Example Support",
    "to": ["customer@example.net"],
    "reply_to": "support+t-4821@support.example.com",
    "subject": "Re: Help with my order",
    "text": "Hi Alex, your order shipped this morning. Tracking: ...",
    "headers": {
      "In-Reply-To": "<abc123@example.net>",
      "References": "<first-message@example.net> <abc123@example.net>"
    },
    "metadata": { "ticket_id": "4821" }
  }'