Email worker — SMTP send and real-time IMAP read with IDLE push (email::*).
iii trigger compose::add worker=email@0.1.16Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.
List configured email accounts. Returns { accounts: [{ name, provider, from, can_send, can_read, folders }] }. Use `name` as the `account` field for email::send, email::list, email::get, email::search, email::flag, email::move, and email::attachment::get.
Download an email's attachment by part id. Payload: { account, folder, uid, part_id }. `part_id` comes from email::get's attachments[].part_id. Bytes flow over the response channel in chunks as IMAP delivers them; no in-memory buffering. Channel closes on EOF.
Wire-identical mirror of `iii_sdk::channels::StreamChannelRef`. The SDK type does not derive `JsonSchema`, which would block typed registration of `email::search` and `email::attachment::get`. Converted via `From` at the handler boundary so the rest of the worker keeps using the SDK type.
Report the last configuration hot-reload outcome: last_outcome (applied|rejected), last_error, and rejected_reloads (count since boot). A rejected outcome means a stored config was refused and the live accounts diverged from the central store. Takes no arguments.
Mark an email read, flagged, or answered by setting a flag. Payload: { account, folder, uid, flag, add?=true }. `flag` is one of 'seen', 'flagged', 'answered', 'deleted', 'draft' (without the leading backslash). Marking 'deleted' does NOT expunge — use email::move to trash.
Read a single email by UID. Payload: { account, folder, uid }. Returns { uid, message_id, from, to[], subject, date, html?, text?, attachments: [{ part_id, filename, content_type, size }] }. Use email::attachment::get with the returned part_id to stream attachment bytes.
List recent emails in a folder, newest first. Payload: { account, folder?='INBOX', limit?=50, since_uid?=<int> }. Returns { items: [{ uid, message_id, from, subject, snippet, ts, seen, flagged }], next_since_uid }. Pass next_since_uid back as since_uid to page forward without gaps or duplicates.
Move an email to another folder, e.g. archive or trash. Payload: { account, folder, uid, dst_folder }. Uses RFC 6851 UID MOVE when supported; else COPY + STORE \Deleted. Destination folder must exist on the server.
Internal: hot-reload the email worker from the authoritative configuration when it changes. Limit changes swap the snapshot; account changes respawn the IMAP supervisors and drop pooled sessions. Rejected values keep the previous runtime.
Search an account's emails by subject, sender, date, or text. `query` is IMAP SEARCH syntax (RFC 9051), e.g. 'FROM alice@x SINCE 1-Jan-2026'. Frames { uid, message_id, from, subject, snippet, ts, seen, flagged } stream as NDJSON on the response channel, which closes at completion.
Wire-identical mirror of `iii_sdk::channels::StreamChannelRef`. The SDK type does not derive `JsonSchema`, which would block typed registration of `email::search` and `email::attachment::get`. Converted via `From` at the handler boundary so the rest of the worker keeps using the SDK type.
Send an email via the account's SMTP transport; provide `html`, `text` or both. The SMTP login comes from the account's `smtp.username` / `smtp.password` configuration, else from `auth::get_token` under provider key `email::<account>`.
Fires when IMAP IDLE pushes a new message to a configured (account, folder). Payload: { account, folder, uid, message_id, from, subject, snippet, ts }. If the IMAP server lacks the IDLE capability, the account fails at startup (E610).
Find workers, kits and executables, or jump to a page.