Email Trigger - FlowX.AI

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

For Microsoft Outlook mailboxes, you can also use the Microsoft Outlook data source which connects via the MS Graph API and supports both reading and sending emails in a single data source.

Email Trigger vs Microsoft Outlook

	Email Trigger + Email Sender	Microsoft Outlook
Protocol	IMAP (read) + SMTP (send)	MS Graph API
Authentication	Username + password / app password	Azure AD (client credentials)
Read + Send	Two separate data sources	Single data source (Read & Send scope)
Reply threading	Manual — requires `Message-ID` header forwarding	Native — uses MS Graph message ID to maintain conversation threads
Provider support	Any IMAP/SMTP-compatible mail server	Microsoft 365 / Outlook only
Best for	Gmail, self-hosted mail servers, or mixed environments	Organizations using Microsoft 365

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:

Configure Email Connection

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

Link to Message Start Event (Start Catch Message)

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

Activate the Trigger

Turn on monitoring from the Manage Triggers section in Runtime Settings.

Process Incoming Emails

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

An Email Trigger can also start an integration workflow: bind it on the workflow’s Start node instead of a Message Start Event. The email arrives in the workflow’s data model as emailMessage. For details, see External triggers.

Email Triggers process only new emailsAn Email Trigger only processes emails that arrive after the trigger is activated for the first time. Existing emails in the mailbox — whether read or unread — are never picked up retroactively.This applies to reactivation as well: if you deactivate and then reactivate a trigger, only emails that arrive after the reactivation are processed. Anything that landed in the mailbox during the inactive period is ignored.For IMAP triggers, the email must also still be unread in the monitored folder when the trigger picks it up.

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

Navigate to Data Sources

Navigate to FlowX Designer → Workspaces → Your workspace → Projects → Your project → Integrations → Data Sources

Add a new data source

Click Add New Data Source

Select Email Trigger

Select Email Trigger as the data source type

Step 2: Configure connection settings

Configure the IMAP connection with the following fields:

string

required

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

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.

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`

string

required

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

This field accepts configuration parameters for environment-specific credentials.

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.

boolean

Turn on secure connection using SSL/TLS encryption. Recommended: ON.With SSL/TLS on, the mail server’s certificate is verified: it must be signed by a trusted authority and match the server’s host name. Test Connection and the trigger fail against a server with a self-signed, private-CA, or mismatched certificate. On self-hosted deployments, add the server’s CA to the Email Gateway trust store or list the host in EMAILGATEWAY_IMAP_SSLTRUSTEDHOSTS. See IMAP configuration in the Email Gateway setup guide.

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

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

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:

string

required

The mailbox folder to monitor for incoming emails.Default: INBOXExamples:

INBOX
Support
Orders/New

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

Trigger condition and attachment forwarding

Email Trigger validation uses a two-stage model:

Start Process for — which incoming emails should create a process instance.
Save email attachments on process — which attachments are forwarded into the process data.

If a trigger condition fails, the email is rejected and appears in the Failed Triggers section. If an attachment is filtered out by the forwarding mode, it is dropped silently and no Failed Trigger is recorded.

Start Process for

Select which incoming emails create a process instance.

radio

Start the process for all emails received in the selected mailbox folder.

radio

Start the process only when the email has at least one attachment. Emails without attachments are rejected with cause No attachments.

radio

Start the process if at least one attachment matches the selected file types. The Allowed File Types multiselect activates. Emails without a matching attachment are rejected with cause No matching file types.Earlier releases selected allowed types from the file type categories below.

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

Individual file extensionsAllowed File Types and Forward File Types select individual file extensions instead of these categories. The categories no longer exist in the runtime, so the table above serves only as a reference for what each one used to cover.Selected extensions are stored as bare uppercase values without a leading dot (PDF, DOCX). Input is tolerant of case and of a leading dot, so pdf and .pdf resolve to the same extension. Existing triggers are migrated automatically, with each stored category expanded into the individual extensions it covered.

Save email attachments on process

Select which attachments from the email are passed into the process.

radio

Save all attachments from the email to the process instance.

radio

No files are forwarded. Only email metadata (subject, body, sender, headers) reaches the process. The Maximum File Size field is disabled.

radio

Save only attachments that match the selected file types. The Forward File Types multiselect activates. Non-matching attachments are dropped silently (no Failed Trigger entry).

Limits

number

Maximum number of attachments allowed per email. If exceeded, the email is rejected at the trigger level and appears in Failed Triggers with cause File count exceeded.Leave empty for no limit.

number

Maximum allowed size per attachment file, in megabytes. Applies across all forwarding strategies.Maximum allowed value: 25 MBLeave empty to apply no per-file size limit beyond the 25 MB hard cap.

Triggers migrated from an earlier deploymentWhen a deployment is upgraded, existing triggers are set to All incoming emails + All attachments. The Allowed File Types value is preserved on the trigger but no longer filters anything until you switch the trigger condition or forwarding mode to one of the file-type options. Reopen each trigger after the upgrade to confirm the new settings match your intent.

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

Open your process definition

Open your process definition in the Process Designer.

Add a Message Start Event node

Add a Message Start Event node.

Configure the Process Trigger

In the node configuration, locate the Process Trigger section:

select

required

Select the trigger type:

Internal Throw Message - Traditional message-based triggering
Email Trigger - Email-based triggering
Incoming Webhook - Webhook-based triggering (see the Incoming Webhooks data source)

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": "customer@example.com",
    "replyTo": ["replies@example.com"],
    "body": "Email body content...",
    "fileAttachments": [
      {
        "filePath": "email-attachments/proc-123/invoice.pdf",
        "downloadPath": "internal/files/uuid-456/download"
      }
    ],
    "headerParams": {
      "Message-ID": "<abc123@example.com>",
      ...
    }
  }
}

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
`replyTo`	array of strings	Reply-To addresses from the email header. Use these when sending a reply via the Email Sender or Send Notification Action
`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:

Uploaded to the Document Plugin as temporary files
Copied to permanent storage linked to the process instance
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. Upload retries on InterruptedException only — up to 3 attempts with exponential backoff totaling roughly 7 seconds. Other failures (network, document plugin errors) fail fast.

Forwarding incoming attachments to a reply

The inbound fileAttachments[] shape (filePath, downloadPath) differs from the outbound shape expected by the Send Notification action’s Attachments field (path, filename). To forward original attachments on a reply, transform emailMessage.fileAttachments into the Send Notification shape — typically in a Script node — and pass the result through a process variable:

const replyAttachments = emailMessage.fileAttachments.map(f => ({
  path: f.filePath,
  filename: f.filePath.substring(f.filePath.lastIndexOf('/') + 1)
}));

Reference the resulting variable (for example, ${replyAttachments}) in the Send Notification action’s Attachments field.

Managing triggers at runtime

Accessing Manage Triggers

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

Trigger list columns

Column	Description
State	Current status: `Active` or `Deactivated`
Trigger Type	Always “Email Trigger” for email-based triggers
Event Name	The Email Trigger data source name
Location	Dependency app name, or `Local` for the current build

Activation requirements

For an Email Trigger to appear in Manage Triggers:

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

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

All Email Trigger configuration changes and runtime actions (activation, deactivation, trigger events) are recorded in the audit trail for compliance and debugging purposes.

Activating and deactivating triggers

Open the row menu (⋮) on the trigger and select Activate or Deactivate, then confirm. The State column updates to:

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

Testing with mock email content

When running a process from the build list, you can provide mock email content to simulate an incoming email trigger. This is useful for:

Testing process logic before connecting to a live mailbox
Verifying attachment handling and validation rules
Debugging email-triggered workflows in development

How to test with mock email

Open the start process dialog

Navigate to your process definition and click Start Process. If the process has a Message Start Event configured with an Email Trigger, the dialog displays a mock email form instead of the standard start parameters.

Fill in the mock email fields

Complete the form fields to simulate an incoming email:

Field	Description
Subject	The email subject line
Sender	The sender email address
Datetime	When the email was “received” (defaults to the current date and time)
Body	The email body content
Upload files	Attach files to simulate email attachments. Accepted types: PDF, DOCUMENT (.doc, .docx, .txt), IMAGE (.png, .jpg, .jpeg, .tif, .tiff, .gif), EXCEL (.xls, .xlsx, .csv), ZIP (.zip), up to 25 MB
Theme	Select the theme to use for the process instance

Start the process

Click Start Process to create a process instance using the mock email data, just as if a real email had been received.

Use mock testing to validate your process handles edge cases — emails without attachments, emails with multiple Reply-To addresses, or emails with large body content.

Handling failed triggers

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

Accessing Failed Triggers

Navigate to Runtime → Processes → 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: customer@example.com”

Cause types

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.

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.

Message: “File limit exceeded. For this Email Trigger there is a limit of {limit} files per email.”Resolution: The email contains more attachments than the trigger-level Maximum File Count. Ask the sender to split attachments across multiple emails, or raise the limit on the trigger.

Message: “Email rejected: no attachments matching the allowed file types {types} were found.”Resolution: The trigger is configured to Start Process for → Only emails with these attachment file types, and none of the inbound attachments matched the Allowed File Types list. Ask the sender to use an accepted format or widen the allowed list.

Failed trigger details page

Click on a failed trigger row to open the dedicated details page, which displays:

Field	Description
Email Subject	Subject line of the failed email
Email Sender	Sender address
Timestamp	When the email was received
Cause Type	Failure classification
Error Details	Detailed error description, displayed in a code editor for easy reading
Build Status	Whether the associated build is WIP or Committed
Monitored Email Address	The email account being monitored
Monitored Inbox Folder	The mailbox folder being monitored
Process Definition	Link to navigate to the process definition (requires config rights)
Build	Build identifier
Project/Library	Source project or library
Build Created From	Branch name
Project/Library Version ID	Version identifier

Use the breadcrumb navigation at the top of the page to return to the failed triggers list.

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

Use cases

Customer support ticket creation

Configure Email Trigger

Create an Email Trigger connected to your support email (e.g., support@company.com).

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

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 asynchronously

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:

Email Trigger is created as a Data Source
Email Trigger is linked to a Message Start Event
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
Certificate not trusted: With SSL/TLS on, the server’s certificate must be signed by a trusted authority and match its host name. On self-hosted deployments, trust a self-signed or private-CA certificate as described in IMAP configuration
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:

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

Attachments not available in process

Attachment processing is asynchronous. If you need immediate access:

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

Cookbook: reconcile invoices

See the Email Trigger in a full build: invoices arrive by email, AI extracts them, and exceptions go to a reviewer

Email Sender

Configure SMTP connections to send and reply to emails from processes

Microsoft Outlook

Connect to Outlook via MS Graph API for reading and sending emails

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

​Email Trigger vs Microsoft Outlook

​Overview

​How it works

​Creating an email trigger data source

​Prerequisites

​Step 1: Access Integration Designer

​Step 2: Configure connection settings

​Step 3: Test the connection

​Step 4: Configure basic information

​Configuring email trigger settings

​Filtering criteria

​Trigger condition and attachment forwarding

​Start Process for

​Save email attachments on process

​Limits

​Polling interval

​Connecting to a Message Start Event

​Configuring the Message Start Event

​Email data schema

​Schema fields

​Attachment handling

​Forwarding incoming attachments to a reply

​Managing triggers at runtime

​Accessing Manage Triggers

​Trigger list columns

​Activation requirements

​Activating and deactivating triggers

​Testing with mock email content

​How to test with mock email

​Handling failed triggers

​Accessing Failed Triggers

​Failed Triggers list

​Cause types

​Failed trigger details page

​Use cases

​Customer support ticket creation

​Document processing workflow

​Best practices

Use configuration parameters

Set appropriate validations

Monitor failed triggers

Handle attachments asynchronously

​Troubleshooting

​Related documentation

Cookbook: reconcile invoices

Email Sender

Microsoft Outlook

Send Notification Action

Integration Designer

Message Start Event

Document Plugin

Configuration Parameters

Email Trigger vs Microsoft Outlook

Overview

How it works

Creating an email trigger data source

Prerequisites

Step 1: Access Integration Designer

Step 2: Configure connection settings

Step 3: Test the connection

Step 4: Configure basic information

Configuring email trigger settings

Filtering criteria

Trigger condition and attachment forwarding

Start Process for

Save email attachments on process

Limits

Polling interval

Connecting to a Message Start Event

Configuring the Message Start Event

Email data schema

Schema fields

Attachment handling

Forwarding incoming attachments to a reply

Managing triggers at runtime

Accessing Manage Triggers

Trigger list columns

Activation requirements

Activating and deactivating triggers

Testing with mock email content

How to test with mock email

Handling failed triggers

Accessing Failed Triggers

Failed Triggers list

Cause types

Failed trigger details page

Use cases

Customer support ticket creation

Document processing workflow

Best practices

Troubleshooting

Related documentation