Best Practices

Follow these best practices to build reliable, secure, and maintainable inbound email processing systems.

Architecture

Process Asynchronously

Respond to each delivery with a 2xx quickly and do slow work in the background. Lettr doesn’t document a timeout for your forwarding URL, so keep the request itself short:

// Good: Queue the work, then respond
app.post('/webhooks/inbound', express.json({ limit: '50mb' }), async (req, res) => {
  // Queue each event for async processing (fast)
  for (const event of req.body) {
    const relay = event.msys?.relay_message;
    if (relay) {
      await emailQueue.add('process-inbound', relay);
    }
  }

  // Acknowledge once the work is safely queued
  res.sendStatus(200);
});

// Process in background
emailQueue.process('process-inbound', async (job) => {
  const relay = job.data;
  await processEmail(relay);
});

// Bad: Blocking the webhook response
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;

    // Slow work inside the request
    await extractAndStoreAttachments(relay);
    await processEmail(relay);
    await sendNotifications(relay);
    await updateDatabase(relay);
  }

  res.sendStatus(200);
});

Implement Idempotency

The same message can arrive more than once, so make processing idempotent. Events carry no ID of their own; key on the message’s Message-ID header instead:

import Redis from 'ioredis';
const redis = new Redis();

// 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;
}

async function processEmailOnce(relay) {
  const messageId = getHeader(relay.content.headers, 'Message-ID');
  // Fall back to a hash of the raw message if Message-ID is missing
  const dedupeId = messageId || sha256(relay.content.email_rfc822 || '');
  // Include the recipient: one message sent to two of your addresses is two deliveries
  const key = `processed:${relay.rcpt_to}:${dedupeId}`;

  // Try to set the key (only succeeds if it doesn't exist)
  const isNew = await redis.set(key, '1', 'EX', 7 * 86400, 'NX');

  if (!isNew) {
    console.log(`Already processed: ${key}`);
    return { skipped: true };
  }

  try {
    await processEmail(relay);
  } catch (error) {
    await redis.del(key); // allow a later attempt
    throw error;
  }
  return { processed: true };
}

Use Separate Queues by Priority

import Queue from 'bull';

const highPriorityQueue = new Queue('email-high', redisUrl);
const normalQueue = new Queue('email-normal', redisUrl);
const lowPriorityQueue = new Queue('email-low', redisUrl);

function routeToQueue(relay) {
  if (isVipCustomer(relay.msg_from)) {
    return highPriorityQueue;
  }
  // Your own spam heuristic: Lettr adds no spam score
  if (looksLikeSpam(relay)) {
    return lowPriorityQueue;
  }
  return normalQueue;
}

// Process with different concurrency
highPriorityQueue.process(10, processEmail);
normalQueue.process(5, processEmail);
lowPriorityQueue.process(2, processEmail);

Reliability

Store Before Processing

Lettr doesn’t keep a copy of inbound mail, so save the payload yourself before any processing:

app.post('/webhooks/inbound', express.json({ limit: '50mb' }), async (req, res) => {
  // Store raw payload first
  await storeRawPayload({
    payload: req.body,
    receivedAt: new Date()
  });

  res.sendStatus(200);

  // Then process each event (your own retry job can replay it from stored data)
  for (const event of req.body) {
    const relay = event.msys?.relay_message;
    if (!relay) continue;

    try {
      await processEmail(relay);
      await markAsProcessed(getHeader(relay.content.headers, 'Message-ID'));
    } catch (error) {
      await markAsFailed(relay, error);
      await scheduleRetry(relay);
    }
  }
});

Retry Your Own Downstream Calls

When your processing calls other services (your database, a ticketing API, storage), retry transient failures in your own code. This is your application’s retry policy, separate from how the message reaches your forwarding URL:

class EmailProcessor {
  constructor() {
    this.maxRetries = 3;
    this.retryDelays = [1000, 5000, 30000]; // 1s, 5s, 30s
  }

  async processWithRetry(email, attempt = 0) {
    try {
      await this.process(email);
      return { success: true };
    } catch (error) {
      if (attempt < this.maxRetries && this.isRetryable(error)) {
        await sleep(this.retryDelays[attempt]);
        return this.processWithRetry(email, attempt + 1);
      }

      await this.handleFailure(email, error);
      return { success: false, error: error.message };
    }
  }

  isRetryable(error) {
    // Retry network errors and 5xx responses
    return error.code === 'ECONNREFUSED' ||
           error.code === 'ETIMEDOUT' ||
           (error.status >= 500 && error.status < 600);
  }

  async handleFailure(email, error) {
    await storeFailedEmail(email, error);
    await alertOpsTeam(email, error);
  }
}

Extract Attachments from the Raw Message

The payload has no attachment list or attachment URLs. Attachments are only inside the raw MIME message in content.email_rfc822. Parse it with a MIME library in your background job, and store the files yourself if you need them later:

import { simpleParser } from 'mailparser';

emailQueue.process('process-inbound', async (job) => {
  const relay = job.data;

  // email_rfc822 can be base64-encoded; decode it first when flagged
  const raw = relay.content.email_rfc822_is_base64
    ? Buffer.from(relay.content.email_rfc822, 'base64')
    : relay.content.email_rfc822;

  const parsed = await simpleParser(raw);

  // Each attachment's content is a Buffer, not a URL
  const savedAttachments = await Promise.all(
    parsed.attachments.map(async (attachment) => {
      try {
        const savedPath = await saveToStorage(
          attachment.filename || 'attachment',
          attachment.content
        );
        return { filename: attachment.filename, contentType: attachment.contentType, savedPath };
      } catch (error) {
        console.error(`Failed to store ${attachment.filename}:`, error);
        return { filename: attachment.filename, error: error.message };
      }
    })
  );

  await processEmail({ relay, attachments: savedAttachments });
});

See Attachments for more on parsing attachments.

Error Handling

Graceful Degradation

Handle partial failures gracefully:

async function processEmail({ relay, attachments }) {
  const results = {
    stored: false,
    attachmentsProcessed: false,
    notificationsSent: false,
    errors: []
  };

  // Store email (critical)
  try {
    await storeEmail(relay);
    results.stored = true;
  } catch (error) {
    results.errors.push({ stage: 'store', error: error.message });
    // Fail fast for critical operations
    throw error;
  }

  // Process attachments (non-critical)
  try {
    await processAttachments(attachments);
    results.attachmentsProcessed = true;
  } catch (error) {
    results.errors.push({ stage: 'attachments', error: error.message });
    // Continue despite failure
  }

  // Send notifications (non-critical)
  try {
    await sendNotifications(relay);
    results.notificationsSent = true;
  } catch (error) {
    results.errors.push({ stage: 'notifications', error: error.message });
    // Continue despite failure
  }

  return results;
}

Structured Error Logging

function logError(context, error) {
  console.error(JSON.stringify({
    level: 'error',
    timestamp: new Date().toISOString(),
    context: {
      messageId: context.messageId, // the Message-ID header
      recipient: context.rcptTo,
      sender: context.msgFrom,
      stage: context.stage
    },
    error: {
      message: error.message,
      stack: error.stack,
      code: error.code
    }
  }));
}

Performance

Batch Database Operations

// Bad: Individual inserts
for (const email of emails) {
  await db.insert('emails', email);
}

// Good: Batch insert
await db.batchInsert('emails', emails);

Limit Concurrent Processing

import pLimit from 'p-limit';

const limit = pLimit(10); // Max 10 concurrent operations

async function processEmails(emails) {
  const promises = emails.map(email =>
    limit(() => processEmail(email))
  );

  return Promise.allSettled(promises);
}

Cache Common Lookups

import NodeCache from 'node-cache';

const customerCache = new NodeCache({ stdTTL: 300 }); // 5 minute TTL

async function getCustomer(email) {
  const domain = email.split('@')[1];

  let customer = customerCache.get(domain);
  if (!customer) {
    customer = await db.findCustomerByDomain(domain);
    if (customer) {
      customerCache.set(domain, customer);
    }
  }

  return customer;
}

Monitoring

Track Key Metrics

import { Counter, Histogram, Gauge } from 'prom-client';

const emailsReceived = new Counter({
  name: 'inbound_emails_total',
  help: 'Total inbound emails received',
  labelNames: ['domain', 'status']
});

const processingTime = new Histogram({
  name: 'inbound_email_processing_seconds',
  help: 'Email processing time',
  labelNames: ['type'],
  buckets: [0.1, 0.5, 1, 2, 5, 10]
});

const queueSize = new Gauge({
  name: 'inbound_email_queue_size',
  help: 'Current email queue size'
});

async function processEmail(relay) {
  const timer = processingTime.startTimer({ type: 'full' });
  const domain = relay.rcpt_to.split('@')[1];

  try {
    await doProcessing(relay);
    emailsReceived.inc({ domain, status: 'success' });
  } catch (error) {
    emailsReceived.inc({ domain, status: 'error' });
    throw error;
  } finally {
    timer();
  }
}

Set Up Alerts

// Alert on a high spam rate, as measured by your own spam checks
async function checkSpamRate() {
  const recent = await getRecentEmails(100);
  const spamCount = recent.filter(e => e.isSpam).length;
  const spamRate = spamCount / recent.length;

  if (spamRate > 0.3) { // 30% spam
    await alertOps({
      type: 'high_spam_rate',
      rate: spamRate,
      message: `Spam rate is ${(spamRate * 100).toFixed(1)}%`
    });
  }
}

// Alert on processing failures
async function checkFailureRate() {
  const stats = await getProcessingStats('1h');

  if (stats.failureRate > 0.05) { // 5% failure
    await alertOps({
      type: 'high_failure_rate',
      rate: stats.failureRate,
      message: `Processing failure rate is ${(stats.failureRate * 100).toFixed(1)}%`
    });
  }
}

Testing

Test Webhook Handling

import { describe, it, expect } from 'vitest';
import request from 'supertest';
import app from './app';

describe('Inbound Webhook', () => {
  const validToken = process.env.INBOUND_AUTH_TOKEN;

  it('should process valid relay event', async () => {
    const payload = [{
      msys: {
        relay_message: {
          msg_from: 'sender@example.com',
          rcpt_to: 'support@mail.example.com',
          friendly_from: 'Sender <sender@example.com>',
          content: {
            subject: 'Test email',
            text: 'Test content',
            headers: [
              { 'Message-ID': '<test-123@example.com>' }
            ],
            to: ['support@mail.example.com']
          }
        }
      }
    }];

    const response = await request(app)
      .post('/webhooks/inbound')
      .set('X-MessageSystems-Webhook-Token', validToken)
      .send(payload);

    expect(response.status).toBe(200);
  });

  it('should reject a missing auth token', async () => {
    const response = await request(app)
      .post('/webhooks/inbound')
      .send([]);

    expect(response.status).toBe(401);
  });
});

Test Edge Cases

describe('Email Processing', () => {
  it('should handle missing fields', async () => {
    const relay = {
      msg_from: 'sender@example.com',
      rcpt_to: 'support@mail.example.com',
      content: {
        to: ['support@mail.example.com'],
        headers: []
        // Missing subject, text, html
      }
    };

    const result = await processEmail(relay);
    expect(result.success).toBe(true);
  });

  it('should skip a duplicate delivery', async () => {
    const relay = {
      msg_from: 'sender@example.com',
      rcpt_to: 'support@mail.example.com',
      content: {
        subject: 'Hello',
        text: 'Hi',
        headers: [{ 'Message-ID': '<dup-1@example.com>' }]
      }
    };

    await processEmailOnce(relay);
    const second = await processEmailOnce(relay);
    expect(second.skipped).toBe(true);
  });
});

Checklist

Setup

Configure inbound domain with MX records
Set a forwarding URL on the domain and verify its auth token
Decide how your handler treats spam (Lettr does not filter it)
Set up monitoring and alerting

Processing

Implement async processing (don’t block webhooks)
Store raw emails before processing
Implement idempotency (handle duplicates)
Parse attachments from the raw MIME message
Retry your own downstream calls on transient failures

Security

Verify the X-MessageSystems-Webhook-Token auth token
Validate and sanitize all inputs
Validate attachment types from content
Implement rate limiting
Scan attachments for malware

Operations

Monitor processing metrics
Set up alerts for anomalies
Log all processing for debugging
Plan for handling failures
Document your email routing rules

Setup

Configure inbound email

Security

Security best practices

Webhooks

Webhook configuration

Sending Best Practices

Best practices for sending

Documentation

Quickstart

Learn

Integrations

Resources

Best Practices

Architecture

Process Asynchronously

Implement Idempotency

Use Separate Queues by Priority

Reliability

Store Before Processing

Retry Your Own Downstream Calls

Extract Attachments from the Raw Message

Error Handling

Graceful Degradation

Structured Error Logging

Performance

Batch Database Operations

Limit Concurrent Processing

Cache Common Lookups

Monitoring

Track Key Metrics

Set Up Alerts

Testing

Test Webhook Handling

Test Edge Cases

Checklist

Setup

Security

Webhooks

Sending Best Practices

​Architecture

​Process Asynchronously

​Implement Idempotency

​Use Separate Queues by Priority

​Reliability

​Store Before Processing

​Retry Your Own Downstream Calls

​Extract Attachments from the Raw Message

​Error Handling

​Graceful Degradation

​Structured Error Logging

​Performance

​Batch Database Operations

​Limit Concurrent Processing

​Cache Common Lookups

​Monitoring

​Track Key Metrics

​Set Up Alerts

​Testing

​Test Webhook Handling

​Test Edge Cases

​Checklist

​Related Topics

Setup

Security

Webhooks

Sending Best Practices

Architecture

Process Asynchronously

Implement Idempotency

Use Separate Queues by Priority

Reliability

Store Before Processing

Retry Your Own Downstream Calls

Extract Attachments from the Raw Message

Error Handling

Graceful Degradation

Structured Error Logging

Performance

Batch Database Operations

Limit Concurrent Processing

Cache Common Lookups

Monitoring

Track Key Metrics

Set Up Alerts

Testing

Test Webhook Handling

Test Edge Cases

Checklist

Related Topics