Skip to main content
POST
/
api
/
threads
Create Thread
curl --request POST \
  --url https://app.puffle.ai/api/threads \
  --header 'Authorization: Bearer <token>'
CLI: 
puffle thread create

​
Overview

Creates a draft one-off email thread in Unibox. This does not send the email by itself. To send the message, call Send message with the returned thread.id. Use this endpoint when you want to start a new direct email conversation outside a campaign. Campaign sends still belong to the Campaigns API and sequence engine.

​
Request Body

FieldTypeRequiredDescription
participant_emailstringRequired to sendRecipient email address. The API stores it lowercase.
account_idstringOptionalEmail sender account ID. If provided, it must belong to the workspace, be an email account, have a configured sending inbox, and be ready to send. You may also provide this later when sending.
participant_namestringOptionalDisplay name for the recipient.
draft_subjectstringOptionalDraft subject stored on the thread.
draft_body_textstringOptionalPlain-text draft body stored on the thread.
draft_body_htmlstringOptionalHTML draft body stored on the thread.
draft_ccstringOptionalComma-separated CC recipients for the draft.
draft_bccstringOptionalComma-separated BCC recipients for the draft.
draft_attachmentsarrayOptionalDraft email attachments. Use uploaded attachment metadata from the thread attachment endpoint.
At least one draft field must be present. A sendable one-off email needs participant_email plus an email sender account, either here as account_id or later in the send request.

​
Example

curl -X POST "https://app.puffle.ai/api/threads" \
  -H "Authorization: Bearer $PUFFLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "8a2f0c7a-9d1e-4d8f-9d7d-6a8b8e8f4a11",
    "participant_email": "founder@example.com",
    "participant_name": "Alex Founder",
    "draft_subject": "Quick question",
    "draft_body_text": "Hi Alex, I had a quick question about your outbound workflow."
  }'
The response includes the created draft as thread. 
{
  "thread": {
    "id": "3d986dd1-9d70-45b7-8e36-5d5b8b1c9337",
    "channel": "email",
    "status": "draft",
    "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 about your outbound workflow."
  },
  "existing_threads": {
    "exists": false,
    "total": 0,
    "threads": []
  }
}

​
Duplicate Recipient Handling

If the same sender already has a non-archived, non-warmup email thread with the recipient, the API returns 409 with existing_thread and existing_threads. Open that thread and call Send message instead of creating a duplicate.

​
AI agent notes

Use this endpoint before POST /api/threads/{id}/messages when starting a one-off email. Do not use it to send campaign sequence messages.

Authorizations

​
Authorization
string
header
required

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

Response

Thread created.