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

# Attachments

> Send, upload, and download attachments with Qubrics.

For the Sending API, upload file bytes first and send by `attachment_id`. Inline base64 attachments remain supported for small generated content and older integrations, but uploaded refs are the preferred path for normal files. Direct and delegated binary uploads require the exact `Content-Length`; Qubrics SDK and CLI file helpers calculate it from the local file.

## Limits

| Limit | Value |
| - | - |
| Attachments per email | 10 |
| Sending API binary upload | 18 MiB |
| Final sent message | 25 MB |
| Mailbox upload attachment | 7,500,000 bytes |

Base64 content counts towards the request body size and increases payload size. Upload refs avoid that overhead, but the final encoded email must still fit within the 25 MB message limit.

Mailbox attachment uploads are available for mailbox send workflows that need to upload a file first and then reference the returned blob ID when sending. Direct mailbox uploads and presigned mailbox uploads use the same per-attachment cap.

## Upload before sending with the Sending API

Upload bytes directly when your client has the API key:

```bash theme={null}
SIZE_BYTES="$(wc -c < invoice.pdf | tr -d ' ')"
ATTACHMENT_ID="$(
  curl -sS -X POST "https://smtp.qubrics.com/api/v1/emails/attachments?filename=invoice.pdf" \
    --header @- \
    -H "Content-Type: application/pdf" \
    -H "Content-Length: $SIZE_BYTES" \
    --data-binary @invoice.pdf <<< "Authorization: Bearer $QUBRICS_API_KEY" \
  | jq -r '.data.attachment_id'
)"
```

Then reference it from `POST /emails/send` or `POST /emails/send/batch`:

```json theme={null}
{
  "from": { "email": "hello@example.com" },
  "to": { "email": "user@example.com" },
  "subject": "Invoice attached",
  "html_body": "<p>Please find your invoice attached.</p>",
  "attachments": [{ "attachment_id": "att_tz4a98xxat96iws9zmbrgj3a" }]
}
```

## Delegated uploads

Use a delegated upload when a browser, hosted agent, or another remote client needs to upload bytes without seeing your API key.

```bash theme={null}
SIZE_BYTES="$(wc -c < invoice.pdf | tr -d ' ')"
SHA256="$(shasum -a 256 invoice.pdf | awk '{print $1}')"

UPLOAD_INTENT="$({
  curl -sS -X POST https://smtp.qubrics.com/api/v1/emails/attachment-uploads \
    --header @- \
    -H "Content-Type: application/json" \
    -d "{
      \"filename\": \"invoice.pdf\",
      \"content_type\": \"application/pdf\",
      \"size_bytes\": $SIZE_BYTES,
      \"sha256\": \"$SHA256\"
    }" <<< "Authorization: Bearer $QUBRICS_API_KEY"
})"

ATTACHMENT_ID="$(
  printf '%s' "$UPLOAD_INTENT" \
  | jq -r '
      .data as $upload
      | "request = \($upload.method | @json)",
        "url = \($upload.upload_url | @json)",
        ($upload.headers | to_entries[] | "header = \("\(.key): \(.value)" | @json)")
    ' \
  | curl -sS --config - --data-binary @invoice.pdf \
  | jq -r '.data.attachment_id'
)"
```

The intent supplies the upload method, short-lived `upload_url`, `max_size_bytes`, and every required header. The upload response supplies the `attachment_id`. The pipeline feeds the capability URL and headers to curl through standard input, so they do not enter child-process arguments.

The upload token can write only that attachment, expires quickly, and does not grant send access.

## Agent and MCP workflows

For real Sending files in hosted or local MCP, call `qubrics_sending_create_attachment_upload` with `filename`, `content_type`, and exact `size_bytes`. Upload bytes outside model context using the returned method and headers, honour the returned `max_size_bytes`, then pass the returned `attachment_id` to `qubrics_sending_send_email` or `qubrics_sending_send_email_batch`.

For real Mailbox files in hosted or local MCP, call `qubrics_mailbox_upload_attachment` with `presign_upload_url=true`, `filename`, `content_type`, and exact `size_bytes`. Upload bytes outside model context using the returned method and headers, then send with the returned `blob_id`. The presigned request cap is 7,500,000 bytes.

Use MCP `content_base64` only for tiny agent-authored content. Decoded content is capped at 32 KiB: it is not the normal path for real files. SDK and CLI file helpers can accept local paths because they run outside MCP model context. For inbound Mailbox attachments, call `qubrics_mailbox_read_attachment` first when you need text-like content.

## Mailbox upload before sending

Mailbox send workflows can also upload a file first and reference the returned blob ID when sending. Direct mailbox uploads and presigned mailbox uploads use the same per-attachment cap.

SDK and CLI helpers can read a local path. MCP clients instead request a short-lived presigned upload URL, then upload the bytes outside model context with the exact returned method, headers, content type, and content length.

## Allowed files

Qubrics accepts common image, document, spreadsheet, presentation, text, calendar, and contact formats. Executables and archives are rejected.

Binary files are checked against their claimed file type. Text-based files are checked by extension.

## Inline base64 compatibility

```json theme={null}
{
  "from": { "email": "hello@example.com" },
  "to": { "email": "user@example.com" },
  "subject": "Invoice attached",
  "html_body": "<p>Please find your invoice attached.</p>",
  "attachments": [
    {
      "filename": "invoice-2026-03.pdf",
      "content": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZw...",
      "type": "application/pdf"
    }
  ]
}
```

Use this form only for small content that is already in memory. For files on disk, upload bytes first and use `attachment_id`.

## Attachment fields

| Form | Required fields | Optional fields |
| - | - | - |
| Uploaded reference | `attachment_id` | None |
| Inline base64 | `filename`, `content` | `type`, `encoding` |

An uploaded reference contains only the temporary `attachment_id` returned by
an upload endpoint. Inline attachments include a filename with an allowed
extension and base64-encoded content. If supplied, `encoding` must be `base64`.

## What happens next

If an attachment is too large, unsupported, or does not match its file type, the request fails with `validation_error` or `payload_too_large`. Fix the file and retry.

## Download mailbox attachments

Mailbox messages include attachment metadata when attachments are present:

* `id`
* `filename`
* `content_type`
* `size_bytes`
* `content_id`
* `disposition`
* `download_url`

The `download_url` is short-lived and grants access only to that attachment. Fetch it promptly with any HTTP client; no `Authorization` header is needed for the URL itself.

If the URL expires, re-read the message with `GET /mailbox/messages/{message_id}`, list or search messages again, or call the MCP `qubrics_mailbox_get_attachment` tool to get a fresh `download_url`. MCP clients that need attachment text should call `qubrics_mailbox_read_attachment` first; it returns inline text for text-like attachments and returns a resource link for binary or oversized files. The authenticated attachment download endpoint continues to work for clients that send bearer credentials.

Realtime received-message events can include the same attachment metadata when it is available. Handle older events where `attachments` is omitted, then re-read message metadata before downloading.

Range requests are still supported on attachment downloads, including short-lived URLs.

## Agent workflow

1. Wait for or list messages.
2. Read the message metadata and find the attachment.
3. For MCP, call `qubrics_mailbox_read_attachment` with the message ID and attachment ID.
4. Use returned inline text directly, or fetch the returned link promptly for binary or oversized files.
5. If the URL expired, re-read the message or attachment metadata and fetch the new URL.

Do not construct attachment URLs manually.

## Related guides

> [card] [Send by HTTP](https://sendmux.ai/docs/sending/http.md)
>
> Send uploaded attachment refs in single or batch requests.

> [card] [Mailbox push delivery](https://sendmux.ai/docs/mailboxes/push-delivery.md)
>
> Receive live mailbox events and then download attachments from message metadata.

> [card] [Sending errors](https://sendmux.ai/docs/sending-api/errors.md)
>
> Handle validation and payload size errors.


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