Security

Receiving emails from external sources introduces security considerations. This guide covers best practices for securing your inbound email processing pipeline.

Forwarding URL Security

Verify the Auth Token

Always verify that requests to your forwarding URL come from Lettr, not malicious actors. When you create an inbound domain, or later on the domain’s Mail Forwarding card, set an Auth token. Lettr sends it with every request in the X-MessageSystems-Webhook-Token header. Compare it against your stored value and reject anything that doesn’t match:

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

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

  // Constant-time comparison to avoid timing attacks
  if (
    token.length !== expected.length ||
    !crypto.timingSafeEqual(Buffer.from(token), Buffer.from(expected))
  ) {
    return res.sendStatus(401);
  }

  next();
}

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

    await processEmail(relay);
  }

  res.sendStatus(200);
});

Lettr doesn’t store your auth token, so keep your own copy (for example in an environment variable). To rotate it, enter a new token on the Mail Forwarding card and click Save forwarding URL. Leaving the field blank keeps the token that is already set.

Don’t Rely on IP Allowlisting

Inbound mail is posted to your forwarding URL by SparkPost, the mail infrastructure behind Lettr’s inbound servers, and SparkPost publishes no fixed source IP addresses. An IP allowlist can’t reliably identify these requests, so use the auth token instead. If your endpoint sits behind Cloudflare or another firewall/WAF, allow server-to-server POST requests on your forwarding URL’s path. Otherwise the firewall may answer with a challenge page, and a non-2xx response makes the forwarding URL test fail when you create the domain or save a new URL.

Input Validation

Validate Email Addresses

Never trust email addresses from inbound emails:

function validateEmailAddress(email) {
  if (!email || typeof email !== 'string') {
    return false;
  }

  // Basic format check
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  if (!emailRegex.test(email)) {
    return false;
  }

  // Length limits
  if (email.length > 254) {
    return false;
  }

  const [localPart, domain] = email.split('@');
  if (localPart.length > 64 || domain.length > 255) {
    return false;
  }

  return true;
}

Sanitize Email Content

Sanitize HTML content before displaying or storing:

import DOMPurify from 'isomorphic-dompurify';

function sanitizeHtml(html) {
  return DOMPurify.sanitize(html, {
    ALLOWED_TAGS: [
      'p', 'br', 'b', 'i', 'u', 'strong', 'em',
      'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
      'ul', 'ol', 'li', 'a', 'img', 'blockquote',
      'table', 'thead', 'tbody', 'tr', 'th', 'td',
      'span', 'div'
    ],
    ALLOWED_ATTR: ['href', 'src', 'alt', 'class', 'style'],
    ALLOW_DATA_ATTR: false,
    FORBID_TAGS: ['script', 'iframe', 'object', 'embed', 'form'],
    FORBID_ATTR: ['onerror', 'onload', 'onclick']
  });
}

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

    const { html, text } = relay.content;

    // Sanitize before storing
    const safeHtml = html ? sanitizeHtml(html) : null;
    const safeText = text ? escapeHtml(text) : null;

    await storeEmail({ html: safeHtml, text: safeText });
  }

  res.sendStatus(200);
});

Validate and Sanitize Filenames

Never use attachment filenames directly:

import path from 'path';

function sanitizeFilename(filename) {
  if (!filename || typeof filename !== 'string') {
    return 'unnamed_file';
  }

  // Remove directory traversal attempts
  let safe = path.basename(filename);

  // Remove dangerous characters
  safe = safe.replace(/[<>:"/\\|?*\x00-\x1f]/g, '_');

  // Limit length
  safe = safe.substring(0, 200);

  // Ensure not empty
  if (!safe || safe === '.' || safe === '..') {
    safe = 'unnamed_file';
  }

  return safe;
}

// Generate unique filenames to prevent overwrites
function generateSafeFilename(originalFilename) {
  const safe = sanitizeFilename(originalFilename);
  const ext = path.extname(safe);
  const base = path.basename(safe, ext);
  const timestamp = Date.now();
  const random = crypto.randomBytes(4).toString('hex');

  return `${base}_${timestamp}_${random}${ext}`;
}

Attachment Security

Validate File Types

Never trust the declared content type:

import { fileTypeFromBuffer } from 'file-type';

const ALLOWED_TYPES = new Map([
  ['application/pdf', ['.pdf']],
  ['image/jpeg', ['.jpg', '.jpeg']],
  ['image/png', ['.png']],
  ['image/gif', ['.gif']],
  ['text/plain', ['.txt']],
  ['text/csv', ['.csv']]
]);

async function validateAttachment(attachment) {
  const response = await fetch(attachment.url);
  const buffer = Buffer.from(await response.arrayBuffer());

  // Detect actual file type from content
  const detected = await fileTypeFromBuffer(buffer);

  if (!detected) {
    // Could be text file
    if (attachment.contentType.startsWith('text/')) {
      return { valid: true, type: attachment.contentType };
    }
    return { valid: false, reason: 'Unknown file type' };
  }

  // Check if type is allowed
  if (!ALLOWED_TYPES.has(detected.mime)) {
    return { valid: false, reason: `File type not allowed: ${detected.mime}` };
  }

  // Verify declared type matches detected type
  if (detected.mime !== attachment.contentType) {
    console.warn(
      `Content-Type mismatch: declared ${attachment.contentType}, detected ${detected.mime}`
    );
    // Use detected type, not declared type
  }

  return { valid: true, type: detected.mime, buffer };
}

Scan for Malware

Integrate with a virus scanner:

import ClamScan from 'clamscan';

const clamscan = await new ClamScan().init({
  clamdscan: {
    host: process.env.CLAMAV_HOST || 'localhost',
    port: 3310
  }
});

async function scanForMalware(buffer, filename) {
  try {
    const { isInfected, viruses } = await clamscan.scanBuffer(buffer);

    if (isInfected) {
      console.error(`Malware detected in ${filename}: ${viruses.join(', ')}`);
      return {
        safe: false,
        threats: viruses
      };
    }

    return { safe: true };
  } catch (error) {
    console.error('Virus scan failed:', error);
    // Fail closed - treat as unsafe if scanning fails
    return { safe: false, error: 'Scan failed' };
  }
}

Limit File Sizes

Enforce size limits to prevent resource exhaustion:

const MAX_ATTACHMENT_SIZE = 10 * 1024 * 1024; // 10 MB
const MAX_TOTAL_SIZE = 25 * 1024 * 1024; // 25 MB

function validateAttachmentSizes(attachments) {
  let totalSize = 0;

  for (const attachment of attachments) {
    if (attachment.size > MAX_ATTACHMENT_SIZE) {
      return {
        valid: false,
        reason: `Attachment ${attachment.filename} exceeds size limit`
      };
    }
    totalSize += attachment.size;
  }

  if (totalSize > MAX_TOTAL_SIZE) {
    return {
      valid: false,
      reason: `Total attachment size exceeds limit`
    };
  }

  return { valid: true };
}

Content Security

Prevent XSS in Displayed Emails

When displaying email content in a web interface:

// Use CSP headers
app.use((req, res, next) => {
  res.setHeader(
    'Content-Security-Policy',
    "default-src 'self'; img-src 'self' https:; style-src 'self' 'unsafe-inline'"
  );
  next();
});

// Render emails in sandboxed iframe
function renderEmailHtml(sanitizedHtml) {
  return `
    <iframe
      sandbox="allow-same-origin"
      srcdoc="${escapeAttribute(sanitizedHtml)}"
      style="width: 100%; height: 500px; border: none;"
    ></iframe>
  `;
}

Block Tracking Pixels

Strip tracking pixels from received emails:

function removeTrackingPixels(html) {
  // Remove 1x1 images (common tracking pixels)
  html = html.replace(
    /<img[^>]*(?:width|height)\s*=\s*["']?1["']?[^>]*>/gi,
    ''
  );

  // Remove images from known tracking domains
  const trackingDomains = [
    'mailtrack.io',
    'pixel.watch',
    'track.customer.io',
    'open.convertkit.com'
  ];

  for (const domain of trackingDomains) {
    const regex = new RegExp(`<img[^>]*${domain}[^>]*>`, 'gi');
    html = html.replace(regex, '');
  }

  return html;
}

Rate Limiting

Protect against email flooding:

import { RateLimiterRedis } from 'rate-limiter-flexible';
import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);

const senderLimiter = new RateLimiterRedis({
  storeClient: redis,
  keyPrefix: 'inbound_sender',
  points: 100, // 100 emails
  duration: 3600 // per hour
});

const domainLimiter = new RateLimiterRedis({
  storeClient: redis,
  keyPrefix: 'inbound_domain',
  points: 500,
  duration: 3600
});

const globalLimiter = new RateLimiterRedis({
  storeClient: redis,
  keyPrefix: 'inbound_global',
  points: 10000,
  duration: 3600
});

async function checkRateLimits(email) {
  const sender = email.from.toLowerCase();
  const domain = sender.split('@')[1];

  try {
    await Promise.all([
      senderLimiter.consume(sender),
      domainLimiter.consume(domain),
      globalLimiter.consume('global')
    ]);
    return { allowed: true };
  } catch (error) {
    return {
      allowed: false,
      reason: 'Rate limit exceeded',
      retryAfter: Math.ceil(error.msBeforeNext / 1000)
    };
  }
}

Logging and Monitoring

Audit Logging

Log all inbound email processing:

async function logInboundEmail(email, result) {
  await auditLog.create({
    type: 'inbound_email',
    emailId: email.id,
    from: email.from,
    to: email.to,
    subject: email.subject?.substring(0, 100),
    attachmentCount: email.attachments?.length || 0,
    result: result.status,
    processingTime: result.duration,
    timestamp: new Date()
  });
}

Anomaly Detection

Monitor for suspicious patterns:

class AnomalyDetector {
  constructor() {
    this.senderHistory = new Map();
  }

  async analyze(email) {
    const sender = email.from.toLowerCase();
    const alerts = [];

    // Track sender frequency
    const history = this.senderHistory.get(sender) || { count: 0, firstSeen: Date.now() };
    history.count++;
    this.senderHistory.set(sender, history);

    // New sender sending many emails quickly
    if (history.count > 10 && Date.now() - history.firstSeen < 60000) {
      alerts.push({
        type: 'rapid_sender',
        sender,
        count: history.count,
        duration: Date.now() - history.firstSeen
      });
    }

    // Unusual attachment patterns
    if (email.attachments?.length > 5) {
      alerts.push({
        type: 'many_attachments',
        sender,
        count: email.attachments.length
      });
    }

    return alerts;
  }
}

Security Checklist

Forwarding URL Security

Set an auth token and verify the X-MessageSystems-Webhook-Token header on every request
Store the token securely in environment variables
Use HTTPS for your forwarding URL
Allow server-to-server POST requests through your firewall or WAF instead of relying on an IP allowlist

Input Validation

Validate all email addresses
Sanitize HTML content before storage/display
Sanitize filenames before use
Validate attachment content types

Attachment Security

Verify file types from content, not headers
Scan attachments for malware
Enforce size limits
Store attachments outside web root

Monitoring

Log all inbound email processing
Monitor for rate limit violations
Alert on anomalous patterns
Track spam score distributions

Never trust any data from inbound emails. Senders can forge headers, spoof addresses, and include malicious content. Always validate and sanitize everything.

Inbound Setup

Set the forwarding URL and auth token

Spam Filtering

Filter spam emails

Attachments

Handle attachments safely

Best Practices

Overall best practices

Documentation

Quickstart

Learn

Integrations

Resources

Forwarding URL Security

Verify the Auth Token

Don’t Rely on IP Allowlisting

Input Validation

Validate Email Addresses

Sanitize Email Content

Validate and Sanitize Filenames

Attachment Security

Validate File Types

Scan for Malware

Limit File Sizes

Content Security

Prevent XSS in Displayed Emails

Block Tracking Pixels

Rate Limiting

Logging and Monitoring

Audit Logging

Anomaly Detection

Security Checklist

Inbound Setup

Spam Filtering

Attachments

Best Practices

​Forwarding URL Security

​Verify the Auth Token

​Don’t Rely on IP Allowlisting

​Input Validation

​Validate Email Addresses

​Sanitize Email Content

​Validate and Sanitize Filenames

​Attachment Security

​Validate File Types

​Scan for Malware

​Limit File Sizes

​Content Security

​Prevent XSS in Displayed Emails

​Block Tracking Pixels

​Rate Limiting

​Logging and Monitoring

​Audit Logging

​Anomaly Detection

​Security Checklist

​Related Topics

Inbound Setup

Spam Filtering

Attachments

Best Practices

Forwarding URL Security

Verify the Auth Token

Don’t Rely on IP Allowlisting

Input Validation

Validate Email Addresses

Sanitize Email Content

Validate and Sanitize Filenames

Attachment Security

Validate File Types

Scan for Malware

Limit File Sizes

Content Security

Prevent XSS in Displayed Emails

Block Tracking Pixels

Rate Limiting

Logging and Monitoring

Audit Logging

Anomaly Detection

Security Checklist

Related Topics