# email_thread_search

Search Email Threads

## 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:finance@versacommerce.de 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

```json
{
  "$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

```json
{
  "$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"
}
```