# email > Email worker — SMTP send and real-time IMAP read with IDLE push (email::*). | field | value | |-------|-------| | version | 0.1.1 | | type | binary | | repo | https://github.com/iii-hq/workers | | supported_targets | x86_64-apple-darwin, aarch64-apple-darwin, i686-pc-windows-msvc, x86_64-pc-windows-msvc, aarch64-pc-windows-msvc, x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, x86_64-unknown-linux-musl, armv7-unknown-linux-gnueabihf | | author | iii | ## installation ```sh iii worker add email@0.1.1 ``` ## configuration ```yaml - accounts: alice: from: Alice provider: smtp smtp: host: localhost port: 3025 starttls: false bob: from: Bob provider: smtp smtp: host: localhost port: 3025 starttls: false limits: imap_connect_timeout_ms: 15000 max_attachment_bytes: 26214400 max_recipients: 100 send_timeout_ms: 30000 ``` ## readme # email Email worker for the iii engine. SMTP send + real-time IMAP read with `IDLE` push. The worker refuses to fall back to polling: an IMAP server without `IDLE` fails fast at startup with `E610`. Inbound messages flow through the `email::new-mail` trigger type, fanned out the moment the server pushes `EXISTS`. Credentials live in `harness/auth-credentials` under provider key `email::`. Pair both workers in any real deployment. ## Install ```bash iii worker add harness/auth-credentials iii worker add email ``` ## Quickstart ```rust use iii_sdk::{register_worker, InitOptions, protocol::TriggerRequest}; use serde_json::json; #[tokio::main] async fn main() -> anyhow::Result<()> { let worker = register_worker("ws://localhost:49134", InitOptions::default()); let result = worker.trigger(TriggerRequest { function_id: "email::send".into(), payload: json!({ "account": "support", "to": ["recipient@example.com"], "subject": "Your ticket has been updated", "text": "Hi — thanks for reaching out." }), action: None, timeout_ms: Some(30_000), }).await?; println!("{result:#?}"); Ok(()) } ``` ```typescript import { registerWorker } from 'iii-sdk' const worker = registerWorker('ws://localhost:49134') await worker.trigger({ function_id: 'email::send', payload: { account: 'support', to: ['recipient@example.com'], subject: 'Your ticket has been updated', text: 'Hi — thanks for reaching out.', }, }) ``` ```python from iii import register_worker worker = register_worker("ws://localhost:49134") worker.trigger({ "function_id": "email::send", "payload": { "account": "support", "to": ["recipient@example.com"], "subject": "Your ticket has been updated", "text": "Hi — thanks for reaching out.", }, }) ``` Other entry points: `email::accounts::list`, `email::list`, `email::get`, `email::search`, `email::flag`, `email::move`, `email::attachment::get`. ## Configuration ```yaml accounts: # Send-only: only smtp:, provider: smtp. support: provider: smtp from: "Support " smtp: host: smtp.example.com port: 587 starttls: true # Two-way: smtp: + imap:, provider: imap. inbox: provider: imap from: "Inbox " smtp: host: smtp.example.com port: 587 starttls: true imap: host: imap.example.com port: 993 tls: true folders: ["INBOX"] limits: max_attachment_bytes: 26214400 # 25 MiB max_recipients: 100 # to + cc + bcc combined send_timeout_ms: 30000 imap_connect_timeout_ms: 15000 ``` Credentials are fetched on every connect from `harness/auth-credentials` under provider key `email::` with shape `{ "type": "api_key", "username": "...", "password": "..." }`. For Gmail, generate an app password at https://myaccount.google.com/apppasswords — the worker accepts both spaced (`abcd efgh ijkl mnop`) and joined (`abcdefghijklmnop`) formats. ## Triggers | Name | Fires when | |---|---| | `email::new-mail` | IMAP `IDLE` push delivers a new message to a configured `(account, folder)`. | Subscriber config: ```yaml triggers: - type: email::new-mail function_id: my-worker::on-mail config: account: support folder: INBOX # optional, default "INBOX" handler_timeout_ms: 30000 # optional, default 30000 ``` Payload your function receives per inbound message: ```json { "account": "support", "folder": "INBOX", "uid": 12345, "message_id": "", "from": "sender@example.com", "subject": "Ticket #42", "snippet": "first ~200 chars of body", "ts": "2026-05-28T10:14:00+00:00" } ``` The dispatch is event-driven off the server's `EXISTS` push — within milliseconds of a new message landing in the watched folder. ## Local development & testing ```bash # In one terminal: start the engine iii # In another: build & run the worker cargo run --release -- --url ws://127.0.0.1:49134 --config ./config.yaml ``` The worker registers 8 functions + 1 trigger type, then spawns one persistent IMAP+IDLE supervisor per `(account, folder)` configured with `provider: imap`. Reads (`list`/`get`/`search`/`flag`/`move`/`attachment::get`) borrow an on-demand session from a separate pool so the half-duplex IMAP socket is never shared with the supervisor. Seed credentials before exercising `email::send` or any IMAP function: ```bash iii trigger auth::set_token \ provider=email::support \ credential='{"type":"api_key","username":"you@example.com","password":""}' ``` `--manifest` prints the registry-publish JSON without touching the engine: ```bash cargo run -- --manifest | jq . ``` ### Tests ```bash cargo test # unit tests (config, manifest, triggers) cargo test --test bdd # cucumber: --manifest subprocess contract ``` `tests/bdd.rs` self-skips `@engine` scenarios when no engine is reachable on `III_ENGINE_WS_URL` (default `ws://127.0.0.1:49134`), so contributor laptops without a running engine still pass `@pure` scenarios. ### Verification before publishing The full preflight checklist for binary workers (`workers/binary-worker.md`): ```bash cargo fmt --all -- --check cargo clippy --all-targets --all-features -- -D warnings cargo test --all-features ./target/debug/email --manifest | jq . ``` ## Errors | Code | When | |------|------| | `E600` | Unknown account name | | `E601` | `email::send` with empty `to` | | `E602` | Total recipients over `limits.max_recipients` | | `E603` | Account missing the required transport block | | `E604` | `email::send` with neither `html` nor `text` | | `E605` | Attachment over `limits.max_attachment_bytes` | | `E606` | `auth::get_token` upstream call failed | | `E607` | No credential stored for the account | | `E608` | Credential payload missing `username` / `password` | | `E609` | Address parse / MIME build failure | | `E610` | IMAP server lacks IDLE — refusing to fall back to polling | | `E612` | IMAP `UID SEARCH` failed | | `E613` | Folder not in account's `imap.folders` config | | `E614` | IMAP connect / TLS handshake failed | | `E615` | Plain (non-TLS) IMAP refused | | `E616` | IMAP login failed | | `E617` | IMAP `SELECT` failed | | `E619` | IMAP body fetch / MIME parse failed | | `E620` | SMTP send failed | | `E621` | Response channel close failed | | `E622` | Unknown flag name | | `E623` | IMAP `STORE` failed | | `E624` | IMAP `COPY` / `STORE \Deleted` fallback failed | | `E625` | IMAP attachment-part fetch failed | | `E626` | Attachment payload malformed (e.g. invalid base64) | | `E627` | `email::move` partial: copy succeeded but `STORE \Deleted` failed — message in BOTH folders, reconcile | | `E699` | Not yet implemented in 0.1.0 | ## api reference ```json { "functions": [ { "description": "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.", "metadata": {}, "name": "email::accounts::list", "request_schema": {}, "response_schema": {} }, { "description": "Stream an attachment's raw bytes from a message. 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.", "metadata": {}, "name": "email::attachment::get", "request_schema": {}, "response_schema": {} }, { "description": "Add or remove a system flag on a message. Payload: { account, folder, uid, flag, add?=true }. `flag` is one of 'seen', 'flagged', 'answered', 'deleted', 'draft' (without the leading backslash). Marking a message 'deleted' does NOT expunge — use email::move to trash, or future email::expunge.", "metadata": {}, "name": "email::flag", "request_schema": {}, "response_schema": {} }, { "description": "Fetch a single message 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.", "metadata": {}, "name": "email::get", "request_schema": {}, "response_schema": {} }, { "description": "List recent messages in a folder. Payload: { account, folder?='INBOX', limit?=50, since_uid?= }. 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 missing or duplicating messages.", "metadata": {}, "name": "email::list", "request_schema": {}, "response_schema": {} }, { "description": "Move a message to another folder. Payload: { account, folder, uid, dst_folder }. Uses RFC 6851 UID MOVE when the server supports it; falls back to COPY + STORE \\Deleted otherwise. Destination folder must exist on the server.", "metadata": {}, "name": "email::move", "request_schema": {}, "response_schema": {} }, { "description": "Stream search results from an account's IMAP. Payload: { account, folder?='INBOX', query }. `query` is IMAP SEARCH syntax (RFC 9051), e.g. 'FROM alice@x SINCE 1-Jan-2026' or 'UNSEEN SUBJECT \"invoice\"'. Returns NDJSON frames on the response channel; each frame is { uid, message_id, from, subject, snippet, ts, seen, flagged }. Channel closes when search completes. No polling — frames stream as IMAP returns matches.", "metadata": {}, "name": "email::search", "request_schema": {}, "response_schema": {} }, { "description": "Send an email via the account's SMTP transport. Payload: { account: string (key from email worker config), to: string[], cc?: string[], bcc?: string[], subject: string, html?: string, text?: string, reply_to?: string, in_reply_to?: string (Message-ID), references?: string[], attachments?: [{ filename, content_type, source: { kind: 'base64', data } }] }. Returns { message_id }. Credentials are fetched from auth-credentials under provider key `email::` ({ username, password }). Provide html OR text (or both); at least one body is required.", "metadata": {}, "name": "email::send", "request_schema": {}, "response_schema": {} } ], "triggers": [ { "description": "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).", "invocation_schema": {}, "metadata": {}, "name": "email::new-mail", "return_schema": {} } ] } ```