conecto. Get started
Google Workspace

Search Gmail

google_mail_search · Reads only · Markdown

The newest messages in a mailbox, or those matching a Gmail search.

Free*

*Free up to 1,000,000 reads a month for the whole account, then $0.50 per 10,000 reads.

An example

Which Gmail messages in support@ are still unread?

Your agent callsgoogle_mail_searchFree*

The example business is Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon. The reply is the one the tool really gives.

With these arguments
{
  "mailbox": "support@halversoncycle.example",
  "unread_only": true
}
What comes back
{
  "mailbox": "support@halversoncycle.example",
  "messages": [
    {
      "id": "192e1f0a7c3b9d41",
      "subject": "Where is my Tabor?",
      "from": "rachel.kim@example.com",
      "from_name": "Rachel Kim",
      "to": [
        "support@halversoncycle.example"
      ],
      "received_at": "Wed, 14 Oct 2026 07:41:09 +0000",
      "preview": "Hi, I ordered the Tabor three weeks ago. When does it ship?",
      "read": false,
      "thread_id": "192e1f0a7c3b9d41"
    }
  ]
}

Use it when

The agent starts its round of the mailbox, or looks for a customer's earlier email.

What it does

The newest messages in a mailbox (the inbox by default), or those matching a Gmail search like "from:rachel subject:tabor": sender, subject, a preview and whether they are read. Free.

What comes back

mailbox; messages: each with id, subject, from, to, received_at, preview, read and thread_id. Every reply also carries cost_usd and balance_usd.

Inputs

NameTypeWhat it is
mailboxstringOne of the mailboxes the agent may act as; optional when only one is connected. Up to 254 characters.
querystringUp to 300 characters.
folderstringOne of: inbox,sent,drafts,spam,trash,all. Default: inbox.
unread_onlybooleanDefault: false.
limitinteger1 to 25. Default: 10.

The call

Over MCP, call google_mail_search on https://api.conecto.chat/mcp/googleworkspace. Over REST:

Terminal
curl -X POST https://api.conecto.chat/v1/tools/google_mail_search \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mailbox":"support@halversoncycle.example","unread_only":true}'

When it refuses

A refused call costs nothing and says what to do next.

CodeWhenWhat to do
not_connected409Google Workspace isn't connected yet.Connect it with google_connect.
not_allowed403The mailbox is not one the agent may act as.Use a connected mailbox; the owner adds one by connecting again.
vendor_rejected502Google refused: delegation is missing a scope, or Google said no.Ask the Workspace admin to grant what the message names.

More Google Workspace tools

All 11 tools

Give this to your agent.

Set up Conecto from https://conecto.chat/SKILL.md