Gmail - Simple Search

Search Gmail with basic filters. Works with both OAuth and App Password authentication methods.

Overview

The Gmail Simple Search tool provides straightforward email searching capabilities that work with both authentication methods. It's perfect for most search needs without the complexity of advanced features.

Key Features:

• Search by text query
• Filter by sender and subject
• Date range filtering
• Read/unread status filtering
• Up to 100 results per search
• Works with both OAuth and App Password accounts

When to Use Simple Search:

• Basic email searches are sufficient
• You don't need labels or attachment filtering
• You're using App Password authentication
• You don't require pagination (100 results is enough)

When to Use Advanced Search Instead:

• You need to filter by Gmail labels
• You want to search for emails with attachments
• You need more than 100 results (requires pagination)
• You want to paginate through large result sets

Prerequisites

Before using this tool, connect a Gmail account to Reeva using either method:

1. Gmail (OAuth) - Full features

   • OAuth Setup Guide

2. Gmail (App Password) - Simple setup

   • App Password Setup Guide

Both methods work identically with Simple Search.

Using the Tool

1. Create a Simple Search Tool Instance

1. Navigate to My Tools in Reeva
2. Click Create New Tool
3. Select Gmail - Simple Search from the base tools
4. Give your tool a name (e.g., "Search My Inbox")
5. Select your connected Google Account
6. Click Create

2. Basic Text Search

Search for keywords in email subjects and bodies:

{
  "query": "meeting notes"
}

Returns emails containing "meeting notes" in subject or body.

3. Filter by Sender

Find all emails from a specific person:

{
  "sender": "john@example.com",
  "max_results": 20
}

4. Filter by Subject

Search for specific subject keywords:

{
  "subject": "invoice",
  "max_results": 50
}

5. Date Range Filtering

Find emails within a specific time period:

{
  "query": "project update",
  "after_date": "2024/01/01",
  "before_date": "2024/12/31"
}

Supported Date Formats:

• YYYY/MM/DD (2024/12/06)
• YYYY-MM-DD (2024-12-06)
• MM/DD/YYYY (12/06/2024)
• DD/MM/YYYY (06/12/2024)
• YYYYMMDD (20241206)

The tool automatically converts your date format.

6. Unread/Read Filtering

Find unread emails:

{
  "is_unread": true,
  "max_results": 50
}

Or find read emails:

{
  "is_unread": false,
  "sender": "boss@company.com"
}

7. Combining Filters

Combine multiple filters for precise searches:

{
  "query": "invoice",
  "sender": "billing@company.com",
  "after_date": "2024/11/01",
  "is_unread": true,
  "max_results": 25
}

Tool Parameters

Parameter	Type	Required	Description
query	string	No	Search text (searches subject and body)
max_results	integer	No	Max results (1-100, default 10)
sender	string	No	Filter by sender email address
subject	string	No	Filter by subject keywords
after_date	string	No	Emails after this date (flexible formats)
before_date	string	No	Emails before this date (flexible formats)
is_unread	boolean	No	Filter by read status

Note: max_results is capped at 100. For larger searches, use Advanced Search with pagination.

Response Format

{
  "results": [
    {
      "message_id": "18d5f2a3b4c5d6e7",
      "thread_id": "18d5f2a3b4c5d6e7",
      "subject": "Project Update - Q4 2024",
      "from": "John Doe <john@example.com>",
      "to": "me@gmail.com",
      "date": "Mon, 6 Dec 2024 10:30:00 -0800",
      "snippet": "Here's the latest update on the Q4 project...",
      "labels": ["INBOX", "UNREAD"],
      "is_unread": true,
      "has_attachment": false
    }
  ],
  "result_count": 1,
  "query": "project update"
}

Response Fields

• results: Array of email objects
  • message_id: Unique message identifier
  • thread_id: Conversation thread ID (may be null for IMAP)
  • subject: Email subject line
  • from: Sender email and name
  • to: Recipient email(s)
  • date: Email date and time
  • snippet: First ~200 characters of email body
  • labels: Gmail labels (empty array for IMAP)
  • is_unread: Whether email is unread
  • has_attachment: Whether email has attachments
• result_count: Number of results returned
• query: The actual search query executed
• note: Additional info (e.g., for IMAP limitations)

Important: Message ID Compatibility

⚠️ The message_id format depends on your authentication method:

• OAuth: Returns hexadecimal message IDs (e.g., "18d5f2a3b4c5d6e7")

  • Can ONLY be used with OAuth authentication in other tools (like Read Email)

• App Password: Returns Gmail's X-GM-MSGID - numeric strings (e.g., "1847392840123456789")

  • Can ONLY be used with App Password authentication in other tools
  • These are Gmail's globally unique message identifiers (18-19 digits)
  • Stable across all folders and never reused

You must use the same authentication method when passing message IDs between tools. For example:

• ✅ Search with OAuth → Read with OAuth
• ✅ Search with App Password → Read with App Password
• ❌ Search with OAuth → Read with App Password (will fail)
• ❌ Search with App Password → Read with OAuth (will fail)

See Read Email documentation for more details.

OAuth vs App Password

Simple Search works identically with both authentication methods, with one minor difference:

Feature	OAuth	App Password
Text search	✅	✅
Sender filter	✅	✅
Subject filter	✅	✅
Date filtering	✅	✅
Read/unread filter	✅	✅
Max results	100	100
Thread IDs	✅	❌ (returns null)
Label info	✅ Returns labels	✅ Returns empty array
Speed	Fast	Slightly slower (IMAP)

Recommendation: Use OAuth for better performance and full metadata, but App Password works great for basic searches.

Error Handling

Date Format Errors

If your date format isn't recognized:

{
  "error": "Unable to parse date '32/13/2024'. Please use one of these formats: YYYY/MM/DD (2024/12/06), YYYY-MM-DD (2024-12-06)..."
}

Solution: Use a standard date format listed above.

Credential Errors

If credentials are missing or invalid:

{
  "error": "Gmail credentials required. Please connect a Google account."
}

Solution: Ensure you've selected a valid Gmail account when creating the tool.

IMAP Note (App Password)

When using App Password, you may see a note in the response:

{
  "note": "IMAP search has limited capabilities. For advanced features like labels and pagination, use OAuth authentication."
}

This is informational only - your search still works.

Use Cases

1. Find Unread Emails from Manager

{
  "sender": "manager@company.com",
  "is_unread": true,
  "max_results": 20
}

2. Search Recent Invoices

{
  "query": "invoice",
  "after_date": "2024/11/01",
  "max_results": 50
}

3. Find Old Newsletters

{
  "subject": "newsletter",
  "before_date": "2024/01/01",
  "max_results": 100
}

4. Search for Specific Project Emails

{
  "query": "alpha project",
  "sender": "team@company.com",
  "after_date": "2024/10/01"
}

Limitations

1. 100 Result Maximum: If you need more, use Advanced Search with pagination
2. No Label Filtering: Can't filter by specific Gmail labels (INBOX, IMPORTANT, etc.)
3. No Attachment Filtering: Can't search specifically for emails with attachments
4. No Pagination: Can't request additional pages of results
5. IMAP Slower: App Password searches are slightly slower due to IMAP protocol

For these advanced features, use Gmail - Advanced Search.

Tips

1. Start Broad: Begin with simple queries, then add filters
2. Use Date Ranges: Narrow results by specifying date ranges
3. Check max_results: Default is 10; increase if needed (up to 100)
4. Combine Filters: Multiple filters work together (AND logic)
5. Date Flexibility: Use any date format you're comfortable with

Troubleshooting

"No results found"

• Check spelling: Verify search terms are correct
• Broaden search: Try removing some filters
• Check dates: Ensure date range is correct
• Try different query: Use alternative keywords

"Invalid date format"

• Use standard formats: Stick to YYYY/MM/DD or similar
• Check values: Ensure day/month are valid (no 32nd or 13th month)
• Read error message: It shows accepted formats

OAuth Token Expired

For OAuth accounts:

1. Try disconnecting and reconnecting your Gmail account
2. Verify Google Cloud credentials are still valid
3. Check OAuth consent hasn't been revoked

IMAP Connection Failed

For App Password accounts:

1. Verify App Password is correct (16 characters, no spaces)
2. Ensure 2FA is enabled on Gmail
3. Check IMAP is enabled in Gmail settings

Related Tools

• Gmail - Advanced Search - Advanced features with labels and pagination (OAuth only)
• Gmail - Send Email - Send emails via Gmail
• Gmail - Read Email - Read full email content by message ID
• Gmail - Summarize Thread - AI summary of email threads
• Gmail - Create Draft - Create draft emails
• Gmail - Update Draft - Modify existing drafts
• Gmail - List Drafts - Browse and filter drafts
• Gmail - Send Draft - Send existing drafts
• Gmail - Delete Draft - Permanently delete drafts

Support

Need help? Reach out to our support team or join our Discord community.