Gmail Fetch Emails

​

Authentication & enablement

• If the workspace has several Gmail connections, the tool uses the one bound to the configured tool, otherwise the workspace’s most recently connected active one. Every result carries account, the address actually read — bind the tool to a connection when it matters which mailbox is searched.
• Composio’s Gmail tools (composio_gmail_*) use a separate connection made through Composio and cannot see this one. Don’t enable composio_gmail_fetch_emails and gmail_fetch_emails on the same agent.

​

Inputs

• query: Gmail search syntax, as in the Gmail search box — from:billing@acme.com, subject:"Salaries 05.2026", after:2026/09/01 before:2026/10/01, has:attachment, label:Invoices, in:anywhere. Empty lists the most recent emails in all mail.
• max_results: emails per page, default 10, maximum 50.
• page_token: the next_page_token from a previous call with the same query.
• ids_only: return only message_ids without each email’s details — the cheapest way to check whether matching emails exist.

​

Output

{
  "tool_name": "gmail_fetch_emails",
  "account": "ap@customer.com",
  "query": "from:billing@acme.com has:attachment",
  "count": 1,
  "emails": [
    {
      "message_id": "19a2f0c4d5e6f7a8",
      "thread_id": "19a2f0c4d5e6f7a8",
      "from": "Billing Team <billing@acme.com>",
      "to": ["ap@customer.com"],
      "subject": "Invoice 42",
      "date": "2026-09-21T14:13:20Z",
      "snippet": "Please find attached invoice 42…",
      "labels": ["INBOX", "UNREAD"],
      "attachments": [{ "attachment_id": "ANGjdJ…", "filename": "Invoice 42.pdf", "mime_type": "application/pdf", "size": 48213 }]
    }
  ],
  "next_page_token": "0987654321"
}

• Email bodies are never returned here. Open an email with gmail_get_email to read it and save its attachments.
• attachments lists files only; inline images such as signature logos are left out.
• skipped counts matches deleted between the search and the fetch.

​

Limits & errors

• Each call is one Gmail search plus one lightweight fetch per match, at most 5 at a time. All tasks in a workspace share one mailbox’s Google quota; when Gmail rate-limits it, the tool backs off and retries, then returns “Gmail is rate-limiting this mailbox” if it still can’t get through. Smaller pages help.
• “No Gmail account is connected” → connect Gmail on the Connectors page.
• “has not granted read access” → the connection was made without Gmail access; reconnect and allow it.
• Billed per call, like the other Gmail tools.

​

Agent Instruction Guidance