IMAP plug-in structure

In this topic you can find information about configuring IMAP email event sources and IMAP email event conditions.

The IMAP email event trigger operates as a persistent service that periodically polls a remote IMAP server to detect new, unseen emails. When a new email is detected, the plug-in generates a workflow event based on the email contents.

Configuring an IMAP event source

A generic event source that receives IMAP email event types can be configured in the following way:

host
  • Type: string (FQDN/IP)
  • Required

The FQDN or IP address of the mail server you want to connect to.

Note: FQDN stands for Fully Qualified Domain Name, which is the complete domain name for a specific computer or host.
port
  • Type: integer (1-65535)

The port used to connect to the mail server. Defaults to 993 or 143 dynamically based on the useSSL setting.

username
  • Type: string
  • Required

The username used for authentication.

password
  • Type: string
  • Required
  • isPassword

The password used for authentication. Passwords must be stored and retrieved from the secure secrets management service.

imapFolder
  • Type: string
  • Default: INBOX

The mailbox path or folder to monitor for new unseen messages.

pollingSeconds
  • Type: integer

The time interval, in seconds, to poll the IMAP server for new messages.

acknowledgmentAction
  • Type: enum (READ, MOVE, DELETE)
  • Default: READ

The action the engine performs on the email after it has been successfully processed and the event has been generated.

moveToImapFolder
  • Type: string

The folder to move the processed email to. This field is conditionally required if acknowledgmentAction is set to MOVE.

useSSL
  • Type: boolean
  • Default: true

Controls the security mode of the connection. If true, the connection prioritizes secure methods. If false (Insecure Mode), it establishes a plain TCP connection on the configured port.

useStartTls
  • Type: boolean

Only evaluated if useSSL is true and the port is 143. The security logic follows this decision tree:

  • Port 993: Establishes an IMAPS connection (TLS tunnel first).
  • Port 143 and useStartTls is true: Establishes a plain connection and immediately issues the STARTTLS command after capability detection.
  • Port 143 and useStartTls is false: The connection is rejected with an error stating that TLS is required but not configured correctly for port 143.

Example

The following is an example of a generic type event source configured to receive IMAP email events:

$eventsource
                EVENT_SOURCE /IMAP_ORDERS
                DESCRIPTION "Monitors the orders@company.com inbox for new purchase orders"
                PLUGIN IMAP
                TYPE Generic
                CONFIGURATION
                {
                "host": "imap.company.com",
                "port": "993",
                "username": "orders_user",
                "password": "${credentials.IMAP_ORDERS_PASSWORD}",
                "imapFolder": "INBOX",
                "acknowledgmentAction": "MOVE",
                "moveToImapFolder": "ProcessedOrders",
                "pollingSeconds": "30"
                }
                END

Configuring an IMAP event condition

When you create an event condition to trigger a workflow based on an IMAP email event, the resulting workflow event payload is a consistent JSON structure. You can specify any number of properties to filter the events received from the event source.

Note: Email attachments are not included in the payload for this version.
messageId
  • Type: string
  • Operator: EQ("=") or NE("!=")
  • Wildcard allowed: true

The unique message ID header or UID of the email.

subject
  • Type: string
  • Operator: EQ("=") or NE("!=")
  • Wildcard allowed: true
  • Case sensitive: false

Specify the email subject line to filter events that match the specified input.

sender.name
  • Type: string
  • Operator: EQ("=") or NE("!=")
  • Wildcard allowed: true

The display name of the email sender.

sender.email
  • Type: string
  • Operator: EQ("=") or NE("!=")
  • Wildcard allowed: true

The email address of the sender (for example, sender@example.com).

to, cc, bcc
  • Type: list/string
  • Operator: EQ("=") or NE("!=")
  • Wildcard allowed: true

The arrays of recipients included in the To, Cc, or Bcc fields.

body
  • Type: string
  • Operator: EQ("=") or NE("!=")
  • Wildcard allowed: true

The plain text content of the email body.

receivedAt / sentDate
  • Type: date/time (ISO 8601 timestamp)
  • Filtering allowed

The timestamp indicating when the email was sent or received.

headers
  • Type: json/map
  • Operator: JSONATA("jsonata")

The JSON object containing the email headers.

isBodyTruncated
  • Type: string

A boolean flag (true or false) indicating if the plain text content of the email exceeded payload limits and was truncated.

replyTo
  • Type: string

The reply-to address specified in the email.