Skip to main content

Gmail - Read Email

Read full email content from Gmail by message ID. Retrieves subject, sender, recipients, body (both plain text and HTML), attachment metadata, and more.

Overview​

The Gmail Read Email tool retrieves complete email content using a message ID. This is essential for AI workflows that need to read and process email content.

Key Features:

  • Read complete email details by message ID
  • Get both plain text and HTML body
  • View attachment metadata (names, sizes, types)
  • Access all headers (from, to, cc, bcc, reply-to, date)
  • Works with both OAuth and App Password

Common Use Cases:

  • AI reads email and drafts response
  • Extract information from specific emails
  • Process email content for workflows
  • Analyze email threads
  • Archive email content

Prerequisites​

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

  1. Gmail (OAuth) - Full features

  2. Gmail (App Password) - Works great too

Both authentication methods work identically with Read Email.

Getting Message IDs​

You need a message ID to read an email. Get message IDs from:

  1. Gmail Search Tools:

  2. Example workflow:

    Step 1: Search for "invoice from:billing@company.com"
    Step 2: Get message_id from search results
    Step 3: Read that email with Read Email tool

⚠️ CRITICAL: Authentication Method Compatibility​

You MUST use the same authentication method for both searching and reading emails.

Message ID Incompatibility​

OAuth (Gmail API) Message IDs:

  • Format: Hexadecimal strings (e.g., "18d5f2a3b4c5d6e7")
  • Only work with OAuth authentication
  • Obtained from OAuth searches

App Password (IMAP) Message IDs:

  • Format: Long numeric strings (e.g., "1847392840123456789")
  • Only work with App Password authentication
  • Obtained from App Password searches
  • Uses Gmail's X-GM-MSGID (globally unique, never reused, stable across folders)

Common Error​

❌ This will NOT work:

1. Search with App Password → get message_id "372569"
2. Read with OAuth → ERROR: Message not found

✅ This WILL work:

Option A: Search with App Password → Read with App Password
Option B: Search with OAuth → Read with OAuth

How to Fix​

If you get a "message not found" error:

  1. Check which authentication method you used for search
  2. Use the SAME authentication method for read
  3. The tool will detect mismatches and provide a helpful error message

Example Error Message:

"Message ID '1847392840123456789' appears to be an IMAP message ID (X-GM-MSGID), not a Gmail API message ID. IMAP message IDs (from App Password searches) cannot be used with OAuth/Gmail API. You must use the same authentication method for both search and read."

Technical Note: IMAP Uses X-GM-MSGID​

App Password authentication now uses Gmail's X-GM-MSGID instead of regular IMAP UIDs. This provides:

  • ✅ Globally unique identifiers (never reused, even after deletion)
  • ✅ Stable across all folders (INBOX, Archive, etc.)
  • ✅ Reliable message identification between search and read operations

Regular IMAP UIDs were folder-specific and could be reused, causing messages to be misidentified. X-GM-MSGID solves this problem.

Using the Tool​

1. Create a Read Email Tool Instance​

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

2. Read an Email (Full Format)​

Read complete email with all details:

{
  "message_id": "18d5f2a3b4c5d6e7"
}

This returns everything: subject, body (plain & HTML), attachments, headers.

3. Read Email Metadata Only​

Get headers without downloading body content:

{
  "message_id": "18d5f2a3b4c5d6e7",
  "format": "metadata"
}

Faster for checking sender, subject, date without processing body.

4. Read Minimal Email Info​

Get just basic info:

{
  "message_id": "18d5f2a3b4c5d6e7",
  "format": "minimal"
}

Fastest option for quick checks.

Tool Parameters​

ParameterTypeRequiredDescription
message_idstringYesGmail message ID from search results
formatstringNoResponse format: "full" (default), "metadata", "minimal"

Format Options​

  • full (default): Complete email with body and attachments
  • metadata: Headers only, no body content (faster)
  • minimal: Just basic info (fastest)

Response Format​

{
  "message_id": "18d5f2a3b4c5d6e7",
  "thread_id": "18d5f2a3b4c5d6e7",
  "label_ids": ["INBOX", "UNREAD"],
  "snippet": "Here is the Q4 sales report as requested...",
  "subject": "Q4 Sales Report",
  "from": "John Doe <john@company.com>",
  "to": "me@gmail.com",
  "cc": "manager@company.com",
  "bcc": "",
  "date": "Mon, 6 Dec 2024 10:30:00 -0800",
  "reply_to": "",
  "body_plain": "Here is the Q4 sales report as requested.\n\nKey highlights:\n- Revenue: $2M\n- Growth: 15%\n\nSee attached PDF for details.",
  "body_html": "<html><body><p>Here is the Q4 sales report as requested.</p><p>Key highlights:</p><ul><li>Revenue: $2M</li><li>Growth: 15%</li></ul><p>See attached PDF for details.</p></body></html>",
  "attachments": [
    {
      "filename": "Q4_Report.pdf",
      "mime_type": "application/pdf",
      "size": 524288,
      "attachment_id": "ANGjdJ8..."
    }
  ],
  "internal_date": "1733520600000",
  "size_estimate": 532512,
  "has_attachments": true
}

Response Fields​

  • message_id: Unique message identifier
  • thread_id: Conversation thread ID (null for IMAP)
  • label_ids: Gmail labels (empty for IMAP)
  • snippet: First ~200 characters preview
  • subject: Email subject line
  • from: Sender email and name
  • to: Primary recipients
  • cc: CC recipients
  • bcc: BCC recipients (rarely visible)
  • date: Email date/time
  • reply_to: Reply-to address if different from sender
  • body_plain: Plain text email body
  • body_html: HTML email body
  • attachments: Array of attachment metadata
    • filename: Attachment name
    • mime_type: File type (e.g., "application/pdf")
    • size: Size in bytes
    • attachment_id: ID for downloading (null for IMAP)
  • internal_date: Unix timestamp (milliseconds)
  • size_estimate: Total email size in bytes
  • has_attachments: Whether email has attachments

OAuth vs App Password​

Both authentication methods work great with Read Email:

FeatureOAuthApp Password
Read email body✅✅
Get attachments metadata✅✅
Thread IDs✅❌ (returns null)
Label IDs✅❌ (returns empty array)
Format options✅ All formats✅ All formats
PerformanceFastSlightly slower (IMAP)

Recommendation: Both work well. Use OAuth for thread IDs and labels.

Use Cases​

1. AI Email Response Assistant​

Workflow:
1. Search for unread emails
2. Read each email with Read Email tool
3. AI analyzes content and drafts response
4. Human reviews and sends

2. Extract Invoice Data​

{
  "message_id": "invoice_email_id"
}

AI extracts:

  • Invoice number from subject or body
  • Amount from body_plain
  • Due date
  • Saves to accounting system

3. Monitor Important Emails​

Workflow:
1. Advanced Search: label_ids=["IMPORTANT"], is_unread=true
2. For each result, Read Email
3. Check for keywords or action items
4. Notify team or trigger workflow

4. Summarize Long Emails​

Workflow:
1. Get message_id from search
2. Read email
3. Send body_plain to AI for summarization
4. Return key points

5. Process Attachments​

Workflow:
1. Read email
2. Check has_attachments = true
3. List attachment filenames and sizes
4. Download needed attachments (separate tool)
5. Process files

Error Handling​

Message Not Found​

{
  "error": "Email with message ID 'abc123' not found."
}

Causes:

  • Invalid message ID
  • Email was deleted
  • Using IMAP ID with OAuth or vice versa

Solution:

  • Verify message ID is correct
  • Check email hasn't been deleted
  • Use search to get current message ID

Invalid Format​

{
  "error": "Invalid format 'wrong'. Must be 'full', 'metadata', or 'minimal'."
}

Solution: Use one of the three valid format options

Credential Errors​

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

Solution: Ensure Gmail account is connected in Reeva

IMAP Errors (App Password)​

{
  "error": "IMAP error: authentication failed"
}

Solution:

  • Verify App Password is correct
  • Ensure IMAP is enabled in Gmail settings
  • Check 2FA is enabled on Gmail account

Tips​

  1. Use Format Wisely:

    • full: When you need body content
    • metadata: When checking sender/subject only
    • minimal: For quick existence checks

  2. Handle Both Body Types:

    • Check body_plain first (easier to parse)
    • Fall back to body_html if plain is empty
    • Use HTML parser if you need formatted content

  3. Check Attachments Before Downloading:

    • Use has_attachments flag
    • Review attachments array for filenames
    • Check sizes before downloading large files

  4. Thread Context:

    • Use thread_id to get full conversation (OAuth only)
    • Read all messages in thread for complete context

  5. Error Recovery:

    • Always check for error field in response
    • Handle "not found" gracefully
    • Retry with exponential backoff for transient errors

Limitations​

  1. No Attachment Download: This tool returns attachment metadata only. Use a separate Download Attachment tool to get file content.

  2. IMAP Limitations (App Password):

    • No thread IDs
    • No Gmail label information
    • Message ID is IMAP UID (different from OAuth message IDs)

  3. Format Support: Gmail API supports more formats (raw, etc.) but tool exposes most common three.

  4. Large Emails: Very large emails (>10MB) may be slow to retrieve.

Troubleshooting​

Empty body_plain and body_html​

Cause: Email has no text content or is images-only

Solution:

  • Check snippet for preview
  • Email might be images/attachments only

Message ID doesn't work​

Cause: Using OAuth message ID with App Password or vice versa

Solution:

  • OAuth message IDs: Long alphanumeric strings
  • IMAP IDs: Usually numeric
  • Use search tool with same account type to get correct IDs

Attachments show but can't access content​

Cause: This tool only returns metadata

Solution: Use Download Attachment tool (future) with attachment_id

Slow performance with App Password​

Cause: IMAP is slower than Gmail API

Solution:

  • Use OAuth for better performance
  • Consider reading multiple emails in parallel
  • Use format="metadata" when body isn't needed

Support​

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