---
title: "Attach a Gmail thread to the task [write]"
method: POST
path: "/tasks/{id}/email-threads"
tags: ["tasks"]
---

# Attach a Gmail thread to the task \[write\]

`POST /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

Reads one Gmail thread and keeps it in the task's files as plain text at `email/<subject>-<thread id>.md`: subject, participants, and every message with sender, recipients, time and text; attachments are listed by name and never copied. Every session of the task reads it at its next turn, and the task story shows it as `file.changed` by the caller with `detail.email`. Attaching the same thread again writes a new version only when it changed (200 instead of 201). Nothing is sent from Gmail. Same access rules as the search; 400 `invalid_thread` for something that is not a thread id or a Gmail address ending in one; 404 `thread_not_found`.

## Path parameters

- `id` string, required

## Request body

- object
  - `thread` string, required: A Gmail thread id, or a mail.google.com address ending in one
  - `connection_id` string

## Response `200`

Already attached and unchanged; same body

## Other responses

- `201`: Attached
- `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/post.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)