Attachments

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.

The whole request body, including Base64-encoded attachments, must not exceed 50 MB. Base64 adds about a third to file size, so plan for roughly 37 MB of raw files per message. See Limits and overage rates for all sending limits.

Attachment fields

Each attachment is an object with three required fields and two optional ones:

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.
`disposition`	string	Optional. `attachment` (default) or `inline`.
`contentId`	string	Required when `disposition` is `inline`. The ID you reference from your HTML.

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):

{
  "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 reference for the complete request body.

Inline images

To embed an image in the HTML body, set disposition to inline, give it a contentId, and reference that ID with a cid: URL. Inline attachments must use an image/* contentType; otherwise the request returns 400.

{
  "data": {
    "message": {
      "recipients": ["recipient@host.com"],
      "headers": {
        "subject": "Sample email with an inline image",
        "from": "sender@verifieddomain.com"
      },
      "content": {
        "text/html": "<html><body><img src=\"cid:logo\"></body></html>"
      },
      "attachments": [
        {
          "fileName": "logo.png",
          "contentType": "image/png",
          "content": "BASE64_ENCODED_IMAGE",
          "disposition": "inline",
          "contentId": "logo"
        }
      ]
    }
  }
}

SDK examples

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

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]
}

const fs = require('fs');

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

const options = {
  attachments: [attachment]
};

For language-specific details, see each SDK’s email client guide — for example the Python SDK or Node.js SDK.

Sending from the CLI

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

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 for all available flags.

Get started

Email API

Migrate to Paubox

Marketing API

MCP Server

SDKs

CLI

Forms API

Attachment fields

REST API example

Inline images

SDK examples

Sending from the CLI

​Attachment fields

​REST API example

​Inline images

​SDK examples

​Sending from the CLI

Attachment fields

REST API example

Inline images

SDK examples

Sending from the CLI