API reference
The message object
Every endpoint answers with the same message object; some fields appear only where they apply.
Amounts are integers in micros, millionths of your account's currency: 30000 is 0.03. Times are RFC 3339 with an offset. Fields marked “only when” are left out of the JSON otherwise; the others are always there, null when empty.
Fields#
idstring
The message's id (a UUID). It identifies the message in lookups and webhooks.
tostring
The recipient, in E.164.
fromstring
The sender ID it was sent from.
bodystring
The text as sent: after smart encoding and link shortening. Empty once your account's data retention has erased it, and then
body_erased is true.linksarray
Only when the message has short links: see Short links. Returned by
GET /v1/messages/{id}, and by the send itself when it shortened links.statusstring
countrystring
The recipient's country, ISO 3166-1 alpha-2 (
GB).networkstring
Only when known: the recipient's mobile network.
encodingstring
gsm7 or ucs2.segmentsinteger
The parts billed.
price_microsinteger
What the message cost: the price per part times its parts.
localboolean
Only where your prices distinguish them: whether the message was priced as local or international traffic.
campaign_idstring | null
The campaign it belongs to, or
null.client_referencestring
Only when you set one: your own id for the message.
expires_atstring
Only when you set a
validity_period: when we stop trying to send it.error_codestring | null
Why it didn't arrive, on
undelivered and failed messages; RETRYING while it waits to be tried again. See error codes.error_messagestring | null
The same, in words, for people. Branch on
error_code.attemptsinteger
How many times we've tried to send it.
created_atstring
When we accepted it.
sent_atstring | null
When the network accepted every part.
done_atstring | null
When it reached its final status.
partsarray
Only in
GET /v1/messages/{id}: one entry per part, below.Parts#
seqinteger
The part's number, from 1.
unitsinteger
Characters in this part: GSM-7 septets or UTF-16 code units.
limitinteger
How many fit in a part of this message: 160 or 153 (GSM-7), 70 or 67 (Unicode).
statusstring
pending, accepted, delivered, undelivered or failed.smsc_idstring | null
The network's id for the part, once accepted.
receipt_statstring | null
The delivery receipt's status:
DELIVRD, UNDELIV, EXPIRED, REJECTD, DELETED, UNKNOWN…receipt_errstring | null
The receipt's network error code.
submitted_atstring | null
When the network accepted the part.
done_atstring | null
When its final receipt came.
Links#
codestring
The link's 7-character code.
short_urlstring
The short address in the text.
urlstring
Where it leads: the address you wrote.
clicksinteger
Visits counted, previews and bots left out.
first_click_atstring | null
The first counted visit.
last_click_atstring | null
The latest counted visit.