Email Trigger

Configure email-based process triggers to automatically start process instances when emails are received. Email Triggers connect to IMAP mail servers and monitor specific mailboxes to initiate workflows.

New in 5.4.0

Email Trigger is a new data source type that enables process instances to be automatically started when emails are received, bringing event-driven automation to your email workflows.

Overview

Email Trigger is a data source type in Integration Designer that allows FlowX.AI processes to be triggered automatically when emails arrive in a monitored mailbox. This enables use cases such as:

• Customer support automation: Automatically create support tickets when emails arrive
• Document processing: Trigger document workflows when emails with attachments are received
• Request handling: Start approval processes based on incoming email requests
• Notification workflows: Process automated alerts from monitoring systems

---

How it works

The Email Trigger system follows a straightforward flow:

1. Configure Email Connection

   Set up an IMAP connection to your email server as a Data Source in Integration Designer.

2. Link to Message Start Event (Start Catch Message)

   Connect the Email Trigger to a Message Start Event node in your process definition.

3. Activate the Trigger

   Enable monitoring from the Manage Triggers section in Runtime Settings.

4. Process Incoming Emails

   When emails arrive, FlowX.AI automatically creates process instances with the email data.

---

Creating an email trigger data source

Prerequisites

Before configuring an Email Trigger, ensure you have:

• Access to Integration Designer with appropriate permissions
• IMAP server credentials (host, port, username, password)
• Knowledge of the mailbox folder to monitor (defaults to Inbox if not specified)

Step 1: Access Integration Designer

1. Navigate to FlowX Designer → Workspaces → Your workspace → Projects → Your project → Integrations → Data Sources
2. Click Add New Data Source
3. Select Email Trigger as the data source type

Step 2: Configure connection settings

Configure the IMAP connection with the following fields:

Protocol · string · required

The email protocol to use. Currently only IMAP is supported.

Server Host · string · required

The hostname or IP address of your IMAP server.

Examples:

• imap.gmail.com
• outlook.office365.com
• mail.yourcompany.com

This field accepts configuration parameters. Use ${configParam} syntax to reference environment-specific values.

Port · number · required

The port number for the IMAP connection. The default value updates automatically based on the SSL/TLS setting.

SSL/TLS	Default Port
ON	993
OFF	143

Username · string · required

The email account username or full email address used for authentication.

This field accepts configuration parameters for environment-specific credentials.

Password · string · required

The password or app-specific password for the email account.

For Gmail and other providers with 2FA enabled, you may need to generate an app-specific password.

Store sensitive credentials in configuration parameters and reference them here using ${configParam} syntax.

SSL/TLS · boolean

Enable secure connection using SSL/TLS encryption. Recommended: enabled.

The SSL/TLS setting determines the default port value. Change this setting before adjusting the port.

Step 3: Test the connection

Click the Test Connection button to verify your settings:

Result	Message	Action
✅ Success	”Established connection”	Proceed to save
❌ Error	”Failed to establish connection”	Check credentials and server settings

When you click Create, another authentication test is performed. If the test fails, you’ll be redirected to the Authorization tab with an error message, but the Email Trigger will still be created.

Step 4: Configure basic information

Name · string · required

A unique, descriptive name for the Email Trigger.

Validation rules:

• Required field
• Must be unique within the project
• Only letters, numbers, and these characters allowed: [], (), ., _, -
• Minimum 3 characters, maximum 50 characters

Description · string

Optional description explaining the purpose of this Email Trigger.

---

Configuring email trigger settings

After creating the Email Trigger, configure monitoring and validation settings in the Settings tab.

Filtering criteria

Define which emails should trigger processes:

Email Address · string

The email address being monitored. This field is read-only and reflects the authenticated account.

Mailbox Folder · string · required

The mailbox folder to monitor for incoming emails.

Default: Inbox

Examples:

• Inbox
• Support
• Orders/New

This field accepts configuration parameters for environment-specific folder names.

Validations

Configure validation rules for incoming emails. If any validation fails, the email will not be processed and a warning will appear in the Failed Triggers section.

Allowed File Types · array

Restrict which attachment file types are accepted:

Type	Extensions
PDF	.pdf
DOCUMENT	.doc, .docx, .txt
IMAGE	.png, .jpg, .jpeg
EXCEL	.xls, .xlsx, .csv
ZIP	.zip

Leave empty to accept all file types.

Maximum File Size · number

Maximum allowed size per attachment file.

Default: 25 MB
Maximum: 25 MB

Maximum File Count · number

Maximum number of attachments allowed per email.

All fields in the Settings section accept configuration parameters, enabling environment-specific configurations.

Polling interval

The Email Trigger polls for new emails every 30 seconds by default. This interval can be configured at the environment level but is not user-configurable in the UI.

---

Connecting to a Message Start Event

To use the Email Trigger, connect it to a Message Start Event node in your process definition.

Configuring the Message Start Event

1. Open your process definition in the Process Designer
2. Add a Message Start Event node
3. In the node configuration, locate the Process Trigger section:

Trigger Type · select · required

Select the trigger type:

• Internal Throw Message Event (default) - Traditional message-based triggering
• Email Trigger - Email-based triggering

Email Trigger · select · required

Select the Email Trigger data source to use. Only Email Triggers created in the current project are available.

Tooltip: “The email connection that will be triggered”

To start monitoring, you must activate the trigger from Manage Triggers in Runtime Settings.

---

Email data schema

When an email triggers a process, the following data structure is available in your process variables:

{
  "emailMessage": {
    "subject": "Support Request #12345",
    "dateTime": "2026-01-15T10:30:00Z",
    "sender": "[e-mail]",
    "body": "Email body content...",
    "fileAttachments": [
      {
        "filePath": "email-attachments/proc-123/invoice.pdf",
        "downloadPath": "/api/internal/files/uuid-456/download"
      }
    ],
    "headerParams": {
      "Message-ID": "<[e-mail]>",
      ...
    }
  }
}

Schema fields

Field	Type	Description
subject	string	Email subject line
dateTime	string (ISO 8601)	Timestamp when email was received
sender	string	Sender’s email address
body	string	Email body content (plain text)
attachments	array	List of attachment metadata objects
fileAttachments[].filePath	string	Storage path in Document Plugin
fileAttachments[].downloadPath	string	API path to download the file
headerParams.Message-ID	string	Unique email message identifier

Attachment handling

Email attachments are automatically:

1. Uploaded to the Document Plugin as temporary files
2. Copied to permanent storage linked to the process instance
3. Referenced in the fileAttachments array with download paths

Attachment processing happens asynchronously. The file copy to permanent storage may complete after the process instance starts. If your process needs to access attachments immediately, consider adding a wait step.

---

Managing triggers at runtime

Accessing Manage Triggers

Navigate to Runtime Settings → Manage Email Triggers to view and control all configured Email Triggers.

Trigger list columns

Column	Description
State	Current status: Active or Inactive
Process Name	The process definition linked to this trigger
Trigger Type	Always “Email Trigger” for email-based triggers
Event Name	The Email Trigger data source name
Location	Project and branch information

Activation requirements

For an Email Trigger to appear in Manage Triggers:

1. ✅ Email Trigger must be created as a Data Source
2. ✅ Email Trigger must be added to a Message Start Event node
3. ✅ The process must be part of a build in the Active Policy

When the Active Policy changes, Email Triggers retain their previous state (Active/Inactive). If an Email Trigger is deleted from the latest build, it will be automatically deactivated.

Activating and deactivating triggers

Use the toggle in the State column to activate or deactivate monitoring:

• Active: The system monitors the mailbox and creates process instances for incoming emails
• Inactive: Monitoring is paused; no new process instances are created

---

Handling failed triggers

When emails fail validation or processing errors occur, they appear in the Failed Triggers section.

Accessing Failed Triggers

Navigate to Runtime Settings → Failed Triggers to view failed email processing attempts.

Failed Triggers list

Column	Description
Timestamp	Date and time (localized)
Trigger Type	”Email Trigger”
Trigger Name	The Email Trigger data source name
Cause Type	Type of failure
Context	Additional info, e.g., “Sender: [e-mail]”

Cause types

File type not permitted

Message: “The file {filename} could not be uploaded because it is not on the list of permitted file types.”

Resolution: Update the Allowed File Types in the Email Trigger settings, or ask the sender to use an accepted format.

File size exceeded

Message: “{filename} is too large. Maximum allowed: 25 MB”

Resolution: The attachment exceeds the maximum file size limit. Ask the sender to reduce the file size or split into multiple emails.

File count exceeded

Message: “File limit exceeded. For this Email Trigger there is a limit of {limit} per email.”

Resolution: The email contains more attachments than allowed. Ask the sender to split attachments across multiple emails.

Unable to connect to email server

Message: “We couldn’t connect to your email server. This might be due to:

• Incorrect server settings
• No internet connection
• Firewall blocking the connection

Please check your connection and try again.”

Resolution: Verify the IMAP server settings in the Email Trigger Authorization tab and test the connection.

Failed trigger details

Click on a failed trigger to view detailed information:

• Go to Process Definition - Link to edit the process (requires config rights)
• Build - Build identifier
• Project/Library - Source project or library
• Build created from - Branch name
• Project/Library version ID - Version identifier
• Monitored Email Address - The email account being monitored
• Monitored Inbox folder - The mailbox folder being monitored
• Email Subject - Subject of the failed email
• Email Sender - Sender address
• Timestamp - Received time (not localized)
• Cause Type - Failure classification
• Message - Detailed error description

If an email fails for multiple reasons, all failure causes are listed in the details view.

---

Use cases

Customer support ticket creation

1. Configure Email Trigger

   Create an Email Trigger connected to your support email (e.g., [e-mail]).

2. Design the process

   Create a process that:

   • Extracts customer information from the email
   • Creates a ticket in your CRM
   • Assigns to the appropriate team
   • Sends an acknowledgment email
3. Handle attachments

   Configure validation to accept relevant file types (PDF, images) and route attachments to your document management system.

Document processing workflow

Email received with attachments
       ↓
Extract document metadata
       ↓
Classify document type (invoice, contract, etc.)
       ↓
Route to appropriate processing workflow
       ↓
Notify relevant stakeholders

---

Best practices

Use Configuration Parameters

Store server credentials and environment-specific settings in configuration parameters for easy management across environments.

Set Appropriate Validations

Configure file type, size, and count limits to prevent processing of unwanted or malicious content.

Monitor Failed Triggers

Regularly review the Failed Triggers section to identify issues with email processing.

Handle Attachments Async

Remember that attachment processing is asynchronous. Design your process to handle potential delays in file availability.

Security Note: Email attachments are uploaded without virus scanning in the current implementation. Consider implementing additional security measures for sensitive environments.

---

Troubleshooting

Email Trigger not appearing in Manage Triggers

Ensure all requirements are met:

1. Email Trigger is created as a Data Source
2. Email Trigger is linked to a Message Start Event
3. The process is included in an Active Policy build

Connection test fails

Common causes:

• Incorrect credentials: Verify username and password
• Wrong port: Use 993 for IMAP with SSL/TLS
• Firewall: Ensure outbound connections to the mail server are allowed
• 2FA enabled: Generate an app-specific password for the email account

Emails not triggering processes

Check:

1. Is the trigger Active in Manage Triggers?
2. Is the correct mailbox folder configured?
3. Do incoming emails pass validation rules?
4. Review Failed Triggers for error details

Attachments not available in process

Attachment processing is asynchronous. If you need immediate access:

1. Add a wait step or message catch event after the start node
2. Verify the email passed file validation rules
3. Check Document Plugin connectivity

---

Related documentation

Email Sender

Configure SMTP connections to send and reply to emails from processes

Send Notification Action

Send emails and reply to received emails directly from process nodes

Integration Designer

Learn about other data source types and workflow creation

Message Start Event

Configure message-based process triggers

Document Plugin

Manage files and attachments in FlowX.AI

Configuration Parameters

Use environment variables for flexible configurations