Email Message Input
Description
Use the step to retrieve messages and their attachments from a mail server using POP3, IMAP or MBOX standard protocols. The step automatically extracts attachments from email files (.eml) that are received as attachments within other emails. This mechanism allows you to access files embedded inside multiple layers of emails.
Limitation
Zoho email IMAP server configuration
Server-side indexing rules control search queries in the Subject field. Queries with fewer than three characters (such as ID, HR, or P0) might return no results, even if matching emails exist. The limitation occurs because IMAP servers typically require at least three characters for search terms.
Configurations
| Field Name | Description |
|---|---|
| General Tab: | Use the General tab to establish the connection to your mail server and define your core email retrieval rules. |
| Step name | Specify the name of the step. This name must be unique in a single workflow. |
| Server Settings: | |
| Source Host | Specify the host address of the mail server. You can use variables in this field, such as ${MAIL_SERVER}. Examples: • For Gmail IMAP: imap.gmail.com • For Gmail POP3: pop.gmail.com |
| Use SSL | Select the checkbox to enable SSL/TLS encryption for a secure connection. For example, incoming connections to the Gmail IMAP server (imap.gmail.com:993) and the Gmail POP server (pop.gmail.com:995) strictly require SSL. Note: Recommended to use SSL for production environments. |
| Username | Specify the username for the target mailbox. The field supports variable values, for example, ${MAIL_USERNAME} |
| Password | Specify the password associated with the target username. The system encrypts the password when you save the configuration. The field supports variable values, for example ${MAIL_PASSWORD} |
| Use proxy | Select the checkbox to route the mail server connection through a proxy. |
| Proxy Host | Specify the Server Host Name or IP address of the proxy. |
| Proxy Port | Specify the port number of the proxy. |
| Proxy Username | Specify the username to authenticate with the proxy server. Note: Use the field only if your proxy requires authentication. |
| Proxy Password | Specify the password to authenticate with the proxy server. The system encrypts the password when saved the configuration. |
| Retrieve emails in reverse order | Select the checkbox to retrieve emails from the newest to the oldest. |
| Fetch in batches | Select the checkbox to retrieve large volumes of emails in smaller, sequential batches. Configure the batches from Settings tab under Batch Settings section. |
| Ignore errors reading fields | Select the checkbox to ignore errors if the mail server does not support retrieving specific message data. |
| Protocol | Select a standard protocol (POP3, IMAP or MBOX) to retrieve emails. Note: To use the POP3 protocol, you must configure the mail server or web application to allow POP3 access. Configuration steps vary by service provider. Example: To configure POP3 for web-based Gmail: 1. Open Gmail settings. 2. Select the Forwarding and POP/IMAP tab. 3. Select option: Enable POP for mail that arrives from now on |
| Timeout and Protocols: | |
| Connection timeout (in milliseconds) | Specify the socket connection timeout value in milliseconds. The default value is infinite. Example: Type 30000 to set a 30-second connection timeout limit. |
| Timeout (in milliseconds) | Specify the socket read timeout value in milliseconds. The default value is infinite. Example: Type 60000 to allow the system 60 seconds to read the data before timing out. |
| Protocols | Select the TLS version to secure the mail server connection. Available versions are: • TLSv1.0 • TLSv1.1 • TLSv1.2 • TLSv1.3 You can select a single version or multiple versions depending on your server requirements. |
| Test Connection | Click to verify the connection to the mail server using your specified settings. This action validates your credentials and server configuration but does not retrieve emails. |
| Settings Tab: | |
| POP3 Settings: | POP3 Settings are enabled if you select POP3 as the connection protocol in the General tab. |
| Retrieve | Select the retrieval scope. You can choose to retrieve all emails or limit the retrieval to a specific number of messages. Available retrieve options are: • All emails • Retrieve first... emails Example: Select All emails to process the entire inbox or select Retrieve first... emails to fetch a smaller batch for processing. |
| Retrieve the ... first emails | Specify the maximum number of emails to fetch. Notes: • This value must be less than or equal to the total number of emails present in the inbox. • The field is available only if Retrieve is selected as Retrieve first... emails Example: Type 50 to retrieve only the first 50 emails from the server. |
| Delete emails after | Select the checkbox to permanently delete the messages from the mail server after the step successfully retrieves them. |
| IMAP Settings: | IMAP Settings are enabled if you set the Protocol as IMAP from the General tab. Note: The javax.mail.FolderClosedException occurs when the mailbox connection is unexpectedly closed (due to timeout or network issues) while processing emails, especially during move operations. It typically indicates that the IMAP session was terminated before completing the folder actions. |
| Get folder from field | Enable this option if you wish to retrieve the IMAP folder name from an input field. |
| Folder field | Select a field containing the folder name. |
| IMAP folder | Specify the name for the IMAP folder to retrieve mails from. Or Click  to select the IMAP folder from the Available folder pop-up window. Click button Test folder... to verify the folder is available and valid. |
| Include subfolders | Select the checkbox to retrieve emails from the selected folder and all its nested subfolders. |
| Retrieve | Select the specific category of emails to fetch. Available options are: • Get all messages: Retrieves every message in the folder without applying filters. • Get new messages: Retrieves messages flagged as newly arrived (RECENT) and not yet seen by any client. • Get old messages: Retrieves messages that are not flagged as new. • Get read messages: Retrieves messages marked as read (SEEN). • Get unread messages: Retrieves messages not marked as read. • Get flagged messages: Retrieves marked or starred messages (FLAGGED). • Get not flagged messages: Retrieves messages without a mark or star. • Get draft messages: Retrieves messages marked as drafts (DRAFT). • Get not draft messages: Retrieves messages not marked as drafts. • Get Answered messages • Get not Answered messages |
| Retrieve the first ... emails | Specify the maximum number of emails to retrieve from the server. Note: The field is enabled only if Protocol is set as IMAP in the General settings. Default Value: 0 |
| Move to Folder | Specify the IMAP folder where emails should be moved after they are processed. This feature works only with IMAP (not supported for POP3). The field supports both static and environment variable values, for example, ${ARCHIVE_FOLDER} Click Test folder to verify whether the specified destination folder exists on the mail server. This helps validate the folder path before running the workflow. To move the email to the folder: Enter the folder name or full path where emails should be moved. For example, • INBOX/Processed • Archive/2024 • Completed Important: • Use the forward slash (/) to define folder hierarchy. For example, INBOX/Processed. • Leave the field empty to disable email movement. Use variables to define IMAP folder, such as ${myVariable} or %%myVariable%% Examples: • INBOX/Archive- Moves emails to Archive inside Inbox • Processed- Moves emails to Processed folder • ${MOVE_TO_FOLDER} - Uses a variable value • Archive/ ${YEAR}/${MONTH} - Moves emails to dynamic folders based on year and month |
| (Button) Select folder | Click the button to open a folder browser displaying all available directories on the mail server. Choose your target folder directly from this list. Example: Navigate the browser to select the INBOX/Invoices folder. |
| Create folder | Select the checkbox to automatically create the destination folder, including any required parent folders if it does not already exist on the mail server. Note: The step fails if the destination folder does not exist. For example, The Move Email to Folder field contains the path: processed_emails/FY_Years/FY_2026. Only the processed_emails folder exists on the server. When you select Create folder: • The system creates folder FY_Years inside processed_emails. • The system creates folder FY_2026 inside folder FY_Years. • The system moves the emails to folder: processed_emails/FY_Years/FY_2026 |
| Batch Settings: | Note: Following fields are available only if Fetch in batches checkbox from General tab is selected. |
| Batch size | Specify the number of emails to retrieve in a single batch operation. Example: Type 50 to process emails in chunks of 50, reducing memory load on large inboxes. |
| Start at message number | Specify the index number of the first message you want to retrieve. Example: Type 1 to begin retrieval from the very first message in the queue. |
| End at message number | Specify the index number of the last message you want to retrieve. Example: Type 500 to stop the retrieval process once the step reaches the 500th message. |
| Attachment Tab: | Use the Attachment tab to configure how the step processes and stores email attachments, including nested .eml files. How .eml Extraction Works • The step saves all attachments from incoming emails to the Attachment Folder. If it detects a .eml file, it parses the file and extracts any embedded attachments to the Extracted attachment location. • If the system encounters nested .eml files inside the parent .eml, it continues extracting based on your configured Maximum .eml extraction depth: ○ Depth of 1: Extracts attachments from the first .eml file only. ○ Depth of 2: Processes the first .eml file and extracts any .eml files nested directly inside it. ○ Depth of 3: Processes up to three levels of nested emails. Important: • If nesting exceeds your configured limit, the system logs a warning, stops extraction, and saves the deepest reached .eml file intact. • The system preserves original file names during extraction. If it detects duplicate file names, it appends a numeric suffix to the new file (for example, invoice_1.pdf, invoice_2.pdf). • If the system cannot save an extracted attachment due to any reason (for example, invalid path or permission issue) the step fails and triggers your standard error-handling logic. • If extraction of even a single file inside an .eml message fails, the step fails. If the workflow includes error handling, it continues execution, but the extraction fails for the step; otherwise, the entire workflow fails. |
| Save Attachments | Select Save Attachments to save or download attachments from incoming emails. If the checkbox is cleared, the step ignores all attachments, including .eml files. Note: When Save Attachments is selected, the following fields become available: Attachment Folder, Extract attachment from .eml, Sanitize attachment filenames?, Deep attachment scan, and Maximum Deep Attachment Scan Depth. |
| Attachment Folder | Specify the folder path to save the attachments. Or Click Select Folder to select a location. |
| Extract attachment from .eml | Select the checkbox to extract attachments embedded inside .eml file. Note: When selected, the following fields are enabled: Preserve .eml file, Extracted .eml attachment location and Maximum .eml extraction depth |
| Preserve .eml file | Select the checkbox to keep the original .eml file after successful extraction. If cleared, the step deletes the .eml file after it successfully extracts the nested attachments and saves only last extracted attachment file. |
| Extracted .eml attachment location | Specify the path to save the extracted attachments from the .eml files. Or Click Select folder to select the required location. |
| Maximum .eml extraction depth | Specify the maximum number of nested email levels to scan for attachments. Limiting the depth prevents infinite recursion when emails are attached within other emails. Allowed Values: 1,2,3 Default Value: 2 |
| Sanitize attachment filenames? | Select the checkbox to replace illegal characters (! @ # / and so on) in attachment filenames with an underscore (_). |
| Deep attachment scan | Select the checkbox to download attachments from the nested emails (for example, .png, .jpg, .pdf, .xlsx and so on). The attachments get downloaded to the location specified in Attachment Folder. Supported protocol: Imap and Pop3 |
| Maximum Deep Attachment scan depth | Specify the maximum number of levels the step scans within nested emails to extract attachments. The field accepts variable or static values Notes: • The allowed scan depth ranges from 1 to 20. • Specifying a value less than 1 (for example, -1 or -10), the step automatically sets the field value to 1. • Specifying a value greater than 20 (for example, 25), the step automatically sets the field value to 20. Default Value: 2 |
| Filters Tab: | Use the Filters tab to define specific criteria based on email message headers. The step evaluates the headers and only processes the messages that match your defined conditions. |
| Sender (FROM) | Specify a sender email address to filter incoming messages. Select the adjacent checkbox to negate this filter, which excludes all emails received from the specified sender. |
| Recipient (To) | Specify a recipient email address to filter messages. Select the adjacent checkbox to negate this filter, which excludes all emails sent to the specified recipient. |
| Subject | Specify text to filter messages by their subject line. This field supports partial matches. Select the adjacent checkbox to negate this filter, which excludes all emails containing this subject text. |
| Received Date | Select a condition from the drop-down list to filter messages based on the date they were received. Select the adjacent checkbox to negate the date filter, which excludes emails that fall within your specified date criteria. Note: The field is enabled only if Protocol is set as IMAP. |
| Condition | Select the comparison condition for the received date filter from the list: • None • Equal to • Smaller than • Greater than • Between to .. and .. |
| Date 1 | Specify the primary date and time for your filter condition. Or Click  and select the required date and time Example: 2026-05-15 14:40:26 |
| Date 2 | Specify a secondary date and time if your selected condition requires a date range. Or Click and select the required date and time. Note: The field is available only if you select Condition as Between to .. and .. |
| Limit Size | Specify the maximum number of email messages the step outputs as rows. Important: This mechanism differs from the Retrieve first...emails setting. The retrieve setting limits how many emails the step fetches from the server, while Limit Size restricts the final output regardless of how many emails the step initially retrieved. Examples: • Specify 0 to apply no limit and output all matching emails. • Specify 100 to output only the first 100 matching emails. Use a variable like ${EMAIL_LIMIT} to apply a dynamic limit. Note: The system disables this field if you select the Use Dynamic Folder setting, as the limit applies per folder in that scenario. |
| Fields Tab: | Use the Fields tab to map specific email attributes to output columns for downstream |
| Name | Select the specific email attributes you want to extract and output as fields. Example: Select attributes like Subject, Sender, or Body. |
| Column | Select the destination column name for the corresponding email attribute. |
| Secret | Select Y to mark the field as a secret. The step masks the value (displays ********) in subsequent steps, previews, and logs. To protect the data, the step excludes the field by default when writing to an output file or database. Useful for masking email body content, headers, or attachment metadata Select N to keep the field value visible as plain text. The step displays the actual value in previews and logs and writes it to the output file or database. Note: If a secret field is combined with plain text in an earlier step (for example, using a Calculator step to create "Token: " + secretField), the result is treated as a new field and is not protected automatically. Mark the new field as Secret to protect its value. |
| Get fields | Click the button to automatically populate the table with the available email attributes based on your configuration. |
| Keep HTML Tags in the Body | Select the checkbox if you want the HTML tags to be displayed in the output view. Note: The checkbox is clear by default. |