Email events plug-in structure

The Email events plug-in is an event source connector that enables you to trigger workflows based on email messages received in an IMAP mailbox.

The Email events plug-in 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 Email events event source

An Email events event source 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.

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.

maxBodySizeKB
  • Type: integer
  • Default (UI): 512

The maximum size in KB of the email body to include in the event payload. When using the Orchestration CLI, you must specify this value explicitly.

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 an Email events event source configured to monitor an email inbox:

$eventsource
EVENT_SOURCE /IMAP_ORDERS
DESCRIPTION "Monitors the orders@company.com inbox for new purchase orders"
PLUGIN EmailEvents
TYPE Email
CONFIGURATION
{
  "host": "imap.gmail.com",
  "port": "993",
  "username": "example_email@gmail.com",
  "password": "app_password",
  "imapFolder": "INBOX",
  "acknowledgmentAction": "MOVE",
  "moveToImapFolder": "ProcessedOrders",
  "maxBodySizeKB": 512
}
END

Configuring an Email events event condition

When you create an event condition to trigger a workflow based on an 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.
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.

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

The sender field as stored in the event payload, in the format Sender Name <sender@example.com>. To match by email address alone, use a wildcard pattern such as *sender@example.com*.

Note: A bare email address value such as sender@example.com will not match because the stored value includes the display name and angle brackets. Always use wildcards when filtering by email address.
to, cc
  • Type: list/string
  • Operator: EQ("=") or NE("!=")
  • Wildcard allowed: true

The arrays of recipients included in the To and Cc fields. Each element is a string value representing a single recipient address, for example [recipient@example.com].

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

The plain text content of the email body.

bodyHTML
  • Type: string (valid HTML format)
  • Operator: EQ("=") or NE("!=")

The HTML content of the email body.

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.

Example

The following example shows a workflow definition with Email events attribute filters:

$jobstream

JOBSTREAM /CLOUD#/WKF_WITH_EMAIL_EVENT_TRIGGER
  TRIGGER TRIG_FF123 CONDITIONS
    NAME COND1 TYPE "EmailEvents/EmailEvent" SCOPE "From" SOURCE /EMAIL FILTERS to = [example@example.com], subject = example-subject, from = *sender@company.com*
  ENDTRIGGER
:
END