Skip to content
ThreadkiteThreadkite Docs

Send a reply, add a note, send an automated message, or log one

POST
/v1/messages
curl --request POST \
  --url https://api.threadkite.app/v1/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "threadId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "contactId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "inboxId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "contactExternalId": { "integration": "my-dms", "externalId": "CUST-10442" }, "to": { "email": "sarah.turner@example.co.uk", "phone": "07911 123456", "name": "Sarah Turner" }, "kind": "message", "channel": "email", "subject": "example", "text": "Hi Sarah, yes it is. Saturday at 10 works for us.", "html": "example", "cc": [ { "address": "accounts@example.co.uk", "name": "example" } ], "bcc": [ { "address": "accounts@example.co.uk", "name": "example" } ], "automationKey": "invoice", "transactional": false, "purpose": "reply", "link": { "recordType": "deal", "integration": "my-dms", "externalId": "DEAL-2231", "label": "Deal #2231", "url": "https://example.com", "status": "open" }, "alreadySent": false, "sentAt": "2026-04-15T12:00:00Z", "externalId": "example", "integration": "my-dms", "record": { "type": "invoice", "externalId": "8812" }, "itemIds": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "locationId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "attachmentIds": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "channelAccountId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "mailboxConnectionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "template": { "templateId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "variables": [] }, "signature": true, "reopen": false }'

Replies and automated messages are checked against consent (transactional automated messages are exempt from opt-outs) and queued for delivery; their status follows in message.status webhooks. With alreadySent, the message is only logged. Basic seats can add notes only.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
<= 255 characters

Any unique value up to 255 characters (a UUID, or the id of the item in your outbox). For 24 hours a retry with the same key and request returns the first response, with Idempotent-Replayed: true, instead of doing it again. Works with an API key or a signed-in session; each has its own keys.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
threadId

The thread to add to

string format: uuid
contactId

Or the contact: their thread is used (and created, for automated messages)

string format: uuid
inboxId

With contactId: the inbox whose thread to use (a contact has one thread per inbox). Your default inbox when left out

string format: uuid
contactExternalId

Or the contact’s id in your system

object
integration
required

The other system, e.g. my-dms

string

Example 

my-dms
externalId
required

The contact’s id there

string

Example 

CUST-10442
to

Or an email address, for a new message to someone who has not written in: the contact with that address is used, or added. Messages only.

object
email
string format: email
<= 254 characters

Example 

sarah.turner@example.co.uk
phone

A phone number: logged messages only (alreadySent), for a text you sent

string
>= 1 characters <= 40 characters

Example 

07911 123456
name
string
nullable <= 200 characters

Example 

Sarah Turner
kind
required

message: a reply to the contact. note: internal, never sent. automated: from a flow in your system (invoice, e-sign, receipt).

string
Allowed values: message note automated
channel

Defaults to the thread’s last channel when the contact can be reached on it (an address that has not failed, no opt-out, and for texts and WhatsApp a connected number), else the first channel they can be reached on, email first. Ignored for notes.

string
Allowed values: email sms whatsapp chat marketplace messenger instagram
subject
string
nullable <= 500 characters
text
required
string
>= 1 characters <= 50000 characters

Example 

Hi Sarah, yes it is. Saturday at 10 works for us.
html

The message formatted, as HTML (bold, italics, underline, lists, links, quotes and headings are kept; everything else is removed). Email: sent as the HTML part, with text as the plain part. WhatsApp: sent with WhatsApp formatting made from it instead of text. Notes keep it. Ignored on other channels

string
nullable <= 500000 characters
cc
Array<object>
<= 20 items
object
address
required
string
>= 3 characters <= 254 characters

Example 

accounts@example.co.uk
name
string
nullable <= 200 characters
bcc
Array<object>
<= 20 items
object
address
required
string
>= 3 characters <= 254 characters

Example 

accounts@example.co.uk
name
string
nullable <= 200 characters
automationKey

Required for automated messages

string
>= 1 characters <= 100 characters

Example 

invoice
transactional

Automated only: the contact needs it whatever they opted out of (invoices, receipts, e-sign)

boolean
purpose

Automated only: marketing (review requests, offers) needs opt-in; reminder (an appointment or renewal reminder) needs a reminders or marketing opt-in on the channel

string
Allowed values: reply marketing reminder
link

A record in your system to link

object
recordType
required
string
Allowed values: deal appraisal finance_application invoice esign reservation other
integration
required
string
/^[a-z0-9][a-z0-9_.-]{0,49}$/

Example 

my-dms
externalId
required
string
>= 1 characters <= 200 characters

Example 

DEAL-2231
label
required
string
>= 1 characters <= 200 characters

Example 

Deal #2231
url
string format: uri
nullable <= 2000 characters
status
string
nullable <= 50 characters

Example 

open
alreadySent

You already sent it yourself: log it in the thread without sending

boolean
sentAt

When a logged message was sent

string format: date-time
externalId

Your system’s id for a logged message. Logging the same id again returns the message already logged; delivery updates name it (POST /v1/messages/by-external-id/{externalId}/status)

string
<= 500 characters
integration

Your system, when you are not an app: the logged message’s externalId is yours under it (api when left out). An app’s are always its own

string
/^[a-z0-9][a-z0-9_.-]{0,49}$/

Example 

my-dms
record

A record of yours it is about (sent with an event before): the message shows it

object
type
required
string
<= 50 characters /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/

Example 

invoice
externalId
required
string
>= 1 characters <= 200 characters

Example 

8812
itemIds

Catalogue items the message is about; added to the thread

Array<string>
<= 20 items
locationId
string format: uuid
nullable
attachmentIds

Files uploaded with POST /v1/attachments (up to 10, 20 MB in all). Sent with email replies and kept on notes.

Array<string>
<= 10 items
channelAccountId

Texts and WhatsApp: the number to send from (GET /v1/threads/{id}/reply-channels). Defaults to the number the contact last wrote to, else the inbox’s

string format: uuid
mailboxConnectionId

Email: send through this connected mailbox (your own, or the shared mailbox of the thread’s inbox) so it goes from that address and lands in its Sent folder. See senders on GET /v1/threads/{id}/reply-channels. Without it email goes from your Threadkite address

string format: uuid
template

WhatsApp: send an approved template instead of free text (required more than 24 hours after their last message)

object
templateId
required

From GET /v1/threads/{id}/reply-channels

string format: uuid
variables

Values for the template’s variables, in order

Array<string>
default: <= 20 items

Example 

[
  "Sarah"
]
signature

Email: add the signature (the inbox’s, else the business’s, filled in for whoever sends). On unless false; never added twice when the text already ends with it

boolean
reopen

Messages only: reopen the thread when it is Done, as the message is sent (a won thread keeps its outcome). Without it a Done thread stays Done

boolean

Responses

Section titled “Responses”

201

Section titled “201”
Media typeapplication/json
object
message
required
object
id
required
string format: uuid
threadId
required
string format: uuid
chapterId
required

The chapter of the thread it is in

string format: uuid
kind
required
string
Allowed values: message note automated event
direction
required
string
Allowed values: in out internal
channel
required
string
Allowed values: email sms whatsapp chat phone form api marketplace visit messenger instagram internal
contactId
required
string format: uuid
nullable
locationId
required
string format: uuid
nullable
source
required
One of:
object
id
required
string format: uuid
key
required
string
name
required
string
logoUrl
required

Logo address; null shows an initial badge

string
nullable
isLead
required

Counts as a lead in reports

boolean
isTest
required

A made-up lead from “Send a test lead”, never counted

boolean
leadOverride
required

A person marked (true) or unmarked (false) it as a lead; null when the rule decided

boolean
nullable
leadType
required
string
nullable
items
required

The catalogue items the message named, in order

Array
One of: discriminator: type
object
id
required
string format: uuid
source
required

Where the item came from: manual, csv, api or an integration key

string
externalId
required

The item’s id in its source

string
locationId
required
string format: uuid
nullable
title
required

From the attributes

string
status
required

The availability: in_stock, out_of_stock, preorder or backorder for products; an industry pack’s item types have their own

string
price
required
One of:
object
amountMinor
required

Amount in minor units (pence, cents)

number
currency
required

ISO 4217

string
billing
required

How the price is charged: one_off (once), monthly (every month) or annual (every year)

string
Allowed values: one_off monthly annual
images
required

Image links, main image first

Array<string>
archivedAt
required

When it was removed from the catalogue (no longer in stock). Removed items stay on the leads and threads that mention them

string format: date-time
nullable
url
required

Advert or product page

string
nullable
addOn
required

Usually sold as an add-on to something else (a warranty, delivery, an onboarding package). Suggestions only

boolean
addOnFor
required

The item types it is usually added to; empty means anything

Array<string>
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
attributes
required
object
title
required

Google/Meta title

string
<= 150 characters
description

Google/Meta description

string
<= 5000 characters
link

Product page. Google/Meta link

string format: uri
imageLinks

Main image first. Google/Meta image_link and additional_image_link

Array<string>
<= 11 items
price
required

Google/Meta price

object
amountMinor
required

Amount in minor units (pence, cents)

number
currency
required

ISO 4217

string
salePrice

Google/Meta sale_price

object
amountMinor
required

Amount in minor units (pence, cents)

number
currency
required

ISO 4217

string
availability

Google/Meta availability

string
default: in_stock
Allowed values: in_stock out_of_stock preorder backorder
condition

Google/Meta condition

string
default: new
Allowed values: new refurbished used
brand

Google/Meta brand

string
<= 70 characters
gtin

GTIN-8, 12, 13 or 14. Google/Meta gtin

string
mpn

Google/Meta mpn

string
<= 70 characters
sku

Your own stock code

string
<= 100 characters
googleProductCategory

Google/Meta google_product_category

string
<= 750 characters
productType

Google/Meta product_type

string
<= 750 characters
itemGroupId

Shared by variants. Google/Meta item_group_id

string
<= 50 characters
size

Google/Meta size

string
<= 100 characters
colour

Google/Meta color

string
<= 100 characters
material

Google/Meta material

string
<= 200 characters
pattern

Google/Meta pattern

string
<= 100 characters
customLabel0

Google/Meta custom_label_0

string
<= 100 characters
customLabel1

Google/Meta custom_label_1

string
<= 100 characters
customLabel2

Google/Meta custom_label_2

string
<= 100 characters
customLabel3

Google/Meta custom_label_3

string
<= 100 characters
customLabel4

Google/Meta custom_label_4

string
<= 100 characters
type
required
string
Allowed values: product
subject
required
string
nullable
text
required
string
html
required
string
nullable
author
required
object
userId
required

Set when a person wrote it

string
nullable
name
required
string
nullable
status
required

Outbound: queued, sent, delivered, opened, read, failed… Inbound: received

string
nullable
statusAt
required
string format: date-time
nullable
failureReason
required

Why delivery failed, when the status is failed, bounced or complained

string
nullable
canRetry
required

Not sent after every retry: POST /v1/messages/{id}/retry tries again

boolean
automationKey
required
string
nullable
transactional
required
boolean
logged
required

Sent outside Threadkite and logged here

boolean
externalId
required
string
nullable
authVerdict
required

Email authentication: pass, fail, unverified

string
nullable
spamVerdict
required
string
nullable
responseSeconds
required

First reply: seconds it took

number
nullable
participants
required
Array<object>
object
role
required
string
Allowed values: from to cc bcc
address
required
string
name
required
string
nullable
contactId
required
string format: uuid
nullable
attachments
required
Array<object>
object
id
required
string format: uuid
fileName
required
string
mimeType
required
string
size
required
number
scanStatus
required
string
Allowed values: pending clean infected
inline
required

An inline image in the email’s HTML (a pasted photo, a signature logo), not a file attached

boolean
contentId
required

For an inline image: the Content-ID the HTML’s cid: image points at

string
nullable
skippedAttachments
required

Files the email came with that were not kept (a type we refuse, too large, or failed the virus check)

Array<object>
object
fileName
required
string
reason
required

Why it was not kept, in plain words

string
tracking
required
One of:
object
landingPageUrl
required
string
nullable
referrer
required
string
nullable
utmSource
required
string
nullable
utmMedium
required
string
nullable
utmCampaign
required
string
nullable
utmTerm
required
string
nullable
utmContent
required
string
nullable
utmId
required

The ad platform’s campaign id

string
nullable
clickId
required

The ad click id, as kind:value

string
nullable
campaign
required

The campaign the lead came from (its UTMs or its lead ad)

object
id
required
string format: uuid
name
required
string
trafficChannel
required

Where the visit came from, worked out when the lead arrived

string
nullable
Allowed values: paid_search paid_social display email sms affiliate organic_search organic_social referral direct other
consentCategories
required
Array<string>
nullable
data
required

Render-only extras, such as the fields of a form

object
key
additional properties
any
lead
required
One of:
object
format
required
string
Allowed values: adf labelled extracted sender
provider
required

The lead provider, as the email names it

string
nullable
forwardedBy
required
One of:
object
userId
required
string
nullable
name
required
string
forwardNote
required

What they wrote when forwarding it

string
nullable
needsSource
required

A forwarded lead whose real source nobody has picked yet

boolean
receivedLeadId
required
string format: uuid
nullable
reference
required
One of:
object
messageId
required
string format: uuid
threadId
required
string format: uuid
contactName
required
string
subject
required
string
nullable
appointment
required
One of:
object
id
required
string format: uuid
action
required

Events: booked, moved, cancelled, confirmed, completed, no_show. Messages to the customer: confirmation, reminder_day, reminder_soon, updated, cancelled.

string
call
required
One of:
object
direction
required
string
Allowed values: in out
outcome
required
string
nullable
Allowed values: answered missed voicemail failed
durationSeconds
required

Seconds talking

number
nullable
from
required

The caller (null when withheld or erased)

string
nullable
to
required

The number they called

string
nullable
menuChoice
required

The menu option the caller chose

string
nullable
forwardedTo
required

Numbers the call was forwarded to

Array<string>
voicemail
required

They left a voicemail

boolean
transcript
required

The voicemail, as text

string
nullable
hasRecording
required

GET /v1/messages/{id}/recording gives a link to play it

boolean
recordingHeldBy
required

The recording is held in this provider’s account and cannot be played here now (the connection is gone)

string
nullable
recordingSeconds
required
number
nullable
recordingPauses
required

When the recording was paused during the call (for card details); it has silence for each

Array<object>
object
pausedAt
required
string format: date-time
resumedAt
required
string format: date-time
nullable
recordingDeleted
required

The recording is no longer available (deleted at the end of the retention period, on erasure, or in the provider account)

boolean
source
required
One of:
object
id
required
string format: uuid
name
required
string
loggedFrom
required

Set for a call made outside a connected phone system and logged in the mobile or web app (POST /v1/threads/{id}/calls)

string
nullable
Allowed values: mobile web
loggedOutcome
required

For logged calls: what they picked after the call

string
nullable
Allowed values: answered no_answer voicemail wrong_number
callId
required

The call (GET /v1/calls/{id}); null for a call logged in the app with no phone system behind it

string format: uuid
nullable
summary
required

A short summary of the call, made from its recording

string
nullable
hasTranscript
required

GET /v1/calls/{id}/transcript gives who said what

boolean
disposition
required

For a call made in Threadkite: how it went, as the person said afterwards

string
nullable
Allowed values: answered no_answer voicemail wrong_number
notes
required

For a call made in Threadkite: the notes saved after it

string
nullable
suggestedContact
required
One of:
object
name
object
current
required
string
nullable
suggested
required
string
email
object
current
required
string
nullable
suggested
required
string
phone
object
current
required
string
nullable
suggested
required
string
company
object
current
required
string
nullable
suggested
required
string
companyId
required
string format: uuid
nullable
jobTitle
object
current
required
string
nullable
suggested
required
string
company
string
template
required
One of:
object
name
required
string
language
required
string
category
required
string
Allowed values: marketing utility authentication
video
One of:
object
id
required
string format: uuid
title
required
string
status
required

expired once it has been deleted (the message shows “Video expired”)

string
Allowed values: uploading processing ready failed expired
lengthSeconds
required
number
nullable
posterUrl
required

Signed poster image (valid a few hours), once the video is ready

string
nullable
opens
required

Times the watch page was opened

number
opened
required

They opened the watch page

boolean
started
required

They started watching

boolean
watched50
required

They watched at least half

boolean
watched90
required

They watched (nearly) all of it

boolean
record
required
One of:
object
recordId
required
string format: uuid
source
required
string
sourceName
required
string
type
required
string
icon
required
string
Allowed values: invoice quote signature document payment booking order link
label
required
string
url
required
string
nullable
status
required
string
nullable
tone
required
string
Allowed values: success warning danger neutral
amount
required
One of:
object
value
required

In major units

number
currency
required
string
details
required
object
key
additional properties
string
previousStatus
required

The status before this event

string
nullable
first
required

The first line about the record on this thread: shown as a card

boolean
late
required

Arrived late: older than the record’s state, changed nothing

boolean
text
required

The line for people

string
pin
required
One of:
object
at
required

When it was pinned

string format: date-time
by
required
One of:
object
id
required
string
name
required
string
redactedAt
required
string format: date-time
nullable
createdAt
required
string format: date-time
threadId
required
string format: uuid
claimed
required

The thread had no owner and you claimed it by replying

boolean

Example 

{
  "message": {
    "kind": "message",
    "direction": "in",
    "channel": "email",
    "source": {
      "key": "website-form",
      "name": "Website form"
    },
    "leadType": "quote",
    "items": [
      {
        "source": "my-dms",
        "externalId": "SKU-1042",
        "title": "Oak dining table",
        "status": "in_stock",
        "price": {
          "amountMinor": 1299500,
          "currency": "GBP"
        },
        "billing": "one_off",
        "addOnFor": [
          "product"
        ],
        "attributes": {
          "title": "Merino jumper",
          "price": {
            "amountMinor": 1299500,
            "currency": "GBP"
          },
          "salePrice": {
            "amountMinor": 1299500,
            "currency": "GBP"
          },
          "availability": "in_stock",
          "condition": "new"
        },
        "type": "product"
      }
    ],
    "text": "Is this still available?",
    "author": {
      "name": "James Patel"
    },
    "failureReason": "The address does not exist",
    "automationKey": "invoice",
    "participants": [
      {
        "role": "from",
        "address": "sarah.turner@example.co.uk"
      }
    ],
    "attachments": [
      {
        "fileName": "photo.jpg",
        "mimeType": "image/jpeg",
        "size": 182044,
        "scanStatus": "pending",
        "contentId": "ii_m1x2y3z40"
      }
    ],
    "skippedAttachments": [
      {
        "fileName": "video.mov",
        "reason": "video.mov is larger than 20 MB."
      }
    ],
    "tracking": {
      "clickId": "gclid:Cj0KCQjw",
      "campaign": {
        "name": "Spring sale"
      },
      "trafficChannel": "paid_search"
    },
    "lead": {
      "format": "adf",
      "forwardedBy": {
        "name": "Chris Moore"
      }
    },
    "reference": {
      "contactName": "James Turner"
    },
    "appointment": {
      "action": "booked"
    },
    "call": {
      "direction": "in",
      "outcome": "answered",
      "recordingHeldBy": "Twilio",
      "source": {
        "name": "Google Ads"
      },
      "loggedFrom": "mobile",
      "loggedOutcome": "answered",
      "disposition": "answered"
    },
    "template": {
      "name": "missed_call",
      "language": "en_GB",
      "category": "marketing"
    },
    "video": {
      "status": "uploading"
    },
    "record": {
      "icon": "invoice",
      "tone": "success",
      "amount": {
        "value": 289,
        "currency": "GBP"
      },
      "text": "Invoice INV-8812: Awaiting payment → Paid"
    },
    "pin": {
      "by": {
        "id": "usr_8f2c",
        "name": "James Patel"
      }
    }
  }
}

400

Section titled “400”
Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>
object
path
required

Dotted path inside the item, e.g. attributes.price.amountMinor

string
message
required
string

Example 

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

401

Section titled “401”

Missing or invalid API key

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>
object
path
required

Dotted path inside the item, e.g. attributes.price.amountMinor

string
message
required
string

Example 

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

402

Section titled “402”

The organisation is on the Free plan (code upgrade_required)

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
feature
required

The feature that needs Pro

string
nullable
Allowed values: extraSeats connections aiAssistant aiReplies rules fullReports api inboxes bulkMessages videoMessages
upgradePath
required

Where to upgrade or pay, in the web app

string

Example 

{
  "statusCode": 402,
  "code": "upgrade_required",
  "message": "Connections are part of Pro. Upgrade to connect texts, calls and more.",
  "feature": "extraSeats",
  "upgradePath": "/settings/billing"
}

403

Section titled “403”

The key does not have the scope (or the person the permission)

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>
object
path
required

Dotted path inside the item, e.g. attributes.price.amountMinor

string
message
required
string

Example 

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

404

Section titled “404”
Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>
object
path
required

Dotted path inside the item, e.g. attributes.price.amountMinor

string
message
required
string

Example 

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

422

Section titled “422”

Refused: opted_out, invalid_address, no_marketing_consent or marketing_suppressed (the person asked not to receive marketing)

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>
object
path
required

Dotted path inside the item, e.g. attributes.price.amountMinor

string
message
required
string

Example 

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

429

Section titled “429”

Rate limit reached

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
retryAfter
required

Seconds until another request will be accepted

number

Example 

{
  "statusCode": 429,
  "code": "rate_limited",
  "message": "Too many requests. Each key can make 120 requests a minute; try again in 12 seconds.",
  "retryAfter": 12
}