`imap://`¶

IMAP4rev2 polling consumer. Built on github.com/emersion/go-imap/v2 + github.com/emersion/go-message. For TLS-from-start, use imaps://. For send, see smtp://.

URI shape¶

imap://host[:port]?username=…&password=…&folderName=INBOX&unseen=true&peek=true

Parameters¶

Connection¶

Param	Type	Default	Description
`host`	string	from URI path	IMAP server host.
`port`	integer	`143`	IMAP server port.
`username`	string	required	IMAP LOGIN username.
`password`	string	required	IMAP LOGIN password.
`connectionTimeout`	duration	`30s`	TCP dial timeout.
`tls`	boolean	`false` (`true` on imaps://)	Implicit TLS from connection start.
`starttls`	boolean	`false`	Opportunistic STARTTLS upgrade.
`tlsInsecure`	boolean	`false`	Skip certificate verification (testing only).
`tlsServerName`	string	—	SNI server name override.
`tlsCert` / `tlsKey` / `tlsCA`	string	—	Client cert + key + CA bundle.

Folder semantics¶

Param	Type	Default	Description
`folderName`	string	`INBOX`	Mailbox to SELECT.
`unseen`	boolean	`true`	Only process unread messages (IMAP SEARCH UNSEEN).
`peek`	boolean	`true`	Use BODY.PEEK[] so reads don't mark messages `\Seen`.
`delete`	boolean	`false`	`\Deleted` + EXPUNGE after the route succeeds.
`moveTo`	string	—	Move processed messages to this folder (MOVE if supported, else COPY+DELETE). Folder is auto-created if missing.
`copyTo`	string	—	COPY processed messages to this folder (independent of delete/moveTo). Folder is auto-created if missing.
`closeFolder`	boolean	`true`	Close the folder (UNSELECT) after each poll.
`disconnect`	boolean	`false`	Drop the IMAP connection after each poll.
`handleFailedMessage`	boolean	`false`	Let the route ErrorHandler handle MIME-parse failures.
`skipFailedMessage`	boolean	`false`	Skip + log MIME-parse failures.

Pagination + transport¶

Param	Type	Default	Description
`fetchSize`	integer	`0`	Cap rows per poll cycle. 0 = unlimited.
`maxMessagesPerPoll`	integer	`0`	Hard cap on messages dispatched per poll.
`sendEmptyMessageWhenIdle`	boolean	`false`	Emit a heartbeat Exchange when poll yields zero messages.
`routeEmptyResultSet`	boolean	`false`	Emit an empty-body Exchange for empty polls.
`breakBatchOnConsumeFail`	boolean	`false`	Abort the batch on first failing message.
`decodeFilename`	boolean	`false`	RFC 2231 / MIME-Word filename decoding for attachments.
`mimeDecodeHeaders`	boolean	`false`	RFC 2047 encoded-word decoding for headers (e.g. Subject).
`generateMissingAttachmentNames`	boolean	`false`	Auto-name attachments without `filename=`.
`handleDuplicateAttachmentNames`	boolean	`false`	Append (`-2`, `-3`) suffix on attachment-name collisions.
`includeRawMessage`	boolean	`false`	Surface the raw RFC 5322 bytes as `HelixMailRaw` header.

Filter + sort¶

Param	Type	Default	Description
`searchTerm`	string	—	IMAP SEARCH terms in string form. Supported tokens: `UNSEEN`, `SEEN`, `DELETED`, `UNDELETED`, `FLAGGED`, `ANSWERED`, `FROM "x"`, `TO "x"`, `CC "x"`, `SUBJECT "x"`, `BODY "x"`, `TEXT "x"`, `SINCE 5-Jun-2026`, `BEFORE 5-Jun-2026`.
`sortTerm`	string	—	IMAP SORT terms (RFC 5256). Empty disables SORT.

Polling scheduler¶

Param	Type	Default	Description
`delay`	duration	`60s`	Interval between polls.
`initialDelay`	duration	`1s`	Delay before the first poll.
`useFixedDelay`	boolean	`true`	Fixed-delay vs. fixed-rate scheduling.
`repeatCount`	integer	`0`	Number of polls before stopping. 0 = infinite.
`greedy`	boolean	`false`	Re-poll immediately when previous yielded messages.
`pollInterval`	duration	—	Legacy alias for `delay`.

Body shape¶

For each received message the consumer emits one Exchange:

body: []byte of the text/plain part (or the HTML part if no plain part exists).
Subject, From, To, Cc, Bcc, Reply-To, Date: parsed from the message envelope.
Content-Type: media type of the body part.
Attachments: map[string][]byte of attachment filenames → bytes (when present).
HelixMailMessageId: Message-ID header.
HelixMailFolder, HelixMailUID, HelixMailSeq: IMAP-side identifiers.
HelixMailRaw (when includeRawMessage=true): raw RFC 5322 bytes.

Example¶

trigger:
  uri: imap://mail.example.com?folderName=INBOX&unseen=true&moveTo=Processed&delete=false&delay=30s
  params:
    username: alerts
    password: secret
steps:
  - log:
      message: "Got: ${headers.Subject}"

imap://¶