> ## Documentation Index > Fetch the complete documentation index at: https://docs.puffle.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update Thread > Update thread lifecycle, unread count, sender, and one-off email draft fields. **CLI:** ```bash theme={null} puffle thread update --id --status --unread-count --account-id --participant-email --participant-name --draft-subject --draft-body-text --draft-body-html --draft-cc --draft-bcc ``` ## Overview Updates a Unibox thread. Use it to archive or reactivate a thread, update unread count, choose a sender for an email draft, or edit one-off draft fields before sending. ## Path Parameters | Parameter | Type | Description | | --------- | ------ | ----------- | | `id` | string | Thread ID. | ## Request Body | Field | Type | Description | | ------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `status` | string | Set to `active` or `archived`. Other values are rejected with `400`. | | `unread_count` | number | Sets the stored unread count. | | `account_id` | string or null | Email sender account ID, or `null` to clear it. Non-null values must refer to a ready email sender in the workspace. | | `participant_email` | string | Recipient email for a draft one-off email. Stored lowercase. | | `participant_name` | string | Recipient display name for a draft. | | `draft_subject` | string or null | Draft email subject. | | `draft_body_text` | string or null | Draft plain-text body. | | `draft_body_html` | string or null | Draft HTML body. | | `draft_cc` | string or null | Draft CC recipients. | | `draft_bcc` | string or null | Draft BCC recipients. | | `draft_attachments` | array or null | Dashboard-only attachment metadata. Bearer API-key callers must omit this field; ask the human to add or clear attachments in Unibox. | At least one valid field is required. ## Example ```bash theme={null} curl -X PATCH "https://app.puffle.ai/api/threads/3d986dd1-9d70-45b7-8e36-5d5b8b1c9337" \ -H "Authorization: Bearer $PUFFLE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "account_id": "8a2f0c7a-9d1e-4d8f-9d7d-6a8b8e8f4a11", "participant_email": "founder@example.com", "draft_subject": "Quick question", "draft_body_text": "Hi Alex, I had a quick question." }' ``` ```json theme={null} { "thread": { "id": "3d986dd1-9d70-45b7-8e36-5d5b8b1c9337", "status": "draft", "account_id": "8a2f0c7a-9d1e-4d8f-9d7d-6a8b8e8f4a11", "participant_email": "founder@example.com", "draft_subject": "Quick question" } } ``` ## Duplicate Recipient Handling When changing `account_id` on an email thread, the API checks whether that sender already has a non-archived, non-warmup thread with the same `participant_email`. If one exists, the response is `409` with `existing_thread`. ## AI agent notes Use this endpoint for draft edits and thread state changes. Do not use it to send a message; call [Send message](/api-reference/unibox/send-thread-message) after the draft is ready. The public API cannot upload a new thread attachment. Do not invent storage metadata or call `/api/threads/{id}/attachments`; that multipart route is UI-only. If a new file must be attached, ask the human to add it in Unibox. Before sending, re-fetch the thread and confirm the recipient, sender, subject, body, and any existing attachment names with the human. Surface `400`, `403`, `404`, and `409` responses without retrying the same update. ## OpenAPI ````yaml patch /api/threads/{id} openapi: 3.0.3 info: title: Puffle API version: 1.0.0 description: >- HTTP API for the Puffle GTM platform - Feed and Lead Finder search preparation, campaign-backed Outbound execution, Puffle Agent runs, sender management, and Unibox reply workflows. Designed for operation by both humans and autonomous AI agents. Agents should start at the [Agent Playbook](/guides/agent-playbook) which prescribes a workspace-context check (`GET /api/context`) and core user journeys with exact call ordering. contact: name: Puffle Support url: https://puffle.ai servers: - url: https://app.puffle.ai description: Production security: - bearerAuth: [] tags: - name: Campaigns description: >- Campaign-backed Outbound execution. These endpoints manage draft, launching, active, paused, and completed Outbound runs with sequence nodes, contacts, and sender accounts. - name: Accounts description: Signed-in user account, settings, and workspace context endpoints. - name: Billing description: Billing customer portal and account billing endpoints. - name: Senders description: >- Connected sender accounts, email inboxes, sending domains, DNS verification, warmup, and sender capacity. - name: Socials description: >- Read connected LinkedIn and X accounts, review current and archived posts, and reconcile publication status. Creating, editing, scheduling, publishing, OAuth connection, analytics, and mentions remain dashboard-managed workflows and are not part of the public Bearer-token API. paths: /api/threads/{id}: patch: tags: - Unibox summary: Update Thread description: Update Thread operationId: updateThread parameters: - name: id in: path required: true schema: type: string description: Thread (`conversations.id`) UUID. requestBody: required: true content: application/json: schema: type: object properties: status: type: string enum: - active - archived unread_count: type: integer minimum: 0 maximum: 9007199254740991 account_id: description: >- Email sender account ID, or null when no sender is selected yet. type: string nullable: true participant_email: type: string description: Recipient email address. participant_name: type: string description: Recipient display name. draft_subject: type: string description: Draft email subject. nullable: true draft_body_text: type: string description: Draft plain-text body. nullable: true draft_body_html: description: Draft HTML body. type: string nullable: true draft_cc: description: Draft CC recipients. type: string nullable: true draft_bcc: description: Draft BCC recipients. type: string nullable: true draft_attachments: type: array items: type: object properties: name: type: string minLength: 1 description: Attachment file name. url: description: Attachment URL. type: string minLength: 1 bucket: type: string minLength: 1 description: Storage bucket containing the attachment. path: type: string minLength: 1 description: Attachment path within the storage bucket. mime_type: type: string minLength: 1 size: type: number minimum: 0 content_id: type: string minLength: 1 content_disposition: type: string enum: - attachment - inline required: - name - bucket - path additionalProperties: false description: >- Dashboard-only attachment metadata. Bearer API-key callers must omit this field and ask a human to manage attachments in Unibox. nullable: true additionalProperties: false responses: '200': description: Successful response. '400': description: Bad request. '401': description: Unauthorized. '403': description: Forbidden. '404': description: Not found. '500': description: Internal server error. components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: pk_live_... ````