Skip to main content

Search Mail

Searches for mails based on specific criteria (mail folder, sender, receiver, cc, bcc, subject, body and mail id)

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Waits in seconds after executing node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.
info

if ContinueOnError property is true, no error is caught when the project is executed even if Catch node is used.

Input​

  • Client Id - Id of the client to search mails. The ID is created by the Connect node.
  • Mail Folder - Name of the mail folder to search mails. If this property is not set, then "INBOX" is considered as default value.
  • From - Sender of the mails that to be searched.
  • To - Receiver of the mails that to be searched.
  • Cc - Cc of the mails that to be searched.
  • Bcc - Bcc of the mails that to be searched.
  • Subject - Subject of the mails that to be searched.
  • Body - Body of the mails that to be searched.
  • Mail ID - Id of the mails that to be searched.

Output​

  • Messages - Found emails returned as an array of JSON objects.

Options​

  • Credentials - Credentials to be used to search mails. Required if there is no Client Id.
  • Start Date - Beginning of the date range to search mails.
  • End Date - End of the date range to search mails.
  • Read Only - If true, only reads the mails to be returned from the mail server.
  • Only IDs - If true, only id's of the searched mails are fetched.

How It Works​

The Search Mail node performs advanced email searches using IMAP search criteria. Here's the process:

  1. Authentication - Uses Client ID or direct credentials
  2. Folder Selection - Selects the mailbox folder to search
  3. Search Criteria Building - Constructs IMAP search query from provided fields (From, To, Subject, Body, dates, Mail ID)
  4. IMAP Search - Executes search on mail server
  5. Results Retrieval - Fetches full message data or just UIDs (based on Only IDs option)
  6. Return Results - Returns array of matching messages or UIDs

Requirements​

  • Client ID from Connect node OR Credentials from vault
  • Mail Folder - Folder to search (default: INBOX)
  • At least one search criterion - From, To, CC, BCC, Subject, Body, Date Range, or Mail ID

Error Handling​

Error CodeDescriptionResolution
Core.Mail.Search.ErrOnCreateConfig parse errorCheck node configuration
Core.Mail.Search.ErrCredentialsInvalid credentialsVerify vault credentials
Core.Mail.Search.ErrClientIdClient ID not foundEnsure Connect node executed
Core.Mail.Search.ErrSelectCannot select folderVerify folder name exists
Core.Mail.Search.ErrMailIDInvalid Mail IDProvide valid Mail ID (over 0)
Core.Mail.Search.ErrBodyCannot read email bodyEmail may be corrupted
Core.Mail.Search.StartDateInvalid start date formatUse YYYY-MM-DD format
Core.Mail.Search.EndDateInvalid end date formatUse YYYY-MM-DD format
Core.Mail.Search.ErrUidFetchCannot fetch messagesCheck IMAP connection
Core.Mail.ErrConnConnection missingEnsure Connect node executed

Usage Examples​

Example 1: Search by Sender​

{
  "client_id": "{{client_id}}",
  "mail_folder": "INBOX",
  "from": "support@company.com",
  "only_ids": false
}
// Returns all emails from support@company.com

Example 2: Search by Subject and Date Range​

{
  "client_id": "{{client_id}}",
  "mail_folder": "INBOX",
  "subject": "Invoice",
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "only_ids": false
}
// Returns all emails with "Invoice" in subject from January 2024

Example 3: Search by Multiple Recipients​

{
  "client_id": "{{client_id}}",
  "mail_folder": "INBOX",
  "to": "team@company.com,manager@company.com",
  "cc": "hr@company.com"
}
// Returns emails sent to team@company.com OR manager@company.com AND CC'd to hr@company.com
{
  "client_id": "{{client_id}}",
  "mail_folder": "INBOX",
  "from": "notifications@system.com",
  "only_ids": true
}
// Output: Array of UIDs [12345, 12346, 12347]
// Much faster than retrieving full message data

Usage Notes​

  • Multiple Values: Separate multiple addresses with commas (e.g., "user1@example.com,user2@example.com")
  • Search Operators: Multiple criteria use AND logic (all must match)
  • Date Format: Use YYYY-MM-DD format for dates
  • Read Only: Set to true to prevent marking messages as read during search
  • Only IDs: Retrieving only UIDs is much faster for large result sets
  • Mail ID Search: Searches across all folders when Mail ID is provided
  • Body Search: Server-side full-text search in email body
  • Case Sensitivity: Search is generally case-insensitive (depends on server)

Tips​

  • Use Only IDs for Counting: Get count of matching emails without downloading full data
  • Narrow Your Search: Use multiple criteria to reduce result set size
  • Date Ranges: Always specify date ranges for time-based searches
  • Performance: Searching by Mail ID is fastest
  • Folder-Specific: Search only searches the specified folder (except Mail ID search)
  • Body Search Caution: Body searches can be slow on large mailboxes