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-registryat startup - Orchestrator discovers the endpoint via the registry
- No first-class
type: imap_peekstep — useservice_call - Call parameters are first-class YAML fields on the step (not a JSON
payloadblob)
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 /healthzGET /readyzGET /internal/capabilities