> ## Documentation Index
> Fetch the complete documentation index at: https://openmail-docs-reputation-lifecycle-webhooks.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Attachments

> Send files with outbound emails and access attachments on inbound messages. OpenMail parses and stores attachments, making them available via API.

OpenMail supports attachments in both directions — send files with outbound emails and access files from inbound emails with automatic text extraction.

## Sending attachments

To send an email with attachments, use `multipart/form-data` instead of JSON:

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"dark-plus"}}
  curl -X POST "https://api.openmail.sh/v1/inboxes/$OPENMAIL_INBOX_ID/send" \
    -H "Authorization: Bearer $OPENMAIL_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)" \
    -F "to=recipient@example.com" \
    -F "subject=Monthly report" \
    -F "body=See the attached report." \
    -F "attachments=@report.pdf" \
    -F "attachments=@chart.png"
  ```

  ```bash CLI theme={"theme":{"light":"github-light","dark":"dark-plus"}}
  openmail send --to recipient@example.com --subject "Monthly report" \
    --body "See the attached report." \
    --attach report.pdf --attach chart.png
  ```
</CodeGroup>

* Maximum 25 MB total per email (provider limit)
* Multiple files: repeat the `attachments` field (curl) or `--attach` flag (CLI)
* JSON requests without attachments continue to work as before

## Receiving attachments

When an inbound email includes attachments, OpenMail stores them, extracts readable text, and provides signed download URLs.

### How it works

1. Email arrives with attachments
2. We upload each file to secure storage
3. Text is extracted automatically based on file type
4. Attachment metadata — including extracted text — is included in the webhook payload and message responses

## Text extraction

OpenMail automatically extracts readable text from common attachment types so your agent can read the content directly from the webhook payload or API response, without downloading and parsing files.

| File type   | Examples                                                 |
| ----------- | -------------------------------------------------------- |
| PDF         | Invoices, receipts, contracts                            |
| Images      | Scanned documents, screenshots                           |
| Office docs | `.docx`, `.xlsx`, `.pptx`, `.odt`                        |
| CSV / TSV   | Spreadsheets, data exports                               |
| Plain text  | `.txt`, `.md`, `.json`, `.html`, `.xml`, `.yaml`, `.log` |

Each attachment includes a `parsedText` field when extraction succeeds:

```json theme={"theme":{"light":"github-light","dark":"dark-plus"}}
{
  "filename": "invoice.pdf",
  "contentType": "application/pdf",
  "sizeBytes": 45000,
  "url": "https://api.openmail.sh/v1/attachments/msg_.../invoice.pdf",
  "parsedText": "Invoice #2847\nDate: March 15, 2026\nAmount: $1,250.00\n...",
  "extractionMethod": "pdf"
}
```

The `extractionMethod` field tells you how the text was extracted: `pdf`, `ocr`, `office`, `csv`, or `text`. If extraction failed or the file type is unsupported, `parsedText` is omitted and `extractionMethod` indicates the reason (e.g. `unsupported`, `pdf_error`, `skipped_too_large`).

### Limits

* Files larger than 10 MB are skipped for extraction
* Extracted text is capped at 50,000 characters per attachment
* Unsupported binary formats (video, audio, archives) return `extractionMethod: "unsupported"`

## Downloading attachments

Each attachment includes a `url` field in the message response:

```
https://api.openmail.sh/v1/attachments/{messageId}/{filename}
```

This endpoint requires authentication and returns a `302` redirect to a signed URL that expires in 15 minutes.

```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
curl -L https://api.openmail.sh/v1/attachments/msg_4c8d5e6f/receipt.pdf \
  -H "Authorization: Bearer om_..."
```

## On-demand text extraction

For attachments that were stored before text extraction was available, or to re-extract text, use the `/text` endpoint:

```
GET /v1/attachments/{messageId}/{filename}/text
```

```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
curl https://api.openmail.sh/v1/attachments/msg_4c8d5e6f/receipt.pdf/text \
  -H "Authorization: Bearer om_..."
```

Returns:

```json theme={"theme":{"light":"github-light","dark":"dark-plus"}}
{
  "filename": "receipt.pdf",
  "contentType": "application/pdf",
  "extractionMethod": "pdf",
  "text": "Invoice #2847\nDate: March 15, 2026\n..."
}
```

## Size limits

* Maximum attachment size is determined by the email provider (typically 25 MB per email)
* Attachment download URLs expire after 15 minutes