Skip to content

Egress IMAP

Responsibility

IMAP mailbox capability provider for workflow service_call steps.

Capabilities:

  • egress.imap.call — list / peek / read (POST /call)
  • connection type via registry designer metadata

Architecture

Capability provider (see Deploy integration contract):

  • Registers with capability-registry at startup
  • Orchestrator discovers the endpoint via the registry
  • No first-class type: imap_peek step — use service_call
  • Call parameters are first-class YAML fields on the step (not a JSON payload blob)

Inbound Authentication

  • internal-only service, called by orchestrator after registry lookup

Outbound Authentication

  • IMAP username/password from connection payload
  • for Gmail IMAP, use App Password (not account password)

Example workflow step

- id: peek_inbox
  type: service_call
  capability_name: egress.imap.call
  capability_version: "^1.0"
  path: /call
  connection: my_imap
  action: list
  mailbox: INBOX
  filter: UNSEEN
  limit: 10

Legacy JSON payload: | { "action": "list", … } still works as a compose fallback; prefer first-class fields.

Step fields (what each option does)

Field Role in the provider
connection Named IMAP connection; orchestrator merges host / port / username / password / use_ssl into the call
action Operation to run (see below)
mailbox Folder to SELECT (e.g. INBOX)
filter IMAP SEARCH criteria string (e.g. UNSEEN, ALL)
limit Cap on how many matching messages are returned (1–100)
message_id Optional sequence/UID when fetching a specific message with action: read
include_body With action: read: include body text/HTML in the response
include_attachments With action: read: include attachment data (size-capped)
mark_seen With action: read: set the \Seen flag after fetch; ignored for peek / list
attachment_max_bytes Per-attachment size limit when include_attachments is true (default 1 MiB)

action options

Option Provider behaviour
peek Fetch headers of matching messages without setting \Seen
list Return a compact summary list (subject / from / date / ids)
read Fetch full message(s); honour include_body, include_attachments, and mark_seen

Connection fields

Field Meaning
host / port IMAP server endpoint
username / password Login (prefer $secret:… for password)
use_ssl When true, use IMAP4_SSL (typical port 993)

Health

  • GET /healthz
  • GET /readyz
  • GET /internal/capabilities