​
Overview

A Thread is a 1:1 conversation between one of your sending numbers and another party. Threads are created automatically the first time you send to a new address or receive a message from one, and they are returned by GET /v1/threads. The same peer messaged from two different sending numbers is two distinct threads.

​
Properties

​
thread_id
string
Unique thread identifier (UUID). Use it to send follow-up messages in the conversation and to read its history.
​
number
string
Your sending number the conversation is on. Follow-up sends in the thread always go out from this number.
​
address
string
The other party’s address in canonical form: +1XXXXXXXXXX for US phone numbers, or the raw email address for email-style iMessage handles.
​
display_name
string | null
Contact display name when known, otherwise null.
​
last_text
string
Text of the most recent message in the thread. Empty string if the thread has no messages yet.
​
last_unix_ms
number | null
Timestamp of the most recent activity in the thread, in milliseconds since the Unix epoch.
​
service
string | null
Service of the most recent message: iMessage or SMS.

​
Example

{
  "thread_id": "0b6f5c1e-8f4a-4f4b-9a2d-3a1c2b3d4e5f",
  "number": "+12315551234",
  "address": "+15551234567",
  "display_name": null,
  "last_text": "Sounds good, see you then!",
  "last_unix_ms": 1765432100000,
  "service": "iMessage"
}

​
Address Canonicalization

Addresses you pass to POST /v1/messages are canonicalized before the thread is matched or created:
  • 10-digit US numbers become +1XXXXXXXXXX (e.g. 5551234567 → +15551234567)
  • Numbers already carrying a leading 1 country code are normalized to +1XXXXXXXXXX
  • Email addresses (iMessage handles) are left untouched
This means 5551234567, (555) 123-4567, and +15551234567 all resolve to the same thread.