Configuration
Full property reference for the IMAP Trigger node: connection, authentication, mailbox selection, search criteria, output format, attachment handling, post-process actions, and timeout settings.
Connection & Authentication
| Property | Required | Description |
|---|---|---|
Host |
Required | IMAP server hostname or IP address. Examples: imap.gmail.com, outlook.office365.com, mail.mycompany.com. |
Port |
Optional | IMAP server port. Default: 993 (standard IMAPS/TLS port). Use 143 for plain IMAP or STARTTLS. Use 993 for TLS/SSL. |
User |
Required | IMAP account username. Typically the full email address (e.g. support@mycompany.com). |
Password |
Required | IMAP account password or app-specific password. Store in BizFirst's encrypted secrets store — do not hardcode in workflow configuration. For Gmail, use an App Password if 2FA is enabled. |
Tls |
Optional | Boolean. Enables TLS encryption for the IMAP connection. Default: true. Set to false only when the server requires plain IMAP (uncommon). Do not disable in production. |
AllowUnauthorizedCerts |
Optional | Boolean. When true, skips TLS certificate validation. For development only — allows self-signed certificates on internal mail servers. Never enable in production. |
Mailbox Selection
| Property | Required | Description |
|---|---|---|
Mailbox |
Optional | IMAP folder name to poll. Default: "INBOX". Use IMAP folder paths for nested folders, e.g. "INBOX/Support" or "[Gmail]/All Mail". Folder names are case-sensitive on most servers. |
Search Criteria
| Property | Required | Description |
|---|---|---|
CustomEmailConfig |
Optional |
IMAP search criteria as a JSON array of RFC 3501 search keys. Default: ["UNSEEN"] — matches all unread emails.Common values: ["UNSEEN"] — unread emails only (default)["ALL"] — all emails in the mailbox["SEEN"] — read emails only["FROM", "invoices@supplier.com"] — from a specific sender["SUBJECT", "Invoice", "UNSEEN"] — unread emails with "Invoice" in subject["SINCE", "01-May-2026"] — emails received since a date (DD-Mon-YYYY format)["FLAGGED"] — flagged/starred emailsMultiple criteria are combined with an implicit AND. |
RFC 3501 compliance: The
CustomEmailConfig array maps directly to IMAP SEARCH command operands. All standard RFC 3501 search keys are supported: ALL, ANSWERED, BCC, BEFORE, BODY, CC, DELETED, DRAFT, FLAGGED, FROM, HEADER, KEYWORD, LARGER, NEW, NOT, OLD, ON, OR, RECENT, SEEN, SINCE, SMALLER, SUBJECT, TEXT, TO, UNANSWERED, UNDELETED, UNDRAFT, UNFLAGGED, UNKEYWORD, UNSEEN.
Output Format
| Property | Required | Description |
|---|---|---|
Format |
Optional |
Output format for the email payload. Default: "simple"."simple" — Parsed JSON with common fields (from, to, subject, date, text, html, attachments). Attachment download available only in this mode."resolved" — Structured output using ImapAddressInfo objects with separate Name and Address fields for all email addresses."raw" — Full RFC 822 email as base64-encoded bytes. No attachment parsing.
|
Attachment Handling
| Property | Required | Description |
|---|---|---|
DownloadAttachments |
Optional | Boolean. When true, downloads email attachments and exposes them as binary fields in the trigger output. Only applies when Format is "simple". Ignored for "resolved" and "raw" formats. |
AttachmentsBinaryPropertyPrefix |
Optional | String prefix for binary field names generated from downloaded attachments. Default: "attachment_". Attachments are named sequentially: attachment_0, attachment_1, etc. |
Post-Process Action
| Property | Required | Description |
|---|---|---|
PostProcessAction |
Optional |
Action taken on each email after the trigger fires. Default: "read"."read" — Marks the email as read (sets the IMAP \Seen flag). Prevents the email from matching UNSEEN searches in future polls."delete" — Permanently deletes the email from the mailbox after processing. Irreversible. Use only when email archival is handled elsewhere."nothing" — No action. The email remains in its current state. Only UID tracking prevents reprocessing — if UIDs are reset or tracking is disabled, emails will re-trigger.
|
UID Tracking & State
| Property | Required | Description |
|---|---|---|
DownloadEmailOnEveryTrigger |
Optional | Boolean. Default: false. When true, disables UID tracking entirely and re-downloads all emails matching the search criteria on every poll cycle. This will cause duplicate workflow executions. Use only for testing and development. |
Batch Size
| Property | Required | Description |
|---|---|---|
BatchSize |
Optional | Integer between 1 and 100. Default: 20. Maximum number of emails to process per poll cycle. When more emails match the search criteria than BatchSize allows, the excess are deferred to the next poll cycle (they will be caught by UID tracking). Prevents poll cycles from generating excessive concurrent executions. |
Timeout Settings
| Property | Required | Description |
|---|---|---|
AuthTimeoutSeconds |
Optional | Seconds to wait for IMAP authentication to complete. Default: 20. Increase for slow or geographically distant IMAP servers. |
CommandTimeoutSeconds |
Optional | Seconds to wait for an IMAP command response (e.g. SEARCH, FETCH). Default: 30. Increase when fetching large numbers of messages or large attachments. |
ConnectionTimeoutSeconds |
Optional | Seconds to wait for the initial TCP connection to be established. Default: 15. Increase for IMAP servers on high-latency networks. |
Gmail IMAP access: Gmail requires IMAP access to be enabled in Gmail settings (Settings → See all settings → Forwarding and POP/IMAP → Enable IMAP). If the account has 2-Step Verification enabled, you must generate and use an App Password — the regular account password will not work. Use
imap.gmail.com on port 993 with Tls: true.
Common IMAP Server Settings
| Provider | Host | Port | TLS |
|---|---|---|---|
| Gmail | imap.gmail.com | 993 | true |
| Microsoft 365 / Outlook.com | outlook.office365.com | 993 | true |
| Yahoo Mail | imap.mail.yahoo.com | 993 | true |
| Apple iCloud | imap.mail.me.com | 993 | true |
| Custom / On-premise | Your server hostname | 993 or 143 | Depends on server config |
PostProcessAction: "delete" permanently removes emails from the IMAP server with no recovery path. Ensure your email archival and compliance requirements are met by other means before enabling this action.