Reference

Threads

Conversations. Group outbound + inbound messages and provide the entry point for replying via API.

List threads

get /v1/threads

curl TypeScript

curl -X GET "https://api.clement.so/v1/threads" \
  -H "Authorization: Bearer $CLEMENT_API_KEY"

import { Clement } from "@clement/sdk";

const c = new Clement({ apiKey: process.env.CLEMENT_API_KEY! });
const result = await c.threads.list();

Query parameters

limit integer
starting_after string
ending_before string
inbox_id string
has_reply string

Response200

Property	Type	Description
`object` required	enum (1)	`"list"`
`data` required	array<Thread>
`has_more` required	boolean
`next_cursor` required	string \| null
`prev_cursor` required	string \| null

Example response

{
  "object": "list",
  "data": [
    {
      "id": "thr_01HZ8X3J9K7P2QV6R5N4M3T2L1_18f8a2b3c4d5e6f",
      "object": "thread",
      "inbox_id": "inb_01HZ8X3J9K7P2QV6R5N4M3T2L1",
      "provider_thread_id": "18f8a2b3c4d5e6f",
      "subject": "Quick question about Acme's data stack",
      "message_count": 2,
      "has_reply": true,
      "has_bounce": false,
      "last_message_at": "2026-04-29T16:42:11Z",
      "first_message_at": "2026-04-29T14:30:02Z"
    }
  ],
  "has_more": false,
  "next_cursor": "string",
  "prev_cursor": "string"
}

Errors

400 Invalid request
401 Authentication failed
403 Insufficient scope
404 Not found
409 Conflict
422 Validation failed
429 Rate limited

See Errors for the full envelope and per-code reference.

Retrieve a thread (with messages embedded)

get /v1/threads/{id}

curl TypeScript

curl -X GET "https://api.clement.so/v1/threads/obj_01HZ8X3J9K7P2QV6R5N4M3T2L1" \
  -H "Authorization: Bearer $CLEMENT_API_KEY"

import { Clement } from "@clement/sdk";

const c = new Clement({ apiKey: process.env.CLEMENT_API_KEY! });
const result = await c.threads.retrieve("obj_01HZ8X3J9K7P2QV6R5N4M3T2L1");

Path parameters

id string required

Response200

Property	Type	Description
`id` required	string
`object` required	enum (1)	`"thread"`
`inbox_id` required	string
`provider_thread_id` required	string	Gmail's resource id.
`subject` required	string \| null
`message_count` required	integer
`has_reply` required	boolean
`has_bounce` required	boolean
`last_message_at` required	string (date-time) \| null
`first_message_at` required	string (date-time) \| null
`messages` required	array<ThreadMessage>

Example response

{
  "id": "thr_01HZ8X3J9K7P2QV6R5N4M3T2L1_18f8a2b3c4d5e6f",
  "object": "thread",
  "inbox_id": "inb_01HZ8X3J9K7P2QV6R5N4M3T2L1",
  "provider_thread_id": "18f8a2b3c4d5e6f",
  "subject": "Quick question about Acme's data stack",
  "message_count": 2,
  "has_reply": true,
  "has_bounce": false,
  "last_message_at": "2026-04-29T16:42:11Z",
  "first_message_at": "2026-04-29T14:30:02Z"
}

Errors

400 Invalid request
401 Authentication failed
403 Insufficient scope
404 Not found
409 Conflict
422 Validation failed
429 Rate limited

See Errors for the full envelope and per-code reference.

Reply in a thread (sugar over POST /v1/sends)

post /v1/threads/{id}/replies

Routes through the same send pipeline as POST /v1/sends, but pre-fills `thread_id_to` and `in_reply_to_message_id` from the thread, and defaults the recipient + subject when omitted.

curl TypeScript

curl -X POST "https://api.clement.so/v1/threads/obj_01HZ8X3J9K7P2QV6R5N4M3T2L1/replies" \
  -H "Authorization: Bearer $CLEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data '{
      "subject": "Quick question about your stack",
      "body_html": "<p>Hi {{first_name}}, would love to chat — does Tuesday work?</p>",
      "body_text": "Hi {{first_name}}, would love to chat — does Tuesday work?",
      "variables": {},
      "to": "alice@example.com",
      "metadata": {},
      "append_signature": false
    }'

import { Clement } from "@clement/sdk";

const c = new Clement({ apiKey: process.env.CLEMENT_API_KEY! });
const result = await c.threads.reply("obj_01HZ8X3J9K7P2QV6R5N4M3T2L1", {
  "subject": "Quick question about your stack",
  "body_html": "<p>Hi {{first_name}}, would love to chat — does Tuesday work?</p>",
  "body_text": "Hi {{first_name}}, would love to chat — does Tuesday work?",
  "variables": {},
  "to": "alice@example.com",
  "metadata": {},
  "append_signature": false
}, { idempotencyKey: crypto.randomUUID() });

Path parameters

id string required

Request body

Property	Type	Description
`subject`	string	Defaults to `Re: <last subject in thread>`.
`body_html`	string
`body_text`	string
`variables`	object
`to`	string (email)	Recipient. Optional — defaults to the most recent inbound from_email in the thread.
`metadata`	object
`append_signature`	boolean	Append the inbox's signature to the reply. Default false.

Response201

Reply scheduled

No schema.

Errors

400 Invalid request
401 Authentication failed
403 Insufficient scope
404 Not found
409 Conflict
422 Validation failed
429 Rate limited

See Errors for the full envelope and per-code reference.