Zum Inhalt
Für Agenten

MCP Reference

email_thread_search

Search Email Threads

Markdown Tools als JSON

Beschreibung

Lists email threads from the caller's connected Gmail accounts in this oona account.

Filters via Gmail's native query syntax — the same operators that work in Gmail web search:

  • Sender/recipient: from:, to:, cc:, bcc:, deliveredto:, list:
  • Time: after:YYYY/MM/DD, before:YYYY/MM/DD, newer:, older:, older_than:1y, newer_than:7d
  • Content: subject:, has:attachment, filename:, "exact phrase", +exact, rfc822msgid:, AROUND
  • Status/location: is:unread, is:starred, is:important, in:inbox|sent|drafts|trash|spam|anywhere, category:primary|social|promotions|updates|forums|reservations|purchases
  • Labels: label:Newsletter (use the label name as shown to the user)
  • Size: larger:10M, smaller:500K
  • Logic: AND, OR, -exclude, ( ) grouping

Examples: - "is:unread newer_than:7d" - "from:[email protected] subject:invoice" - "has:attachment in:inbox -from:no-reply"

Returns thread headers + a short snippet. Use email_thread_get with a returned ethr_… ID to read the messages.

By default searches across all connected accounts in the account; pass account_ids to narrow. Pagination via page_size (max 50) and page_token.

Zugriff

Zugriffsprofil: gated. Module: email. Die Freigabe im Profil ersetzt keine Account-, Workspace- oder Rollenberechtigung.

Parameter

Name Typ Pflicht Beschreibung
account_id string Ja Account prefix ID (acct_…).
account_ids array Nein Restrict to specific Gmail accounts (mail_… from email_account_list). Default: all live accounts.
query string Nein Gmail query syntax. Empty = list everything except spam/trash.
include_trash boolean Nein Include threads from TRASH. Default false.
page_size integer Nein Default 20, max 50.
page_token string Nein Opaque cursor from a previous response's next_page_token.

Eingabeschema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "account_id": {
      "type": "string",
      "description": "Account prefix ID (acct_…)."
    },
    "account_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Restrict to specific Gmail accounts (mail_… from email_account_list). Default: all live accounts."
    },
    "query": {
      "type": "string",
      "description": "Gmail query syntax. Empty = list everything except spam/trash."
    },
    "include_trash": {
      "type": "boolean",
      "description": "Include threads from TRASH. Default false."
    },
    "page_size": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Default 20, max 50."
    },
    "page_token": {
      "type": "string",
      "description": "Opaque cursor from a previous response's next_page_token."
    }
  },
  "required": [
    "account_id"
  ],
  "type": "object"
}

Ausgabeschema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "threads": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "subject": {
            "type": [
              "string",
              "null"
            ]
          },
          "snippet": {
            "type": [
              "string",
              "null"
            ]
          },
          "participants": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "message_count": {
            "type": "integer"
          },
          "last_message_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "is_unread": {
            "type": "boolean"
          },
          "is_starred": {
            "type": "boolean"
          },
          "has_attachments": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "account_id",
          "subject",
          "message_count",
          "is_unread",
          "is_starred"
        ]
      }
    },
    "next_page_token": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "threads"
  ],
  "type": "object"
}
Seiten