Skip to main content
PATCH
/
api
/
threads
/
{id}
Update Thread
curl --request PATCH \
  --url https://app.puffle.ai/api/threads/{id} \
  --header 'Authorization: Bearer <token>'
CLI: 
puffle thread update --id <id>

​
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

ParameterTypeDescription
idstringThread ID.

​
Request Body

FieldTypeDescription
statusstringSet to active or archived. Other values are ignored.
unread_countnumberSets the stored unread count.
account_idstring or nullEmail sender account ID, or null to clear it. Non-null values must refer to a ready email sender in the workspace.
participant_emailstringRecipient email for a draft one-off email. Stored lowercase.
participant_namestringRecipient display name for a draft.
draft_subjectstring or nullDraft email subject.
draft_body_textstring or nullDraft plain-text body.
draft_body_htmlstring or nullDraft HTML body.
draft_ccstring or nullDraft CC recipients.
draft_bccstring or nullDraft BCC recipients.
draft_attachmentsarray or nullDraft attachment metadata from Upload thread attachment.
At least one valid field is required.

​
Example

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."
  }'

{
  "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 after the draft is ready.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
id
string
required

Thread (conversations.id) UUID.

Response

Successful response.