Fetch Single Mail (Gmail)

Retrieve a specific email from Gmail using message ID or search parameters.

Overview

The Fetch Single Mail (Gmail) field type allows you to retrieve a single, specific email from your Gmail account. Unlike Fetch Mail (Gmail) which returns multiple emails, this field type is optimized for fetching one email at a time, making it ideal for retrieving specific messages by ID or the most recent email matching your criteria.

Configuration Options

Option	Type	Description	Required
Google Service Account	Dropdown	Select logged-in Google account	Yes
Enable Max Results	Switch	Limit number of results	No
Max Results Count	Input	Number of results to return	No
Include Spam/Trash	Switch	Include spam and trash in results	No
Enable Retry on Failure	Switch	Retry if request fails	No
Max Retries (Failure)	Input	Maximum retry attempts on failure	No
Retry Until Mail Received	Switch	Keep retrying until mail is found	No
Max Retries (Until Received)	Input	Maximum retry attempts until mail received	No
Timeout	Input	Timeout duration in seconds	No
Enable Regex Filter	Switch	Filter data with regular expression	No
Regular Expression	Input	Regex pattern to match	No
Regex Replace	Input	Replacement string for regex matches	No
Remove UNREAD Label	Switch	Mark email as read after fetching	No
Search Query	Default Value	Gmail search query	No

Option Details

Google Service Account

Select the Google account you want to use for accessing Gmail.

Type: Dropdown

Description: Choose from your logged-in Google accounts. Make sure the selected account has Gmail access enabled.

Example:

user@gmail.com
work@company.com

Enable Max Results

Enable limiting the number of results returned.

Type: Switch

Options:

ON - Limit number of results
OFF - Return all matching results

Note: For single mail retrieval, it's recommended to set max results to 1.

Max Results Count

Specify the maximum number of emails to return.

Type: Input

Description: Set how many emails should be fetched (Return Max Results).

Recommended Value:

1    (Return only 1 email - most recent)

Note: This option only works when Enable Max Results is turned ON.

Include Spam/Trash

Include emails from Spam and Trash folders in the results.

Type: Switch

Options:

ON - Include spam and trash
OFF - Exclude spam and trash (default)

Enable Retry on Failure

Automatically retry the request if it fails.

Type: Switch

Description: When enabled, the system will retry fetching emails if an error occurs.

Options:

ON - Enable retry on failure
OFF - Don't retry on failure

Use Cases:

Network connectivity issues
Temporary API errors
Rate limiting scenarios

Max Retries (Failure)

Maximum number of retry attempts if the request fails.

Type: Input

Description: Specify how many times the system should retry before giving up.

Example:

3    (Retry up to 3 times)
5    (Retry up to 5 times)
10   (Retry up to 10 times)

Note: This option only works when Enable Retry on Failure is turned ON.

Retry Until Mail Received

Keep retrying until the expected email is received.

Type: Switch

Description: Useful for waiting for verification emails, OTPs, or confirmation messages.

Options:

ON - Retry until mail is found
OFF - Don't retry if mail not found

Use Cases:

Waiting for verification codes
Expecting confirmation emails
Polling for specific messages

Max Retries (Until Received)

Maximum number of retry attempts when waiting for mail.

Type: Input

Description: Specify how many times to retry before giving up.

Example:

10   (Retry up to 10 times)
20   (Retry up to 20 times)
50   (Retry up to 50 times)

Note: This option only works when Retry Until Mail Received is turned ON.

Timeout

Timeout duration in seconds between retry attempts.

Type: Input

Description: Specify how long to wait between each retry attempt.

Example:

5     (Wait 5 seconds between retries)
10    (Wait 10 seconds between retries)
30    (Wait 30 seconds between retries)

Note: This option only works when Retry Until Mail Received is turned ON.

Enable Regex Filter

Filter email data using regular expressions.

Type: Switch

Description: Apply regex patterns to extract or transform email content.

Options:

ON - Enable regex filtering
OFF - Return raw email data

Regular Expression

Regular expression pattern to match in email content.

Type: Input

Description: Define a regex pattern to extract specific data from emails.

Example:

\d{6}                    (Match 6-digit codes)
[A-Z0-9]{8}              (Match 8-character alphanumeric codes)
verification code: (\d+) (Extract verification code)

Note: This option only works when Enable Regex Filter is turned ON.

Regex Replace

Replacement string for regex matches.

Type: Input

Description: Define what to replace matched patterns with. Use $1, $2 for capture groups.

Example:

$1                (Use first capture group)
Code: $1          (Prefix with "Code: ")
$1-$2             (Combine capture groups)

Note: This option only works when Enable Regex Filter is turned ON.

Remove UNREAD Label

Automatically mark email as read after fetching.

Type: Switch

Description: Remove the UNREAD label from emails after they are retrieved.

Options:

ON - Mark as read after fetching
OFF - Keep email as unread

Use Cases:

Prevent duplicate processing
Clean up inbox automatically
Track processed emails

Search Query

Gmail search query to filter emails.

Type: Default Value Field

Description: Use Gmail's powerful search syntax to find specific emails.

Set Query in Default Value

You can set the search query in the "If excel column value is empty then fill this default value" field option.

Example:

from:noreply@example.com subject:verification
is:unread after:2024/01/01
has:attachment larger:5M

Learn More: See Gmail API Search Queries for detailed search syntax and examples.

Differences from Fetch Mail (Gmail)

Feature	Fetch Single Mail	Fetch Mail
Purpose	Retrieve one specific email	Retrieve multiple emails
Mail Parts Selection	Returns complete email	Select specific parts (body, subject, etc.)
Use Case	Get latest/specific message	Search and filter multiple messages
Performance	Faster for single email	Better for bulk operations

Use Cases

Fetch latest verification code - Get the most recent OTP email
Retrieve specific email by ID - Fetch email using message ID
Get confirmation email - Wait for and retrieve confirmation messages
Extract single data point - Get one specific piece of information
Monitor for specific message - Poll for expected email

Practical Examples

Example 1: Get Latest OTP Email

Search Query:

is:unread from:noreply@bank.com subject:OTP

Max Results: 1

Regex Pattern: \d{6}

Remove UNREAD: ON

Example 2: Wait for Verification Email

Search Query:

is:unread subject:"verify your email"

Retry Until Received: ON

Max Retries: 20

Timeout: 10 seconds

Example 3: Get Password Reset Link

Search Query:

is:unread from:noreply@service.com subject:"reset password"

Regex Pattern: https://[^\s]+

Max Results: 1

Custom Filter

For advanced filtering of Gmail data, use a JavaScript event listener in a separate JavaScript Code field type.

Implementation Steps

Use three field types in sequence:

JavaScript Code - Add event listener
Fetch Single Mail (Gmail) - Trigger event and pass email details
getLocalStorage function - Check if filter is complete

JavaScript Event Listener

// Listen Event
window.addEventListener('EDF-SINGLE-GMAIL-RESPONSE', (e) => {
  if (e && e.detail) {
    console.log("Email Data:", e.detail);
    
    // Apply your custom filtering logic here
    // Example: Check if email contains specific text
    if (e.detail.body && e.detail.body.includes('verification code')) {
      // If match found, store value in local storage
      $fns.setLocalStorage("gmail-verification-found", "1");
    }
  }
});

// RETURN - if don't use this line then extension will pause on this field
$fns.return("1");

Event Variable Structure

Event Variable: e.detail

Data Type: Email object

Example Response:

json

{
  "id": "18d4f2a1b3c5e6f7",
  "threadId": "18d4f2a1b3c5e6f7",
  "subject": "Your Verification Code",
  "from": "noreply@example.com",
  "to": "user@gmail.com",
  "body": "Your verification code is: 123456",
  "snippet": "Your verification code is: 123456",
  "date": "2024-01-15T10:30:00Z",
  "labelIds": ["UNREAD", "INBOX"],
  "internalDate": "1705318200000"
}

Email Properties

Property	Type	Description
`id`	string	Unique message ID
`threadId`	string	Thread ID the message belongs to
`subject`	string	Email subject line
`from`	string	Sender email address
`to`	string	Recipient email address
`body`	string	Email body content (plain text or HTML)
`snippet`	string	Short preview of email content
`date`	string	ISO timestamp when email was sent
`labelIds`	array	Gmail labels applied to the email
`internalDate`	string	Internal date timestamp

Usage Examples

Example 1: Extract and Validate OTP

Field 1 - JavaScript Code:

window.addEventListener('EDF-SINGLE-GMAIL-RESPONSE', (e) => {
  if (e && e.detail && e.detail.body) {
    // Extract OTP code (6 digits)
    const otpMatch = e.detail.body.match(/\d{6}/);
    
    if (otpMatch) {
      const otp = otpMatch[0];
      console.log('OTP found:', otp);
      
      // Validate OTP format
      if (otp.length === 6) {
        // Store OTP in local storage
        $fns.setLocalStorage("email-otp-code", otp);
      }
    } else {
      console.log('No OTP found in email');
    }
  }
});

$fns.return("1");

Field 2 - Fetch Single Mail (Gmail):

Search Query: from:noreply@example.com subject:verification
Max Results: 1

Field 3 - getLocalStorage Function:

Function Value: [email-otp-code][true][true]

Result: Extracts OTP from email, stores it, and retrieves it for use.

Example 2: Filter by Sender and Subject

Field 1 - JavaScript Code:

window.addEventListener('EDF-SINGLE-GMAIL-RESPONSE', (e) => {
  if (e && e.detail) {
    const { from, subject, body } = e.detail;
    
    // Check if email is from trusted sender
    if (from.includes('noreply@bank.com') && 
        subject.includes('Transaction Alert')) {
      
      // Extract transaction amount
      const amountMatch = body.match(/\$(\d+\.\d{2})/);
      
      if (amountMatch) {
        const amount = amountMatch[1];
        console.log('Transaction amount:', amount);
        
        // Store amount in local storage
        $fns.setLocalStorage("transaction-amount", amount);
      }
    }
  }
});

$fns.return("1");

Field 2 - Fetch Single Mail (Gmail):

Search Query: from:noreply@bank.com subject:"Transaction Alert"
Max Results: 1

Field 3 - getLocalStorage Function:

Function Value: [transaction-amount][true][true]

Result: Filters bank transaction emails and extracts amount.

Example 3: Verify Email Content

Field 1 - JavaScript Code:

window.addEventListener('EDF-SINGLE-GMAIL-RESPONSE', (e) => {
  if (e && e.detail) {
    // Check if email contains required keywords
    const hasKeywords = e.detail.body.includes('password reset') && 
                        e.detail.body.includes('click here');
    
    if (hasKeywords) {
      // Extract reset link
      const linkMatch = e.detail.body.match(/https:\/\/[^\s]+/);
      
      if (linkMatch) {
        const resetLink = linkMatch[0];
        console.log('Reset link found:', resetLink);
        
        // Store link in local storage
        $fns.setLocalStorage("password-reset-link", resetLink);
      }
    }
  }
});

$fns.return("1");

Field 2 - Fetch Single Mail (Gmail):

Search Query: subject:"Password Reset"
Max Results: 1

Field 3 - getLocalStorage Function:

Function Value: [password-reset-link][true][false]

Result: Extracts password reset link from email.

Example 4: Multi-Condition Filtering

Field 1 - JavaScript Code:

window.addEventListener('EDF-SINGLE-GMAIL-RESPONSE', (e) => {
  if (e && e.detail) {
    const { from, subject, body, date } = e.detail;
    
    // Check multiple conditions
    const isRecent = new Date(date) > new Date(Date.now() - 3600000); // Last hour
    const isFromSupport = from.includes('support@example.com');
    const hasTicketNumber = /Ticket #\d+/.test(subject);
    
    if (isRecent && isFromSupport && hasTicketNumber) {
      // Extract ticket number
      const ticketMatch = subject.match(/Ticket #(\d+)/);
      
      if (ticketMatch) {
        const ticketNumber = ticketMatch[1];
        console.log('Ticket number:', ticketNumber);
        
        // Store ticket number
        $fns.setLocalStorage("support-ticket-number", ticketNumber);
      }
    }
  }
});

$fns.return("1");

Field 2 - Fetch Single Mail (Gmail):

Search Query: from:support@example.com newer_than:1h
Max Results: 1

Field 3 - getLocalStorage Function:

Function Value: [support-ticket-number][true][true]

Result: Filters recent support emails and extracts ticket number.

Best Practices

✅ Do's

Set max results to 1 - Optimize for single email retrieval
Use specific search queries - Ensure you get the right email
Enable retry for expected emails - Use retry mechanism for verification emails
Mark as read after processing - Prevent duplicate processing
Use regex for data extraction - Extract specific patterns like codes or URLs

❌ Don'ts

Don't fetch multiple emails - Use Fetch Mail (Gmail) for bulk operations
Don't set excessive retries - Balance between reliability and performance
Don't ignore timeout settings - Set appropriate timeout for retry scenarios
Don't process without validation - Verify email content before processing

Troubleshooting

No Email Found

Solution: Verify your search query is correct and the email exists.

Wrong Email Retrieved

Solution: Make your search query more specific with additional filters.

Timeout Errors

Solution: Increase timeout duration or reduce max retry attempts.

Regex Not Matching

Solution: Test your regex pattern and ensure it matches the email content format.

Fetch Single Mail (Gmail) ​

Overview ​

Configuration Options ​

Option Details ​

Google Service Account ​

Enable Max Results ​

Max Results Count ​

Include Spam/Trash ​

Enable Retry on Failure ​

Max Retries (Failure) ​

Retry Until Mail Received ​

Max Retries (Until Received) ​

Timeout ​

Enable Regex Filter ​

Regular Expression ​

Regex Replace ​

Remove UNREAD Label ​

Search Query ​

Differences from Fetch Mail (Gmail) ​

Use Cases ​

Practical Examples ​

Example 1: Get Latest OTP Email ​

Example 2: Wait for Verification Email ​

Example 3: Get Password Reset Link ​

Custom Filter ​

Implementation Steps ​

JavaScript Event Listener ​

Event Variable Structure ​

Email Properties ​

Usage Examples ​

Example 1: Extract and Validate OTP ​

Example 2: Filter by Sender and Subject ​

Example 3: Verify Email Content ​

Example 4: Multi-Condition Filtering ​

Best Practices ​

✅ Do's ​

❌ Don'ts ​

Troubleshooting ​

No Email Found ​

Wrong Email Retrieved ​

Timeout Errors ​

Regex Not Matching ​

Related Documentation ​

Fetch Single Mail (Gmail)

Overview

Configuration Options

Option Details

Google Service Account

Enable Max Results

Max Results Count

Include Spam/Trash

Enable Retry on Failure

Max Retries (Failure)

Retry Until Mail Received

Max Retries (Until Received)

Timeout

Enable Regex Filter

Regular Expression

Regex Replace

Remove UNREAD Label

Search Query

Differences from Fetch Mail (Gmail)

Use Cases

Practical Examples

Example 1: Get Latest OTP Email

Example 2: Wait for Verification Email

Example 3: Get Password Reset Link

Custom Filter

Implementation Steps

JavaScript Event Listener

Event Variable Structure

Email Properties

Usage Examples

Example 1: Extract and Validate OTP

Example 2: Filter by Sender and Subject

Example 3: Verify Email Content

Example 4: Multi-Condition Filtering

Best Practices

✅ Do's

❌ Don'ts

Troubleshooting

No Email Found

Wrong Email Retrieved

Timeout Errors

Regex Not Matching

Related Documentation