Skip to main content
The Gmail Reader agent allows you to read emails from your Gmail account based on specific criteria. It’s perfect for monitoring inbox messages, filtering emails from specific senders, and extracting email data for processing in workflows.

​
Use Cases

  • Monitor emails from specific senders (customers, partners, systems)
  • Read unread messages for automated processing
  • Extract email content for analysis or summarization
  • Trigger workflows based on incoming emails
  • Create email-based automation and response systems

​
Configuration

​
Gmail Authorization

The Gmail Reader uses OAuth 2.0 for secure authentication. Click the “Connect Gmail” button to authorize Agility to access your Gmail account.
Your Gmail credentials are never stored. Agility uses secure OAuth tokens that can be revoked at any time from your Google Account settings.

​
Email Filtering

​
fromEmail
string
required
The email address of the sender to search for. Only emails from this address will be retrieved.Example: [email protected], [email protected]
​
maxResults
number
default:"5"
Maximum number of emails to retrieve. Range: 1-50Default: 5 emails
​
onlyUnread
boolean
default:"true"
When enabled, only retrieves unread emails. When disabled, retrieves all emails matching other criteria.Default: true

​
Workflow Trigger

​
setAsTrigger
boolean
default:"false"
When enabled, this agent becomes the workflow trigger. The workflow will automatically execute when new emails arrive from the specified sender.Note: Only one agent per workflow can be set as a trigger.

​
Output Structure

The Gmail Reader provides comprehensive email data that can be used by subsequent agents.
​
messages
array
required
Array of email message objects retrieved from Gmail. Each message contains full email details.
​
emailBody
string
required
Body content of the first email message in plain text format.
​
emailSubject
string
required
Subject line of the first email message.
​
emailFrom
string
required
Email address of the sender of the first message.
​
emailTo
string
required
Email address of the recipient of the first message.
​
emailDate
string
required
Date and time when the first email was sent (ISO 8601 format).
​
email
string
required
Formatted representation of the first email including all headers and body content.

​
Example Output

{
  "messages": [
    {
      "id": "18c5f8a9b2d4e1f0",
      "subject": "New order #12345",
      "from": "[email protected]",
      "to": "[email protected]",
      "date": "2024-03-15T10:30:00Z",
      "body": "Your order has been received...",
      "snippet": "Your order has been received and is being processed."
    }
  ],
  "emailBody": "Your order has been received and is being processed. Order details: ...",
  "emailSubject": "New order #12345",
  "emailFrom": "[email protected]",
  "emailTo": "[email protected]",
  "emailDate": "2024-03-15T10:30:00Z",
  "email": "From: [email protected]\nTo: [email protected]\nSubject: New order #12345\n\nYour order has been received..."
}

​
Usage Examples

​
Customer Support Automation

Workflow: Auto-respond to support emails
  1. Gmail Reader
  2. Text Generator
    • Prompt: “Generate a professional support response for: ”
  3. Gmail Sender
    • To: {{emailFrom}}
    • Subject: Re: {{emailSubject}}
    • Body: {{text}}

​
Order Notification Monitor

Workflow: Extract and log order information
  1. Gmail Reader
  2. Text Generator
    • Prompt: “Extract order number, customer name, and total amount from: ”
  3. Discord Messenger
    • Message: “New order received: “

​
GitHub Digest

Workflow: Daily summary of GitHub notifications
  1. Gmail Reader
  2. Text Generator
    • Prompt: “Summarize these GitHub notifications: ”
  3. Discord Messenger
    • Message: “Daily GitHub Digest:\n”

​
Best Practices

​
Email Filtering

  • Use specific sender addresses rather than domains
  • Start with small maxResults values and increase as needed
  • Use “Only Unread” to avoid processing the same emails repeatedly

​
Performance

  • Avoid setting very high maxResults values (>20) as it increases processing time
  • Use workflow triggers for real-time email processing instead of polling

​
Security

  • Regularly review OAuth permissions in your Google Account
  • Only grant access to workflows that genuinely need email access
  • Revoke access when workflows are no longer needed

​
Error Handling

Common errors and solutions:
  • Gmail authorization required: Click “Connect Gmail” to authorize access
  • No emails found: Verify the sender email address is correct and matching emails exist
  • Rate limit exceeded: Gmail API has usage limits; wait before retrying
  • Invalid sender email: Ensure the email address format is valid

​
Testing

​
Test Agent

Immediately searches for and retrieves emails matching your criteria. Results are displayed in the configuration panel.

​
Test Workflow

Runs the entire workflow to see how email data is processed by subsequent agents.

Build docs developers (and LLMs) love

Get started for freeTalk to us