IMAP Source Node

The imapsource node polls an IMAP email mailbox on a configurable schedule and emits each fetched email as an record into the pipeline.

The source connects to an IMAP server over SSL/TLS (by default), applies an optional search filter to narrow the messages retrieved, and marks fetched messages as read to prevent re-processing on the next poll cycle. Both password and OAuth2 authentication are supported.

Key Features

• Scheduled polling: fetches new messages at a configurable interval via pollIntervalMs
• IMAP search filter support: use searchCriteria to narrow fetched messages to only those matching a supported IMAP search expression
• Duplicate prevention: marks messages as read after fetching so they are not re-emitted on subsequent polls
• Optional attachment extraction: include full attachment data in the emitted record by enabling includeAttachments
• Flexible authentication: supports PASSWORD and OAUTH2 authentication methods

Configuration

Field	Type	Required	Default	Description
host	String	Yes	—	IMAP server hostname or IP address
port	int	No	993	IMAP server port
credentialId	String	Yes	—	ID of credentials in jobContext.otherProperties
authType	String	No	PASSWORD	Authentication type: PASSWORD or OAUTH2
folder	String	No	INBOX	Mailbox folder to read from
searchCriteria	String	No	—	IMAP search filter (e.g. UNSEEN, FROM admin@example.com)
pollIntervalMs	long	No	60000	How often to poll for new messages, in milliseconds
markAsRead	boolean	No	true	Mark fetched messages as read to avoid re-processing
includeAttachments	boolean	No	false	Include attachment data in the emitted record
useSsl	boolean	No	true	Enable SSL/TLS for the connection
maxMessages	int	No	100	Maximum messages fetched per poll cycle

IMAP Search Criteria

The searchCriteria field accepts one of the following supported expressions. Any other value causes the source to fail with an "Unsupported search criteria" error.

Criteria	Description
UNSEEN	Only messages not yet marked as read
SEEN	Only messages already marked as read
FROM alerts@example.com	Messages from a specific sender
SINCE 2024-01-01	Messages received on or after a date (yyyy-MM-dd)
SUBJECT Critical Alert	Messages whose subject contains the given text

If searchCriteria is omitted and markAsRead is false, all messages in the folder up to maxMessages are fetched each poll cycle. When markAsRead is true (the default), an unread-only (UNSEEN) filter is always applied — and if a searchCriteria is also set, the effective filter is that criteria combined with UNSEEN.

DAG Example

jobContext:
  otherProperties:
    imap-cred:
      username: alerts@example.com
      password: mypassword
  metricTags: {}
  dlqConfig:

dag:
  - id: "source"
    commandName: "imapsource"
    config:
      host: "imap.example.com"
      port: 993
      credentialId: "imap-cred"
      authType: "PASSWORD"
      folder: "INBOX"
      searchCriteria: "UNSEEN"
      pollIntervalMs: 60000
      markAsRead: true
      includeAttachments: false
      useSsl: true
      maxMessages: 100
    outputs:
      - "sink"

  - id: "sink"
    commandName: "stdout"
    config:
      encodingType: "JSON_OBJECT"

Related Nodes

• smtpsink: Send emails via SMTP for each pipeline record
• kafkasource: Read messages from a Kafka topic