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

# Attachments

> Attach files to emails sent via the Paubox Email API.

You can attach files to any message sent through the Email API. Attachments are added as an `attachments` array on the message, where each entry describes a single file.

<Note>
  The total size of all attachments must not exceed **50 MB** per message. See [Limits and overage rates](/email-api/limits) for all sending limits.
</Note>

## Attachment fields

Each attachment is an object with three required fields:

| Field         | Type   | Description                                                               |
| :------------ | :----- | :------------------------------------------------------------------------ |
| `fileName`    | string | Name the recipient will see, including the extension (e.g. `report.pdf`). |
| `contentType` | string | Valid MIME type for the file, e.g. `application/pdf` or `text/plain`.     |
| `content`     | string | The file contents, Base64-encoded.                                        |

## REST API example

Add the `attachments` array to the message body. The example below attaches a small text file (`Hello World!` Base64-encoded as `SGVsbG8gV29ybGQh`):

```json theme={null}
{
  "data": {
    "message": {
      "recipients": ["recipient@host.com"],
      "headers": {
        "subject": "Sample email with an attachment",
        "from": "sender@verifieddomain.com"
      },
      "content": {
        "text/plain": "Hello World!"
      },
      "attachments": [
        {
          "fileName": "hello_world.txt",
          "contentType": "text/plain",
          "content": "SGVsbG8gV29ybGQh"
        }
      ]
    }
  }
}
```

See the full [Send a message](/email-api/messages) reference for the complete request body.

## SDK examples

Most Paubox SDKs accept attachments in the same `fileName` / `contentType` / `content` shape. The file content is always Base64-encoded.

<CodeGroup>
  ```python Python theme={null}
  import base64

  with open('report.pdf', 'rb') as f:
      encoded = base64.b64encode(f.read()).decode('utf-8')

  attachment = {
      'fileName':    'report.pdf',
      'contentType': 'application/pdf',
      'content':     encoded
  }

  # Pass attachments via the optional_headers dict
  optional_headers = {
      'attachments': [attachment]
  }
  ```

  ```javascript Node.js theme={null}
  const fs = require('fs');

  const attachment = {
    fileName: 'report.pdf',
    contentType: 'application/pdf',
    content: fs.readFileSync('report.pdf').toString('base64')
  };

  const options = {
    attachments: [attachment]
  };
  ```
</CodeGroup>

For language-specific details, see each SDK's email client guide — for example the [Python SDK](/python-sdk/email-client) or [Node.js SDK](/node-sdk/email-client).

## Sending from the CLI

The Paubox CLI accepts files directly with the `--attachment` flag and handles the Base64 encoding for you:

```bash theme={null}
paubox send \
  --from sender@verifieddomain.com \
  --to recipient@host.com \
  --subject "Sample email with an attachment" \
  --text "Hello World!" \
  --attachment report.pdf
```

See the [CLI commands reference](/cli/commands) for all available flags.