Attachments

Many transactional emails need to include files — invoices after a purchase, receipts for payments, reports generated on demand, or contracts that need a signature. Lettr supports base64-encoded file attachments, so you can attach files directly in your API request.

Basic Attachment

Attach files using base64-encoded content:

import fs from 'fs';

const fileContent = fs.readFileSync('invoice.pdf');
const base64Content = fileContent.toString('base64');

await lettr.emails.send({
  from: 'you@example.com',
  to: ['recipient@example.com'],
  subject: 'Your Invoice',
  html: '<p>Please find your invoice attached.</p>',
  attachments: [
    {
      name: 'invoice.pdf',
      data: base64Content,
      type: 'application/pdf'
    }
  ]
});

Multiple Attachments

await lettr.emails.send({
  from: 'you@example.com',
  to: ['recipient@example.com'],
  subject: 'Project Files',
  html: '<p>Here are the requested files.</p>',
  attachments: [
    {
      name: 'report.pdf',
      data: reportBase64,
      type: 'application/pdf'
    },
    {
      name: 'data.xlsx',
      data: excelBase64,
      type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
    },
    {
      name: 'image.png',
      data: imageBase64,
      type: 'image/png'
    }
  ]
});

Inline Images

To show an attachment inside the body of the email instead of as a separate file, give the image attachment a content_id and reference it from your HTML with a cid: URL:

{
  "from": "you@example.com",
  "to": ["recipient@example.com"],
  "subject": "Your order has shipped",
  "html": "<img src=\"cid:logo@example.com\" alt=\"Acme\" /><p>Your order is on its way.</p>",
  "attachments": [
    {
      "name": "logo.png",
      "type": "image/png",
      "data": "iVBORw0KGgoAAAANSUhEUgAA...",
      "content_id": "logo@example.com"
    }
  ]
}

content_id only works on image attachments (a type starting with image/).
It can be up to 255 printable ASCII characters, without spaces or angle brackets. Don’t include the < > brackets you may see in raw MIME headers.
Each inline image in a request needs its own unique content_id.
Attachments without a content_id are delivered as regular attachments, as before.

A content_id that breaks these rules fails with a 422 validation error on attachments.N.content_id, and the email is not sent.

Over SMTP

When you send over SMTP, embedded images created by your mail library (for example, PHPMailer’s addEmbeddedImage() or Laravel’s $message->embed()) keep their Content-ID, so cid: references in your HTML display inline. You don’t need to change anything.

Hosted Images

You can also host the image at a public URL and reference that URL directly, which keeps the message smaller:

await lettr.emails.send({
  from: 'you@example.com',
  to: ['recipient@example.com'],
  subject: 'Email with Image',
  html: '<p>Check out this image:</p><img src="https://cdn.example.com/logo.png" alt="Logo" />'
});

Many email clients block remote images by default and ask the recipient to “display images.” An alt attribute keeps the message readable when the image is blocked.

Attachment Limits

Limit	Value
Max total size (after Base64 encoding)	5 MB
Max attachment name length	255 characters

Large attachments can affect deliverability and may be blocked by recipient email servers. Consider using download links for large files.

Attachments vs. Download Links

Not every file belongs as an attachment. Consider which approach fits your use case:

Factor	Attachment	Download Link
File size	Best for files under 10 MB	Better for large files
Offline access	Recipient has the file immediately	Requires internet to download
Deliverability	Large attachments may be blocked	No impact on email delivery
Tracking	No download tracking	Can track link clicks
Expiration	File persists in recipient’s inbox	Link can expire for security

Use attachments for: invoices, receipts, tickets, and small documents the recipient needs to keep. Use download links for: large reports, media files, archives, and files that should expire after a set period.

Attachment Format

Attachments are included as base64-encoded content in the API request. Each attachment requires three fields:

name — The filename the recipient will see (max 255 characters)
data — The file content encoded as base64 (must not contain \r\n characters)
type — The MIME type of the file

An image attachment can also have an optional content_id to display it inline — see Inline Images.

attachments: [{ name: 'invoice.pdf', data: base64String, type: 'application/pdf' }]

Error Handling

When an attachment fails validation, the API returns an error and the email is not sent:

{
  "error_code": "validation_error",
  "message": "The given data was invalid.",
  "errors": {
    "attachments.0.data": ["The attachments.0.data field must be a valid base64 string."],
    "attachments.0.name": ["The attachments.0.name field is required."]
  }
}

Validate file sizes and ensure base64 encoding does not contain \r\n characters before calling the API to avoid failed sends.

Common MIME Types

Extension	MIME Type
`.pdf`	`application/pdf`
`.doc`	`application/msword`
`.docx`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
`.xls`	`application/vnd.ms-excel`
`.xlsx`	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
`.png`	`image/png`
`.jpg`	`image/jpeg`
`.gif`	`image/gif`
`.zip`	`application/zip`
`.csv`	`text/csv`

Documentation

Quickstart

Learn

Integrations

Resources

Basic Attachment

Multiple Attachments

Inline Images

Over SMTP

Hosted Images

Attachment Limits

Attachments vs. Download Links

Attachment Format

Error Handling

Common MIME Types

​Basic Attachment

​Multiple Attachments

​Inline Images

​Over SMTP

​Hosted Images

​Attachment Limits

​Attachments vs. Download Links

​Attachment Format

​Error Handling

​Common MIME Types

Basic Attachment

Multiple Attachments

Inline Images

Over SMTP

Hosted Images

Attachment Limits

Attachments vs. Download Links

Attachment Format

Error Handling

Common MIME Types