Message body APIs
Use the raw body endpoint when you need the message body exactly as available from the mailbox.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
Setinclude_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.
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.
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.
/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 requiresmailbox.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 Integration credentials and connected apps with several granted inboxes must also pass the selected
POST to the attachment’s /text URL; no request body or Idempotency-Key is needed.mailbox_id query parameter.2
Poll the same extraction
A An HTTP
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.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 when you need its full content or extraction cannot complete.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:
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.