Fetch Mail (Gmail)

Retrieve and filter multiple emails from your Gmail account using search queries, labels, regex extractors, and automated retry mechanisms.

---

Overview

The Fetch Mail (Gmail) field type connects to the Google Gmail API using your authorized Google account to harvest email data into automation workflows. It allows extracting email bodies, subject lines, senders, recipients, and tokens (like OTPs or verification URLs) with full regex support.

---

Configuration Options

Option	Type	Description	Required
Google Service Account	Dropdown	Logged-in Google account with Gmail permissions.	Yes
Mail Parts	Input Tags	Specific email parts to extract (body, subject, from, snippet, to).	Yes
Enable Max Results	Toggle Switch	Limit the number of matching emails returned.	No
Max Results Count	Number Input	Maximum count of messages to fetch (e.g., 5, 10, 50).	When limit enabled
Use Gmail Labels	Toggle Switch	Filter search specifically within chosen Gmail labels.	No
Gmail Label IDs	Multi-Select	Select labels to scope the search (e.g., INBOX, SPAM, UNREAD).	When labels enabled
Include Spam/Trash	Toggle Switch	Includes messages located in Spam or Trash folders.	No
Enable Retry on Failure	Toggle Switch	Re-attempts the API query if network errors occur.	No
Max Retries (Failure)	Number Input	Maximum retry attempts for failed requests.	When retry enabled
Retry Until Mail Received	Toggle Switch	Polls repeatedly until an email matching search criteria arrives.	No
Max Retries (Until Received)	Number Input	Number of polling cycles to wait for new emails.	When polling enabled
Timeout	Number Input	Wait timeout in seconds between polling cycles.	No
Enable Regex Filter	Toggle Switch	Applies regular expressions to extract specific patterns from email content.	No
Regular Expression	Text Input	Regex pattern to capture tokens (e.g. \b\d{6}\b for 6-digit OTPs).	When regex enabled
Regex Replace	Text Input	Optional replacement string for matched regex patterns.	No
Remove UNREAD Label	Toggle Switch	Automatically marks retrieved emails as read to prevent reprocessing.	No
Search Query	Default Value	Standard Gmail search operators to filter messages.	No

---

Detailed Settings Breakdown

Google Service Account

Select the authorized Google identity registered under Google Service. Ensure the account holds valid OAuth2 permissions to read Gmail messages.

Mail Parts

Specify which components of the message to parse:

• body: Plain text or HTML email body.
• subject: Email subject header.
• from: Sender name and address ([email protected]).
• to: Recipient address(es).
• snippet: Short preview text snippet generated by Gmail.

Polling for Incoming Emails

When an automated form triggers an email verification code:

1. Enable Retry Until Mail Received.
2. Set Max Retries (e.g., 10).
3. Set Timeout (e.g., 10 seconds).
4. The extension will poll Gmail every 10 seconds (up to 10 times) until the message arrives.

Regex Extraction

Extract specific text fragments from the email body:

• 6-Digit Verification Code: \b\d{6}\b
• Confirmation Link: https://example\.com/verify\?token=[a-zA-Z0-9_-]+
• Invoice Number: INV-\d{5,8}

Mark as Read (Remove UNREAD Label)

Enable Remove UNREAD Label to strip the UNREAD badge upon successful retrieval. This ensures subsequent loop iterations or forms do not read the same verification message twice.

---

Practical Examples

Example 1: Fetching Unread Verification Code

Google Service Account: [email protected]
Mail Parts: body
Retry Until Mail Received: ON
Max Retries (Until Received): 8
Timeout: 5 seconds
Enable Regex Filter: ON
Regular Expression: \b\d{6}\b
Remove UNREAD Label: ON
Search Query: from:[email protected] is:unread

Example 2: Extracting Latest Billing Report

Google Service Account: [email protected]
Mail Parts: subject, snippet
Enable Max Results: ON
Max Results Count: 1
Search Query: subject:"Monthly Invoice" after:2025/01/01

---

Best Practices

Do's

• Use Precise Search Queries: Scope searches with from:, subject:, and newer_than:1d to minimize API latency.
• Mark Processed Emails as Read: Prevent duplicate data processing by enabling Remove UNREAD Label.
• Set Realistic Polling Timeouts: Give external email delivery servers at least 30–60 seconds to deliver OTP messages.

Don'ts

• Do Not Fetch Unbounded Queries: Avoid broad queries without is:unread or date boundaries.
• Do Not Set Infinite Retries: Limit polling to a reasonable count (e.g., 6–10 attempts).

---

Troubleshooting

Issue	Likely Cause	Solution
No emails found	Search query too restrictive or email delayed	Verify search parameters manually in Gmail web interface. Increase retry timeout.
Permission denied (403)	Missing Gmail API scope	Re-authenticate Google account under Google Service.
Regex returns empty	Pattern does not match email body formatting	Test regex against the actual raw email body text.

---

Related Documentation

• Gmail API Search Queries Guide
• Fetch Single Mail (Gmail)
• Send Mail (Gmail)
• Google Service Account Setup