> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lettr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Attachments

> Attach invoices, receipts, reports, and other files to your emails as base64-encoded content directly in the Lettr send request

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:

```javascript theme={null}
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

```javascript theme={null}
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:

```json theme={null}
{
  "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](https://docs.lettr.com/quickstart/smtp/introduction.md), 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:

```javascript theme={null}
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" />'
});
```

> [!NOTE]
>
> 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 |

> [!WARNING]
>
> 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](#inline-images).

```javascript theme={null}
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:

```json theme={null}
{
  "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."]
  }
}
```

> [!TIP]
>
> 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` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.