Python SDK: Mail: inbound mail
ctx.mail() is available for an inbound-mail scenario. Read message content and attachments only for the authorized run; do not write their contents to logs.
Examples are fragments inside def run(ctx):. All SDK methods are synchronous; do not add await.
Methods
available
ctx.mail().available() -> bool
No arguments.
Result: bool.
Whether this run has a verified message. Returns False for manual and trial runs.
result = ctx.mail().available()
current
ctx.mail().current() -> dict[str, Any]
No arguments.
Result: dict[str, Any].
The current message's subject, sender, text, attachments, and retention period. Internal headers and other recipients are not exposed. Text is limited to 1 MiB; text_truncated tells you when it was shortened.
result = ctx.mail().current()
text
ctx.mail().text() -> str
No arguments.
Result: str.
Get the plain text of the message without HTML.
result = ctx.mail().text()
attachments
ctx.mail().attachments() -> list[dict[str, Any]]
No arguments.
Result: list[dict[str, Any]].
The verified attachments, with id, name, mime, and size. Download links require access to the current workspace.
result = ctx.mail().attachments()
document
ctx.mail().document(id) -> Document
| Argument | Type | Required | Purpose |
|---|---|---|---|
id |
str |
Yes | Authorized attachment/product identifier for this context. |
Result: Document. An SDK object; use its methods instead of emitting it directly.
Extract text, Excel sheets, Word tables, or PDF pages from an attachment belonging to this message. Links in the document are not opened automatically. No more than eight documents can be parsed per run.
result = ctx.mail().document('attachment-id')
attachment
ctx.mail().attachment(id) -> bytes
| Argument | Type | Required | Purpose |
|---|---|---|---|
id |
str |
Yes | Authorized attachment/product identifier for this context. |
Result: bytes.
Reads an attachment in chunks and returns bytes, up to 10 MiB. Decode text explicitly only when its encoding is known. Use document(id) for Excel, PDF, or Word to preserve structure.
result = ctx.mail().attachment('attachment-id')
Errors and execution context
All calls are synchronous. Invalid arguments or malformed source data can raise ValueError/TypeError; a platform refusal or unavailable service raises RuntimeError. Missing elements/values return None or an empty collection only where explicitly documented. Do not convert every exception into an empty successful result. External-service methods are unavailable in export transformations; see transformation limits and environment.