Spam Filtering

Lettr doesn’t score, filter or quarantine inbound mail. Every message accepted for your inbound domain is posted to your forwarding URL, spam included. There is no spam score in the payload and no spam setting in the dashboard. If you want spam handling, you build it into the handler behind your forwarding URL. This page shows common techniques for doing that with the fields you actually receive.

Answer each request with a 2xx, including for messages you decide to drop. The mail has already been accepted by the time it reaches your endpoint, so an error response can’t reject it back to the sender. It only makes the delivery to your endpoint look failed.

What You Have to Work With

Your forwarding URL receives a JSON array of events. Each event carries one message in event.msys.relay_message (see Email Parsing for the full payload). The fields that matter for spam handling are:

Field	What it is
`msg_from`	Envelope sender (SMTP `MAIL FROM`)
`friendly_from`	Display name and address from the `From` header
`rcpt_to`	The address on your inbound domain the message was sent to
`content.subject`	Subject line
`content.text` / `content.html`	Plain text and HTML bodies. Either can be missing.
`content.headers`	Message headers, as an array of single-key objects
`content.email_rfc822`	The full raw MIME message, including attachments

Both sender fields are set by whoever sent the message, so treat them as claims, not proof of identity. Headers come as an array like [{ "Received": "..." }, { "Subject": "..." }], and a name can appear more than once. A small helper makes them easier to read:

// Returns every value of a header, matching the name case-insensitively
function getHeaders(relay, name) {
  const wanted = name.toLowerCase();
  const values = [];

  for (const header of relay.content?.headers ?? []) {
    for (const [key, value] of Object.entries(header)) {
      if (key.toLowerCase() === wanted) {
        values.push(value);
      }
    }
  }

  return values;
}

function senderAddress(relay) {
  return (relay.msg_from || '').toLowerCase();
}

function senderDomain(relay) {
  return senderAddress(relay).split('@')[1] || '';
}

Check Authentication Results

Some messages carry an Authentication-Results or Received-SPF header, added by a mail server that checked SPF, DKIM or DMARC along the way. Don’t assume these headers are present, and remember that a sender can put a fake one in their own message. Use them as one signal among several, never as the only check.

function authenticationSignals(relay) {
  const results = getHeaders(relay, 'Authentication-Results').join(' ').toLowerCase();

  if (!results) {
    return { known: false };
  }

  return {
    known: true,
    spfFail: /\bspf=(fail|softfail)\b/.test(results),
    dkimFail: /\bdkim=fail\b/.test(results),
    dmarcFail: /\bdmarc=fail\b/.test(results)
  };
}

Build Your Own Heuristics

A simple approach is to add up points for suspicious signals and act on the total. The point scale below belongs to this example code. It isn’t a Lettr score, so tune the weights and thresholds to your own traffic.

function scoreMessage(relay) {
  const signals = [];
  let score = 0;

  const subject = (relay.content?.subject || '').toLowerCase();
  const body = (relay.content?.text || relay.content?.html || '').toLowerCase();

  // Suspicious subject patterns
  const spamSubjectPatterns = [
    /\bfree\b.*\bmoney\b/,
    /\burgent\b.*\baction\b/,
    /\bwinner\b/,
    /\bcongratulations\b.*\bwon\b/,
    /\blottery\b/
  ];

  for (const pattern of spamSubjectPatterns) {
    if (pattern.test(subject)) {
      score += 2;
      signals.push(`Suspicious subject pattern: ${pattern}`);
    }
  }

  // Many links
  const linkCount = (body.match(/https?:\/\//g) || []).length;
  if (linkCount > 10) {
    score += 1;
    signals.push(`Many links: ${linkCount}`);
  }

  // URL shorteners
  for (const shortener of ['bit.ly', 'tinyurl.com', 't.co']) {
    if (body.includes(shortener)) {
      score += 1.5;
      signals.push(`URL shortener: ${shortener}`);
    }
  }

  // Failed authentication, when the headers report it
  const auth = authenticationSignals(relay);
  if (auth.known && (auth.spfFail || auth.dkimFail || auth.dmarcFail)) {
    score += 3;
    signals.push('Authentication failed');
  }

  // Your own record of bad sender domains
  if (isSuspiciousDomain(senderDomain(relay))) {
    score += 2;
    signals.push(`Suspicious sender domain: ${senderDomain(relay)}`);
  }

  return { score, signals };
}

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 { score, signals } = scoreMessage(relay);

    if (score >= 8) {
      await logDroppedSpam(relay, signals); // drop it
      continue;
    }

    if (score >= 5) {
      await quarantine.add(relay, signals); // keep it for review
      continue;
    }

    await processEmail(relay);
  }

  res.sendStatus(200);
});

If you’d rather not write your own rules, your handler can pass the raw message in content.email_rfc822 to a third-party spam filter. When content.email_rfc822_is_base64 is true, base64-decode it first.

Allow and Block Lists

Keep your own lists of trusted and blocked senders, for example in your database, and check them before any other rule:

async function checkLists(relay) {
  const from = senderAddress(relay);
  const domain = senderDomain(relay);

  if ((await allowlist.has(from)) || (await allowedDomains.has(domain))) {
    return 'allow';
  }

  if ((await blocklist.has(from)) || (await blockedDomains.has(domain))) {
    return 'block';
  }

  return 'check';
}

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 listResult = await checkLists(relay);

    if (listResult === 'block') {
      await logBlockedEmail(relay);
      continue;
    }

    if (listResult === 'allow') {
      await processEmail(relay);
      continue;
    }

    // Unlisted sender: apply your heuristics
    const { score, signals } = scoreMessage(relay);
    if (score >= 5) {
      await quarantine.add(relay, signals);
      continue;
    }

    await processEmail(relay);
  }

  res.sendStatus(200);
});

Because a sender address can be forged, an allowlist entry is safest when the message also shows a passing authentication result for that sender.

Rate Limiting by Sender

Limit how many messages one sender or sender domain can push through your pipeline:

import { RateLimiterMemory } from 'rate-limiter-flexible';

const senderLimiter = new RateLimiterMemory({ points: 10, duration: 60 }); // 10 per minute
const domainLimiter = new RateLimiterMemory({ points: 50, duration: 60 }); // 50 per minute

async function withinRateLimits(relay) {
  try {
    await senderLimiter.consume(senderAddress(relay) || 'unknown');
    await domainLimiter.consume(senderDomain(relay) || 'unknown');
    return true;
  } catch {
    return false;
  }
}

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 (!(await withinRateLimits(relay))) {
      console.warn(`Rate limited: ${relay.msg_from}`);
      await logRateLimited(relay);
      continue;
    }

    await processEmail(relay);
  }

  res.sendStatus(200);
});

RateLimiterMemory counts per process. If you run more than one instance of your handler, use a shared store such as Redis.

Quarantine in Your Own Storage

Lettr doesn’t keep inbound messages, so a quarantine has to live in your own storage. Key each record on the Message-ID header, which also lets you ignore a message that arrives twice:

import crypto from 'node:crypto';

class EmailQuarantine {
  constructor(storage) {
    this.storage = storage;
  }

  async add(relay, reasons) {
    const messageId = getHeaders(relay, 'Message-ID')[0] ?? crypto.randomUUID();

    await this.storage.upsert(messageId, {
      messageId,
      relay, // the full relay_message, so you can process it later
      reasons,
      status: 'pending',
      quarantinedAt: new Date().toISOString()
    });
  }

  async release(messageId) {
    const record = await this.storage.get(messageId);
    if (!record) throw new Error('Message not found');

    await this.storage.update(messageId, { status: 'released' });
    return record.relay;
  }

  async listPending() {
    return this.storage.query({ status: 'pending' });
  }
}

const quarantine = new EmailQuarantine(quarantineStorage);

// Admin endpoints for reviewing the quarantine
app.get('/admin/quarantine', async (req, res) => {
  res.json(await quarantine.listPending());
});

app.post('/admin/quarantine/release', express.json(), async (req, res) => {
  const relay = await quarantine.release(req.body.messageId);
  await processEmail(relay);
  res.json({ success: true });
});

Decide how long to keep quarantined messages and delete them on your own schedule.

Learning From Reports

When spam gets through, let your users report it and add the sender to your blocklist:

app.post('/api/report-spam', express.json(), async (req, res) => {
  const { messageId } = req.body;

  const stored = await getStoredEmail(messageId); // a relay_message you saved earlier
  await blocklist.add(stored.msg_from.toLowerCase());

  await logSpamReport({
    messageId,
    sender: stored.msg_from,
    reportedAt: new Date()
  });

  res.json({ success: true });
});

Best Practices

Quarantine before you drop

Start by quarantining suspicious mail instead of discarding it. Once you know your false positive rate, you can drop the clearest cases.

Log every decision

Record why each message was allowed, quarantined or dropped. Lettr doesn’t keep a copy of inbound mail, so your logs are the only way to trace a missing email.

Combine multiple signals

No single check is reliable on its own. Combine allow and block lists, authentication results when present, rate limits and content rules.

Do slow checks asynchronously

Answer the request quickly and run expensive checks, such as a third-party filter, from a queue.

Review the quarantine regularly

Release false positives promptly and use them to tune your rules.

Be careful with aggressive filtering. False positives can make you miss important emails from customers or partners.

Email Parsing

The full inbound payload

Routing

Route emails in your handler

Security

Security best practices

Best Practices

Overall inbound best practices

Documentation

Quickstart

Learn

Integrations

Resources

Spam Filtering

What You Have to Work With

Check Authentication Results

Build Your Own Heuristics

Allow and Block Lists

Rate Limiting by Sender

Quarantine in Your Own Storage

Learning From Reports

Best Practices

Email Parsing

Routing

Security

Best Practices

What You Have to Work With

Check Authentication Results

Build Your Own Heuristics

Allow and Block Lists

Rate Limiting by Sender

Quarantine in Your Own Storage

Learning From Reports

Best Practices

Related Topics

Email Parsing

Routing

Security

Best Practices