IMAP Trigger imap-trigger

When to Use

• Invoice processing: Watch an invoices@company.com mailbox and start a data extraction workflow for each new supplier invoice email, pulling the PDF attachment for OCR or structured parsing.
• Order confirmation ingestion: Ingest order confirmation emails from a marketplace or supplier into your ERP by parsing the subject and body fields in a downstream Data Mapping node.
• Support ticket creation: Convert inbound customer support emails into help desk tickets automatically, mapping the sender address, subject, and body to ticket fields.
• Email-based approval workflows: Poll a dedicated approval mailbox for reply emails, extract the approval decision from the body text, and resume a suspended workflow accordingly.
• Automated reply systems: Detect inbound emails matching a subject pattern, generate a contextual reply using an AI Agent node, and route the response through an SMTP node.

Configuration

Connection

Mailbox & Polling

Output Format & Attachments

Timeouts

Sample Configuration JSON

{
  "host": "imap.gmail.com",
  "port": 993,
  "user": "invoices@company.com",
  "password": "{{ $credentials.gmail-app-password }}",
  "tls": true,
  "mailbox": "INBOX",
  "customEmailConfig": "[\"UNSEEN\", \"SUBJECT\", \"Invoice\"]",
  "batchSize": 10,
  "postProcessAction": "read",
  "downloadAttachments": true,
  "attachmentsBinaryPropertyPrefix": "invoice_attachment_",
  "format": "simple"
}

Validation Errors

Output

Success Port — Per Email

One workflow execution fires per email. All fields below are available on the success port:

Attachment Metadata Object

Error Port

Fires on connection failure, authentication failure, mailbox not found, or configuration validation errors. The output contains errorCode and message fields. The trigger pauses polling and retries on the next scheduled interval.

Sample Output JSON

{
  "uid": 4812,
  "messageId": "<CABx1y2z3a4b5c6d7e8f9g@mail.gmail.com>",
  "subject": "Invoice #2026-0512 from Acme Supplies",
  "from": {
    "name": "Acme Supplies Billing",
    "address": "billing@acme-supplies.com"
  },
  "to": [
    { "name": "Invoices", "address": "invoices@company.com" }
  ],
  "cc": [],
  "date": "2026-05-26T07:42:15Z",
  "body": {
    "text": "Please find attached your invoice for May 2026.",
    "html": "<p>Please find attached your invoice for May 2026.</p>"
  },
  "attachments": [
    {
      "fileName": "invoice-2026-0512.pdf",
      "mimeType": "application/pdf",
      "size": 148320,
      "contentId": null,
      "binaryKey": "invoice_attachment_0",
      "error": null
    }
  ]
}

Expression Reference

Node Policies & GuardRails

• Store credentials in Credentials Manager. Reference stored credentials with {{ $credentials.name }}. For Gmail, use an App Password generated in Google Account settings. For Microsoft 365, use an App Password or OAuth token — the primary account password will not work when modern authentication is enforced.
• Keep tls: true in production. IMAP without TLS transmits credentials and email content in plaintext. Only set tls: false in isolated development environments, and never disable allowUnauthorizedCerts in production.
• Never set downloadEmailOnEveryTrigger: true in production. This disables UID deduplication and will cause every matching email to re-trigger on every poll cycle, producing duplicate workflow executions. It exists only for testing purposes.
• Choose postProcessAction deliberately. Use read (the default) for most workflows to prevent re-triggering on the same email. Use delete only when the mailbox is a dedicated processing inbox and emails are not needed after processing. Use nothing only with an alternative deduplication mechanism.
• Scope customEmailConfig tightly. A broad ["UNSEEN"] criteria on a high-volume inbox may fetch hundreds of unrelated emails per cycle. Add FROM, SUBJECT, or SINCE criteria to limit what is fetched to only emails your workflow needs.
• Set reasonable timeouts for remote mail servers. Corporate IMAP servers accessed over VPN or the public internet may be slower than cloud providers. Increase commandTimeoutSeconds if you see intermittent timeout errors rather than reducing batchSize first.

Examples

Invoice Processing — Detect and Extract PDF Attachment

{
  "host": "imap.gmail.com",
  "port": 993,
  "user": "invoices@company.com",
  "password": "{{ $credentials.gmail-invoices-app-password }}",
  "tls": true,
  "mailbox": "INBOX",
  "customEmailConfig": "[\"UNSEEN\", \"SUBJECT\", \"Invoice\"]",
  "batchSize": 5,
  "postProcessAction": "read",
  "downloadAttachments": true,
  "attachmentsBinaryPropertyPrefix": "invoice_",
  "format": "simple"
}

Polls the invoices inbox every cycle for unread emails with "Invoice" in the subject. Each qualifying email triggers a separate workflow run. The PDF attachment is downloaded and available in the binary map under key invoice_0 for an OCR or parsing node downstream. Processed emails are marked as read so they are excluded from the next poll.

Support Ticket Creation from Customer Email

{
  "host": "outlook.office365.com",
  "port": 993,
  "user": "support@company.com",
  "password": "{{ $credentials.outlook-support-app-password }}",
  "tls": true,
  "mailbox": "INBOX",
  "customEmailConfig": "[\"UNSEEN\"]",
  "batchSize": 20,
  "postProcessAction": "read",
  "downloadAttachments": false,
  "format": "simple"
}

Each new email to the support inbox triggers a workflow that maps {{ $output.email.from.address }} to the customer record, {{ $output.email.subject }} to the ticket title, and {{ $output.email.body.text }} to the ticket description. Attachments are not downloaded because the downstream Jira node only requires text fields.

Approval Reply Detection

{
  "host": "imap.gmail.com",
  "port": 993,
  "user": "approvals@company.com",
  "password": "{{ $credentials.gmail-approvals-app-password }}",
  "tls": true,
  "mailbox": "INBOX",
  "customEmailConfig": "[\"UNSEEN\", \"SUBJECT\", \"RE: Approval Request\"]",
  "batchSize": 10,
  "postProcessAction": "delete",
  "downloadAttachments": false,
  "format": "simple"
}

Watches for reply emails to approval requests. The subject filter limits fetching to replies, and postProcessAction: delete removes processed emails from the dedicated approvals mailbox. A downstream Code Execute node inspects {{ $output.email.body.text }} for approval keywords (approved, rejected) to resume the suspended parent workflow.