Attachments

Attachments on inbound emails are not delivered as separate files or download links. Every inbound email reaches your forwarding URL as one JSON payload, and the files are inside the complete raw message in content.email_rfc822. To get them, decode that field if needed and parse it with a MIME library in your handler. Lettr does not store attachments, so there is nothing to download later. Whatever your code does not keep when it handles the delivery is gone.

Where Attachments Live

Your forwarding URL receives a JSON array of events, each with a msys.relay_message object (see Email Parsing for every field). The fields that matter for attachments are:

[
  {
    "msys": {
      "relay_message": {
        "msg_from": "sender@example.com",
        "rcpt_to": "invoices@inbound.example.com",
        "content": {
          "subject": "March invoice",
          "text": "Invoice attached.",
          "email_rfc822": "TUlNRS1WZXJzaW9uOiAxLjAKRnJvbTogLi4u...",
          "email_rfc822_is_base64": true
        }
      }
    }
  }
]

Field	Type	Description
`content.email_rfc822`	string	The complete raw MIME message, including every attachment and inline image
`content.email_rfc822_is_base64`	boolean	When `true`, base64-decode `email_rfc822` before parsing it

The text and html fields only carry the message body. There is no attachments field in the payload.

The whole message, attachments included, arrives in a single request body. Make sure your web server and framework accept request bodies as large as the biggest email you want to receive. Express’s express.json(), for example, rejects bodies over 100 KB unless you raise its limit.

Extracting Attachments

The steps are the same in every language:

Loop over the events in the JSON array.
Read content.email_rfc822 and base64-decode it if content.email_rfc822_is_base64 is true.
Parse the raw message with a MIME library and read its attachment parts.

import express from 'express';
import { simpleParser } from 'mailparser';

const app = express();

// The raw message sits inside the JSON body, so raise the default 100 KB limit
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 parsed = await parseRawEmail(relay);

    for (const attachment of parsed.attachments) {
      console.log(
        attachment.filename,           // may be undefined
        attachment.contentType,        // e.g. "application/pdf"
        attachment.size,               // bytes, after decoding
        attachment.contentDisposition, // "attachment" or "inline"
        attachment.cid                 // Content-ID for inline images
      );
      // attachment.content is a Buffer with the file data
    }
  }

  res.sendStatus(200);
});

export function parseRawEmail(relay) {
  const { email_rfc822, email_rfc822_is_base64 } = relay.content;

  const raw = email_rfc822_is_base64
    ? Buffer.from(email_rfc822, 'base64')
    : email_rfc822;

  return simpleParser(raw);
}

import base64
from email import message_from_bytes, policy

from flask import Flask, request

app = Flask(__name__)


def parse_raw_email(relay):
    content = relay["content"]
    raw = content["email_rfc822"]

    if content.get("email_rfc822_is_base64"):
        raw_bytes = base64.b64decode(raw)
    else:
        raw_bytes = raw.encode("utf-8")

    return message_from_bytes(raw_bytes, policy=policy.default)


@app.post("/webhooks/inbound")
def inbound():
    for event in request.get_json():
        relay = event.get("msys", {}).get("relay_message")
        if relay is None:
            continue

        message = parse_raw_email(relay)

        for part in message.iter_attachments():
            filename = part.get_filename()             # may be None
            content_type = part.get_content_type()     # e.g. "application/pdf"
            disposition = part.get_content_disposition()  # "attachment" or "inline"
            content_id = part.get("Content-ID")        # for inline images
            data = part.get_payload(decode=True) or b""  # bytes

            print(filename, content_type, disposition, len(data))

    return "", 200

<?php

// composer require zbateson/mail-mime-parser
require 'vendor/autoload.php';

use ZBateson\MailMimeParser\Message;

function parseRawEmail(array $relay): Message
{
    $content = $relay['content'];
    $raw = $content['email_rfc822'];

    if (!empty($content['email_rfc822_is_base64'])) {
        $raw = base64_decode($raw);
    }

    return Message::from($raw, false);
}

$events = json_decode(file_get_contents('php://input'), true);

foreach ($events as $event) {
    $relay = $event['msys']['relay_message'] ?? null;
    if ($relay === null) {
        continue;
    }

    $message = parseRawEmail($relay);

    foreach ($message->getAllAttachmentParts() as $part) {
        $filename = $part->getFilename();               // may be null
        $contentType = $part->getContentType();         // e.g. "application/pdf"
        $disposition = $part->getContentDisposition();  // "attachment" or "inline"
        $contentId = $part->getContentId();             // for inline images
        $data = $part->getBinaryContentStream()?->getContents() ?? ''; // decoded bytes

        error_log("{$filename} {$contentType} " . strlen($data) . ' bytes');
    }
}

http_response_code(200);

Python’s iter_attachments() only looks at the top level of the message. Inline images usually sit deeper, inside a multipart/related part, so use message.walk() to find them (see Inline Images). mailparser and mail-mime-parser return both regular attachments and inline images.

Respond First, Process Later

Answer the delivery with a 2xx as soon as you have the payload, and do slow work such as uploads, virus scans and file conversion in a background job. The same email can be delivered more than once, so key whatever you store on the email’s Message-ID header to avoid saving the same files twice.

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) {
      await queue.add('inbound-email', relay); // your job queue
    }
  }

  res.sendStatus(200);
});

// In your worker (parseRawEmail is defined above)
async function handleInboundEmail(relay) {
  const parsed = await parseRawEmail(relay);
  const messageId = parsed.messageId; // from the Message-ID header

  if (await alreadyProcessed(messageId)) return;

  for (const attachment of parsed.attachments) {
    await saveAttachment(messageId, attachment);
  }

  await markProcessed(messageId);
}

Storing Attachments

Store every file you want to keep in your own storage while you handle the delivery. Use a key you generate yourself rather than the sender’s filename, and keep the original filename as metadata.

Save to Local Filesystem

import fs from 'fs/promises';
import path from 'path';
import { randomUUID } from 'crypto';

async function saveAttachmentLocally(attachment, directory = './attachments') {
  const safeFilename = sanitizeFilename(attachment.filename ?? 'attachment');
  const filepath = path.join(directory, `${randomUUID()}-${safeFilename}`);

  await fs.writeFile(filepath, attachment.content);

  return filepath;
}

function sanitizeFilename(filename) {
  return filename
    .replace(/[^a-zA-Z0-9.-]/g, '_')
    .substring(0, 200);
}

Save to Cloud Storage (AWS S3)

import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
import { randomUUID } from 'crypto';

const s3 = new S3Client({ region: 'us-east-1' });

async function saveToS3(attachment, messageId) {
  const key = `inbound/${randomUUID()}`;

  await s3.send(new PutObjectCommand({
    Bucket: 'your-bucket',
    Key: key,
    Body: attachment.content,
    ContentType: attachment.contentType,
    Metadata: {
      'original-filename': encodeURIComponent(attachment.filename ?? ''),
      'message-id': encodeURIComponent(messageId ?? '')
    }
  }));

  return `s3://your-bucket/${key}`;
}

Save to Cloud Storage (Google Cloud)

import { Storage } from '@google-cloud/storage';
import { randomUUID } from 'crypto';

const bucket = new Storage().bucket('your-bucket');

async function saveToGCS(attachment, messageId) {
  const name = `inbound/${randomUUID()}`;

  await bucket.file(name).save(attachment.content, {
    contentType: attachment.contentType,
    metadata: {
      metadata: {
        originalFilename: attachment.filename ?? '',
        messageId: messageId ?? ''
      }
    }
  });

  return `gs://your-bucket/${name}`;
}

Validating Attachments

Lettr passes on whatever the sender attached, so deciding which files you accept is up to your code. Check the type and size of each file before you process it, using limits that suit your application.

const ALLOWED_TYPES = [
  'application/pdf',
  'image/jpeg',
  'image/png',
  'image/gif',
  'text/plain',
  'text/csv',
  'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
];

const MAX_SIZE = 10 * 1024 * 1024; // your own limit, here 10 MB

function validateAttachment(attachment) {
  const errors = [];

  if (!ALLOWED_TYPES.includes(attachment.contentType)) {
    errors.push(`Unsupported file type: ${attachment.contentType}`);
  }

  if (attachment.size > MAX_SIZE) {
    errors.push(`File too large: ${attachment.size} bytes (max ${MAX_SIZE})`);
  }

  if (!attachment.filename || attachment.filename.length > 255) {
    errors.push('Missing or invalid filename');
  }

  return { valid: errors.length === 0, errors };
}

async function handleInboundEmail(relay) {
  const parsed = await parseRawEmail(relay);

  for (const attachment of parsed.attachments) {
    const validation = validateAttachment(attachment);

    if (!validation.valid) {
      console.warn(`Skipping attachment: ${validation.errors.join(', ')}`);
      continue;
    }

    await processAttachment(attachment);
  }
}

Security Considerations

Filenames, content types and file contents all come from the sender. Never trust them. Validate and sanitize before you store, open or serve a file.

Virus Scanning

Scan files for malware in your handler before storing them, for example with ClamAV:

import NodeClam from 'clamscan';

const clamscan = await new NodeClam().init({
  clamdscan: {
    host: 'localhost',
    port: 3310
  }
});

async function scanAndSave(attachment) {
  const { isInfected, viruses } = await clamscan.scanBuffer(attachment.content);

  if (isInfected) {
    console.error(`Infected file detected: ${viruses.join(', ')}`);
    await quarantineAttachment(attachment, viruses);
    return { saved: false, reason: 'malware_detected' };
  }

  await saveToStorage(attachment);
  return { saved: true };
}

File Type Verification

The Content-Type of an attachment is whatever the sender’s mail client wrote. Check the actual bytes against it:

import { fileTypeFromBuffer } from 'file-type';

async function verifyFileType(attachment) {
  const detected = await fileTypeFromBuffer(attachment.content);

  if (detected && detected.mime !== attachment.contentType) {
    console.warn(
      `Content type mismatch: declared ${attachment.contentType}, detected ${detected.mime}`
    );
    return false;
  }

  return true;
}

Inline Images

Images embedded in an HTML email (logos, signatures, pasted screenshots) are MIME parts with a Content-ID header. The HTML body refers to them as cid: URLs, for example <img src="cid:logo@example.com">, so content.html in the payload contains those references but not the images. You find the images in email_rfc822. With mailparser, inline images are part of parsed.attachments. Each has cid set and related: true. By default simpleParser also rewrites the cid: links in parsed.html into data: URLs, so the HTML displays on its own. To store the images and point the HTML at your own copies, keep the links and replace them yourself:

import { simpleParser } from 'mailparser';

async function htmlWithStoredImages(relay) {
  const { email_rfc822, email_rfc822_is_base64 } = relay.content;
  const raw = email_rfc822_is_base64 ? Buffer.from(email_rfc822, 'base64') : email_rfc822;

  const parsed = await simpleParser(raw, { keepCidLinks: true });
  let html = parsed.html || '';

  for (const attachment of parsed.attachments) {
    if (!attachment.cid) continue;

    const url = await uploadToYourStorage(attachment); // returns a public URL
    html = html.replaceAll(`cid:${attachment.cid}`, url);
  }

  return html;
}

In Python, walk the whole message to find parts with a Content-ID:

def inline_images(message):
    for part in message.walk():
        content_id = part.get("Content-ID")
        if content_id and part.get_content_maintype() == "image":
            yield content_id.strip("<>"), part.get_content_type(), part.get_payload(decode=True)

Processing Specific File Types

Once you have an attachment’s bytes, process them with whatever library fits. The examples below use mailparser attachments, where attachment.content is a Buffer.

PDF Documents

import pdf from 'pdf-parse';

async function extractPdfText(attachment) {
  const data = await pdf(attachment.content);

  return {
    text: data.text,
    pages: data.numpages,
    info: data.info
  };
}

Images

import sharp from 'sharp';

async function processImage(attachment) {
  const metadata = await sharp(attachment.content).metadata();

  const thumbnail = await sharp(attachment.content)
    .resize(200, 200, { fit: 'inside' })
    .jpeg({ quality: 80 })
    .toBuffer();

  return { metadata, thumbnail };
}

CSV Files

import { parse } from 'csv-parse/sync';

function parseCsv(attachment) {
  return parse(attachment.content.toString('utf-8'), {
    columns: true,
    skip_empty_lines: true
  });
}

Complete Example

An Express endpoint that acknowledges the delivery right away and a worker that extracts PDF and image attachments, deduplicates on Message-ID, and uploads the files to S3:

import express from 'express';
import { simpleParser } from 'mailparser';
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
import { randomUUID } from 'crypto';

const app = express();
const s3 = new S3Client({ region: 'us-east-1' });

const ALLOWED_TYPES = ['application/pdf', 'image/jpeg', 'image/png'];
const MAX_SIZE = 10 * 1024 * 1024; // your own limit

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) {
      await queue.add('inbound-email', relay); // your job queue
    }
  }

  res.sendStatus(200);
});

// Runs in your queue worker
export async function handleInboundEmail(relay) {
  const { email_rfc822, email_rfc822_is_base64 } = relay.content;
  const raw = email_rfc822_is_base64 ? Buffer.from(email_rfc822, 'base64') : email_rfc822;

  const parsed = await simpleParser(raw);
  const messageId = parsed.messageId;

  if (await alreadyProcessed(messageId)) return;

  const savedAttachments = [];

  for (const attachment of parsed.attachments) {
    if (attachment.related) continue; // skip inline images

    if (!ALLOWED_TYPES.includes(attachment.contentType)) {
      console.warn(`Skipping unsupported type: ${attachment.contentType}`);
      continue;
    }

    if (attachment.size > MAX_SIZE) {
      console.warn(`Skipping large file: ${attachment.filename}`);
      continue;
    }

    const key = `inbound/${randomUUID()}`;

    await s3.send(new PutObjectCommand({
      Bucket: 'my-bucket',
      Key: key,
      Body: attachment.content,
      ContentType: attachment.contentType
    }));

    savedAttachments.push({
      filename: attachment.filename,
      s3Key: key,
      size: attachment.size
    });
  }

  await saveEmailRecord({
    messageId,
    from: relay.friendly_from,
    to: relay.rcpt_to,
    subject: relay.content.subject,
    attachments: savedAttachments
  });
}

Email Parsing

Every field in the inbound payload

Security

Security best practices

Best Practices

Inbound best practices

Sending Attachments

Attach files to outgoing emails

Documentation

Quickstart

Learn

Integrations

Resources

Where Attachments Live

Extracting Attachments

Respond First, Process Later

Storing Attachments

Save to Local Filesystem

Save to Cloud Storage (AWS S3)

Save to Cloud Storage (Google Cloud)

Validating Attachments

Security Considerations

Virus Scanning

File Type Verification

Inline Images

Processing Specific File Types

PDF Documents

Images

CSV Files

Complete Example

Email Parsing

Security

Best Practices

Sending Attachments

Where Attachments Live

Extracting Attachments

Respond First, Process Later

Storing Attachments

Save to Local Filesystem

Save to Cloud Storage (AWS S3)

Save to Cloud Storage (Google Cloud)

Validating Attachments

Security Considerations

Virus Scanning

File Type Verification

Inline Images

Processing Specific File Types

PDF Documents

Images

CSV Files

Complete Example

Related Topics

Email Parsing

Security

Best Practices

Sending Attachments