---
title: "Search Gmail for a thread to attach to the task [write]"
method: GET
path: "/tasks/{id}/email-threads"
tags: ["tasks"]
---

# Search Gmail for a thread to attach to the task \[write\]

`GET /tasks/{id}/email-threads`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/tasks/{id}/email-threads`
- Auth: HTTP bearer

Searches the caller's own Gmail connection, or a Gmail connection a teammate shared with the task's workspace, with Gmail's search syntax (`q`, e.g. `from:supplier@example.com invoice`). At most 10 threads. Read-only on Gmail. Write scope because each Gmail read is a billed connector call. Needs a person's own credential (403 `person_required` for a workspace key, an app or a task pass) and the right to send the task's first session messages (404 otherwise, as for an unknown task); 404 `not_connected` when there is no Gmail connection to read through; the workspace's tool-call rules apply (403 `capability_denied`).

## Path parameters

- `id` string, required

## Query parameters

- `q` string
- `connection_id` string

## Response `200`

OK

- object
  - `connection` EmailConnection, required
    - `id` string, required
    - `label` string, required: Your own connection's account, or whose shared connection it is
    - `shared_by` string, nullable, required: The teammate who shared it with the workspace; null for your own
  - `connections` EmailConnection[], required
    - `id` string, required
    - `label` string, required: Your own connection's account, or whose shared connection it is
    - `shared_by` string, nullable, required: The teammate who shared it with the workspace; null for your own
  - `threads` EmailThread[], required
    - `id` string, required: Gmail thread id; pass it as `thread` to attach
    - `subject` string, required
    - `from` string, nullable, required
    - `date` string, nullable, required: When its latest message was sent
    - `snippet` string, required
    - `messages` integer, required

## Other responses

- `default`: Error — { error: { code, message } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/tasks/:id/email-threads/get.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/8280a065ef6a?raw)