> ## 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.

# Read mailbox message content

> Read raw or cleaned mailbox message bodies with content controls.

The Qubrics Mailbox API is for mailbox-scoped access. Use it when a client should act as a mailbox, or as one mailbox from a connected-app mailbox set, without managing team-wide resources.

## Message body APIs

Use the raw body endpoint when you need the message body exactly as available from the mailbox.

```bash theme={null}
curl "https://app.qubrics.com/api/v1/mailbox/messages/msg_123/body?part=both&max_body_chars=50000" \
  -H "Authorization: Bearer smx_mbx_your_key_here"
```

```json theme={null}
{
  "ok": true,
  "data": {
    "id": "msg_123",
    "thread_id": "thr_123",
    "part": "both",
    "body": {
      "text": "Original body text...",
      "html": "<p>Original body HTML...</p>",
      "is_truncated": false,
      "truncated_at_chars": null
    },
    "states": {
      "email_state": "state_token"
    }
  },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}
```

Use the clean content endpoint when you want deterministic body cleaning and structured metadata.

```bash theme={null}
curl "https://app.qubrics.com/api/v1/mailbox/messages/msg_123/content?strip_signature=true&strip_quotes=true&include_links=true&include_html=false&include_headers=selected&include_attachments=metadata" \
  -H "Authorization: Bearer smx_mbx_your_key_here"
```

```json theme={null}
{
  "ok": true,
  "data": {
    "id": "msg_123",
    "thread_id": "thr_123",
    "subject": "Invoice question",
    "body": {
      "format": "text",
      "text": "Clean body text...",
      "html": null,
      "cleaned_html": null,
      "html_cleaning": null,
      "is_truncated": false,
      "truncated_at_chars": null,
      "signature_stripped": true,
      "quotes_stripped": true,
      "extracted_links": ["https://example.com/invoice"]
    },
    "attachments": [
      {
        "id": "att_123",
        "filename": "invoice.pdf",
        "content_type": "application/pdf",
        "size_bytes": 12345,
        "disposition": "attachment",
        "content_id": null,
        "download_url": "/api/v1/mailbox/messages/msg_123/attachment-downloads/attref_abc123?download_token=..."
      }
    ]
  },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}
```

Clean content controls:

| Parameter | Values | Default | Applies to |
| - | - | - | - |
| `part` | `auto`, `text`, `html` | `auto` | Message content, thread content, batch clean JSON |
| `max_body_chars` | `1` to `1000000` | `100000` for messages, `25000` per thread message | Raw body, message content, thread content, batch |
| `strip_signature` | `true`, `false` | `true` | Message content, thread content, batch clean JSON |
| `strip_quotes` | `true`, `false` | `true` | Message content, thread content, batch clean JSON |
| `include_links` | `true`, `false` | `true` | Message content, thread content, batch clean JSON |
| `include_html` | `true`, `false` | `false` | Message content, thread content, batch clean JSON |
| `include_headers` | `none`, `selected`, `full` | `selected` | Message content, thread content, batch clean JSON |
| `include_attachments` | `none`, `metadata` | `metadata` | Message content, thread content, batch clean JSON |
| `cursor` | Opaque cursor | none | Thread content |
| `limit` | `1` to `100` | `25` | Thread content |

> [!NOTE]
>
> Body endpoints do not parse attachment contents. Attachments are returned as
> metadata or downloaded separately. PDF, CSV, Office document, and OCR parsing
> are not part of these APIs.

## Read cleaned HTML

Set `include_html=true` on the content endpoint to receive both the original `body.html` and `body.cleaned_html`. The stripping options apply to the cleaned copy. Recognised quote and signature containers are removed; surviving markup, links and inline-image references are preserved. Unrecognised formats remain unchanged.

```bash theme={null}
curl "https://app.qubrics.com/api/v1/mailbox/messages/msg_123/content?include_html=true&strip_quotes=true&strip_signature=true" \
  -H "Authorization: Bearer $QUBRICS_API_KEY"
```

`body.html_cleaning` contains a `status` and separate `quotes_stripped` and `signature_stripped` flags. The existing `body.quotes_stripped` and `body.signature_stripped` flags describe the text output.

| HTML cleaning status | Result |
| - | - |
| `complete` | `cleaned_html` contains the processed HTML, including an empty string if all content was removed. |
| `source_truncated` | The source exceeded `max_body_chars` or was already truncated; `cleaned_html` is `null`. |
| `limit_exceeded` | Cleaning exceeded 20,000 elements or 128 nested elements; `cleaned_html` is `null`. |

Both added fields are `null` when HTML is absent or not requested. Cleaning does not sanitise HTML. Apply your own sanitisation and rendering restrictions before displaying either HTML field.

## Download the original message

`GET /mailbox/messages/{message_id}/raw` returns the stored message bytes as `message/rfc822`, including headers and encoded attachments. It requires `mailbox.read` access to that message and supports `ETag` and `If-None-Match`.

```bash theme={null}
curl "https://app.qubrics.com/api/v1/mailbox/messages/msg_123/raw" \
  -H "Authorization: Bearer $QUBRICS_API_KEY" \
  --output message.eml
```

The `/body` endpoint returns decoded body fields in JSON. Use `/raw` when you need the original `.eml` bytes.

## Extract attachment text

Use attachment text extraction when you need readable content from a file rather than the message body. It requires `mailbox.read` access to the source message. Extraction adds no charge; the mailbox's normal email and storage charges still apply.

**1. Request text from the source attachment**

Take the message and attachment IDs from authorised message metadata. Send `POST` to the attachment's `/text` URL; no request body or `Idempotency-Key` is needed.

```bash theme={null}
curl -X POST \
  "https://app.qubrics.com/api/v1/mailbox/messages/msg_123/attachments/att_123/text?max_bytes=262144" \
  -H "Authorization: Bearer $QUBRICS_API_KEY"
```

Integration credentials and connected apps with several granted inboxes must also pass the selected `mailbox_id` query parameter.

**2. Poll the same extraction**

A `202` response has `data.status` of `pending` or `running`. Read `GET` on the same URL until `data.status` is `complete`. GET does not start another conversion.

```bash theme={null}
curl \
  "https://app.qubrics.com/api/v1/mailbox/messages/msg_123/attachments/att_123/text?max_bytes=262144" \
  -H "Authorization: Bearer $QUBRICS_API_KEY"
```

An HTTP `200` means conversion completed; check `data.outcome` before using `data.text`. Only `ready` contains extracted Markdown text. Other completed outcomes contain an empty string.

**3. Check limits and keep the original available**

Check `data.truncated` before treating extracted text as complete. Download the [original attachment](https://sendmux.ai/docs/developer-tools/mailbox-api/attachments.md) when you need its full content or extraction cannot complete.

The input limit is 7,500,000 bytes, and conversion runs for at most 30 seconds. `max_bytes` limits UTF-8 text output: the default is 262,144 bytes and the maximum is 1,048,576 bytes. It also limits cached responses. OCR is unavailable.

Repeated POST requests reuse the same current source extraction for 24 hours. Read `data.expires_at`; after expiry, GET returns `404` and another POST is needed. Current mailbox access and source availability are checked before cached text is returned, including conditional GET requests. Deleting the source or losing access prevents further reads.

Completed outcomes explain why text is unavailable:

| Outcome | Handling |
| - | - |
| `unsupported` | Download the original and use a reader that supports its format. |
| `encrypted` | Use the original with an authorised reader that can open it. |
| `malformed` | Check the original file or request a usable replacement. |
| `ocr_required` | Use your own OCR workflow on the original file. |
| `resource_limit` | Use the original or a smaller file within the limits. |
| `source_unavailable` | Check that the source message and attachment still exist. |
| `failed` | Keep the original available and retain the request ID for support. |

For HTTP `429` or `503`, wait at least the `Retry-After` interval. A `404` can mean the source or unexpired extraction is unavailable; confirm source access before requesting another conversion. Do not treat an empty result or failed request as proof that the original file contains no text.

## Next steps

> [card] [Mailbox API introduction](https://sendmux.ai/docs/mailbox-api/introduction.md)

> [card] [Attachments](https://sendmux.ai/docs/developer-tools/mailbox-api/attachments.md)


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