Email

email

The email worker speaks SMTP and IMAP through persistent per-account connections. Every callable surface lives under the email::* namespace. The transport is chosen per account in config.yaml — provider: smtp for send-only accounts, provider: imap for two-way accounts that also need to read and react to inbound mail.

The worker refuses to fall back to polling. If an IMAP server does not advertise the IDLE capability, the supervisor fails at startup with E610. Inbound messages flow through the email::new-mail trigger type, fanned out by an IDLE-driven dispatcher the moment a server-side EXISTS notification lands. Credentials never live in this worker — every IMAP login and every email::send calls auth::get_token against harness/auth-credentials under provider key email::<account>.

When to Use

• An agent needs to send a transactional email right now (email::send).
• You need to enumerate configured accounts and their capabilities so an LLM picks the right account field (email::accounts::list).
• You need to page recent messages in an IMAP folder by UID with a stable cursor (email::list).
• You need the full parsed body of one message plus attachment part refs (email::get).
• You need to stream IMAP SEARCH results as NDJSON as the server returns matches (email::search).
• You need to add or remove a system flag — \Seen, \Flagged, \Answered, \Deleted, \Draft (email::flag).
• You need to move a message to another folder atomically with RFC 6851 UID MOVE (email::move).
• You need to stream an attachment's raw bytes onto a response channel with no in-memory buffering (email::attachment::get).
• You need to react to inbound mail the instant it lands in a configured (account, folder) (email::new-mail trigger type).

Boundaries

• Not a mail server — this is a client. Bring your own SMTP and IMAP endpoints.
• Not an OAuth flow runner in 0.1.0 — use app-password style credentials via harness/auth-credentials until the OAuth follow-up PR.
• Not a polling fallback — IMAP servers without IDLE fail fast with E610 so the failure stays visible instead of silently degrading.
• Not a credential store — every connect re-fetches the secret from harness/auth-credentials. Pair the two workers; deploying email alone is unsupported.
• email::flag with flag: "deleted" does NOT expunge — use email::move to a Trash folder for visible deletion.
• email::search and email::attachment::get use a streaming response channel; they're invoked by sibling workers passing a StreamChannelRef, not directly from iii trigger.

Functions

• email::send — deliver a message via the account's SMTP transport (STARTTLS or plain on a trusted network).
• email::accounts::list — enumerate configured accounts with provider, from, can_send, can_read, and folders.
• email::list — page recent UIDs in a folder, newest first, with next_since_uid cursor.
• email::get — fetch one message by UID; returns parsed html, text, headers, and an attachments[] list of part refs.
• email::search — stream IMAP SEARCH results as NDJSON frames onto a StreamChannelRef; one header-summary object per match.
• email::flag — add or remove a system flag on a UID via UID STORE +FLAGS.SILENT / -FLAGS.SILENT.
• email::move — move a UID to another folder with RFC 6851 UID MOVE; falls back to COPY + STORE \Deleted when the server lacks MOVE.
• email::attachment::get — stream attachment bytes by part_id onto a StreamChannelRef chunk-by-chunk; no in-memory buffering.

SMTP send timeout is limits.send_timeout_ms (default 30 s). IMAP connect timeout is limits.imap_connect_timeout_ms (default 15 s). Total recipients across to + cc + bcc cap at limits.max_recipients (default 100). Each attachment caps at limits.max_attachment_bytes (default 25 MiB).

Stream-source attachments (source.kind = "stream") return E699 in 0.1.0; use source.kind = "base64" until the symmetric attachment-send path lands.

Reactive triggers

Register an email::new-mail trigger when a function should fire automatically the moment a new message arrives in a configured (account, folder) — without polling with email::list.

Reach for it when:

• A support workflow should kick off the instant a ticket email lands.
• A harness session should ingest new mail as an additional turn.
• An archival worker should mirror inbound mail into a database.

Do not bind when:

• The account is provider: smtp (send-only); only provider: imap accounts open an IDLE listener.
• You only need to act on outbound mail — email::send already gives you the SMTP response synchronously.

How to bind

1. Register a handler: registerFunction('my-worker::on-mail', handler).
2. Register the trigger:

iii.registerTrigger({
  type: 'email::new-mail',
  function_id: 'my-worker::on-mail',
  config: {
    account: 'support',
    folder: 'INBOX',
    handler_timeout_ms: 30000,
  },
})

Config: account (required, must be a configured account with an imap: block), folder (default "INBOX", must appear in config.accounts.<name>.imap.folders), handler_timeout_ms (default 30 000).

Event payload per inbound message:

{
  "account":    "support",
  "folder":     "INBOX",
  "uid":        12345,
  "message_id": "<abc@mx.example.com>",
  "from":       "alice@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 IMAP server's EXISTS push — within milliseconds of a new message landing in the watched folder.

Delivery semantics

Best-effort, at-most-once. The dispatcher fires iii.trigger per subscriber and waits up to handler_timeout_ms. There is no upstream durable queue: IMAP IDLE is a wakeup mechanism, not a delivery guarantee.

• A subscriber handler that panics, times out, or returns an error is logged and skipped — the event is NOT redelivered.
• If the worker is down when a message lands, no email::new-mail event fires for it. On reconnect the supervisor sets the high-water mark to the current UIDNEXT - 1; UIDs that arrived during downtime are reachable via email::list but do NOT replay as events.
• For at-least-once / replay, write each email::new-mail event to a durable store from your handler (database::execute, storage::putObject, …) before doing meaningful work, and use email::list with a persisted since_uid cursor to catch up on downtime gaps.

Errors

Stable across the trigger boundary. Match on the code field of the returned envelope.