# Work with attachments

Download received files and include base64 attachments in outgoing mail.

Source: https://cherami.to/docs/guides/attachments



## Download a received file [#download-a-received-file]

Fetch the [message detail](https://cherami.to/docs/api/messages#read-a-message) and wait for `processing_status: "ready"`. Each `content.attachments` entry supplies an `id`, filename, size, and MIME metadata. Use the returned ID, not the filename, in the download request:

```http
GET /v1/messages/MESSAGE_ID/attachments/ATTACHMENT_ID HTTP/1.1
Host: cherami.to
Authorization: Bearer YOUR_CREDENTIAL
```

The response is a download with `Content-Type: application/octet-stream`. The filename and reported MIME type describe the file; they are not trust signals. Choose a safe local destination rather than treating a sender's filename as a path.

If prepared content failed, you can download `/v1/messages/MESSAGE_ID/raw` and use your own MIME tools. Incoming mail has a 25 MiB total limit including MIME-encoded attachments.

## Attach a file to a send [#attach-a-file-to-a-send]

Encode the file bytes as padded base64 with no whitespace. Include the result in the ordinary sending request:

```json
{
  "to": ["recipient@example.com"],
  "subject": "Notes",
  "text": "Attached are the notes.",
  "attachments": [
    {"filename": "notes.txt", "type": "text/plain", "content": "SGVsbG8="}
  ]
}
```

This example attaches the five bytes `Hello`. Cherami does not fetch attachment URLs or support inline attachments. At most 32 files are allowed. Outbound JSON is capped at 8 MiB; the total email must fit 5 MiB, including generated MIME and attachments. Base64 expands data, so do not assume a 5 MiB file fits.

## Retrieve sent attachments [#retrieve-sent-attachments]

`GET /v1/sent/MESSAGE_ID` includes base64 content in `submission.attachments`. Decode it to recover the file. Thread detail returns attachment metadata without bytes; use sent detail or the received attachment download when you need the file itself.

[Exact attachment validation](https://cherami.to/docs/api/sending#request-fields) · [Mail safety](https://cherami.to/docs/guides/safety)