Listeners: IMAP

The IMAP Listener

The IMAP listener node is used to implement email-driven flows. It connects to an IMAP email server, watches for unread emails in a specified mailbox, and starts the flow when emails matching the criteria are detected.

The IMAP listener reads email content and injects it into messages that can be processed by downstream nodes in the flow. It automatically marks processed emails as read to avoid duplicate processing.

The code block below documents the format for the IMAP Listener node.

"listener": {
	"type": "imap",
	"isMessageGenerator": true,
	"host": "imap.gmail.com",
	"port": 993,
	"tls": true,
	"user": "[email protected]",
	"password": "encrypted_password",
	"mailbox": "INBOX",
	"maxmessages": 10,
	"maxEmailSize": 31457280,
	"partsToInject": ["envelope", "text", "html", "attachments"]
}

Configuration Properties

• host - The IMAP server hostname (e.g., imap.gmail.com, outlook.office365.com)
• port - The IMAP server port (typically 993 for secure IMAP, 143 for non-secure)
• tls - Boolean flag to enable TLS/SSL encryption (recommended: true)
• user - The email account username or email address
• password - The encrypted password for authentication (use ASB's crypt utility to encrypt)
• mailbox - The mailbox folder to monitor (defaults to "INBOX" if not specified)
• maxmessages - Maximum number of unread emails to process per cycle (defaults to 10)
• maxEmailSize - Maximum email size in bytes to process (defaults to 30MB or 31,457,280 bytes)
• partsToInject - Array specifying which email parts to include in the injected message:
  • "envelope" - Email metadata (from, to, subject, date, etc.)
  • "text" - Plain text email body
  • "html" - HTML email body
  • "attachments" - Email attachments (encoded as base64)

Message Content Structure

The injected message will contain the following properties based on partsToInject:

• message.content.envelope - Email envelope with from, to, subject, date fields
• message.content.texts - Array of plain text email bodies
• message.content.htmls - Array of HTML email bodies
• message.content.attachments - Array of attachment objects with contentType, filename, data (base64), and encoding

Important Notes

• The property isMessageGenerator must be set to true for this node
• The IMAP listener automatically marks processed emails as read (sets the \Seen flag)
• Emails larger than maxEmailSize are skipped to prevent memory issues
• The listener checks for the "busy" flag to prevent concurrent processing
• OAuth2 authentication is supported through the standard IMAP authentication mechanism
• For Gmail, you may need to enable "Less secure app access" or, better, use App Passwords

Requirements

The IMAP listener requires the NPM package imapflow to be installed.