List messages

GET/v1/messages

Query Parameters

Results are paged. When has_more is true, pass next_cursor from the response as cursor to fetch the next page.

limitinteger
Default 25. Maximum 100.
cursorstring
numberstring
Filter to messages to or from this number
tostring
Exact destination number (E.164)
fromstring
Exact sending number (E.164)
statusqueued, sent, delivered, failed, blocked, received
blocked_reasonaccount_closed, account_suspended, account_paused, opted_out, destination_not_allowed, sender_not_registered, campaign_mismatch, rate_limited, recipient_not_verified, quiet_hours, consent_required, reconfirmation_pending, reconfirmation_expired, campaign_paused, sender_rotation, content_blocked, screen_unavailable, held_for_review, review_rejected, review_expired, quota_exceeded, spend_limit_reached, insufficient_credits, topic_unsubscribed
Blocked messages with this reason. Implies status=blocked.
failure_codestring
Failed or blocked messages whose failure.code is this.
directionoutbound, inbound
failure_codecarrier_filtered, unreachable, invalid_number, opted_out, campaign_mismatch, content_blocked, screen_unavailable, rate_limited, landline, carrier_rejected, spend_limit_reached, insufficient_credits, sender_not_registered, quiet_hours, consent_required, reconfirmation_pending, reconfirmation_expired, held_for_review, review_rejected, review_expired, campaign_paused, sender_rotation, recipient_not_verified, quota_exceeded, destination_not_allowed, account_closed, account_suspended, account_paused, topic_unsubscribed, unknown
Filter to messages that failed for this reason (the failure.code on a message)
created_afterstring
Inclusive. ISO timestamp or epoch ms.
created_beforestring
Exclusive. ISO timestamp or epoch ms.
customer_idstring
Filter to one customer's messages
schedule_idstring
Filter to the occurrences of one recurring schedule (sch_...)
tagstring
Filter to messages sent with this tag

Responses

200Page of Message
Messages, newest first
401Error
Missing, malformed, or revoked API key
402Error
Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged
429Error
Rate limit or quota exceeded

Response Fields

The body is a page: data (the array), has_more, and next_cursor (null on the last page). Each item in data:

idstring
Example: msg_a1B2c3D4e5F6g7H8.
objectmessage
tostring
Example: +15005550006.
fromstring
Example: +15005550100.
bodystring
directionoutbound, inbound
statusqueued, sent, delivered, failed, blocked, received
blocked: refused by one of our checks before any carrier saw it (opt-out, quiet hours, unregistered sender, content, allowance, spend limit, credits). Final, never charged; failure says why. failed: accepted, then not delivered.
testboolean
simulatedboolean
True when nothing was handed to a carrier: every test-key message except one sent to your own verified phone. Always false on live messages. A simulated message still reaches delivered.
noticestring
Only on the response to POST /messages. Present when a test-key send to a real-looking number was simulated: says nothing was sent and how to send for real.
schedule_idstring
The recurring schedule this message is an occurrence of. Present only when set.
tagsarray of string
The labels sent with the message (tags on POST /messages), lowercased. Present only when set.
categorymarketing, transactional, otp
How the message was classified. Present when you sent one, or when it was classified as marketing.
disclosures_addedarray of brand, opt_out
Wording we added to a message from a number linked to a registration (what we add): brand, your business name in front of a person's first message; opt_out, " Reply STOP to opt out." on marketing that had none. body is the text as sent. Present only when we added something.
deferredobject
Present when the message was held for quiet hours and sent when the window opened.
deferred.reasonquiet_hours
deferred.held_atstring (date-time)
redacted_atstring (date-time)
When the message was redacted (POST /messages/{id}/redact): body is empty and media is gone. Present only then.
linksarray of object
Links shortened with shorten_links, in the order they appear. On the send response and GET /messages/{id} (with clicks so far); not on list pages. body is the text as sent, with the short links.
links[].urlstring
The link as you wrote it.
links[].short_urlstring
Example: https://links.example.com/Ab3dEf9h.
links[].clicksinteger
Opens by people. Link previews (a messaging app fetching the link to draw a preview) are not counted.
links[].first_clicked_atstring (date-time)
Nullable.
links[].last_clicked_atstring (date-time)
Nullable.
created_atstring (date-time)
mediaarray of string (uri)
MMS attachments (inbound today).
sent_bystring
Console user or API key that composed it.
failure_reasonstring
The carrier's raw text for a failed send. Kept for compatibility; see failure.
attemptsinteger
Live sends: carrier submissions so far. More than 1 means it was retried.
next_attempt_atstring (date-time)
Present while queued for an automatic carrier retry.
receipt_statusmissing
The carrier accepted the message but sent no delivery report within 72 hours. status stays sent.
customer_idstring
The customer this is attributed to. Present only when set.
timelinearray of object
Every status transition, oldest first. Inbound messages have a single received.
timeline[].statusaccepted, validated, queued, sent_to_carrier, carrier_accepted, retry_scheduled, delivered, failed, blocked, received
timeline[].atstring (date-time)
timeline[].attemptinteger
Carrier attempt this step belongs to (from sent_to_carrier on).
segmentsinteger
Parts the body is split into (GSM-7: 160, then 153 each; UCS-2: 70, then 67). Example: 1.
encodinggsm7, ucs2
priceobject
What this message costs, in USD: the outbound rate per segment, plus the recipient's carrier fee per segment, at cost, as its own line. Null on messages sent before prices were recorded. Nullable.
price.totalnumber
Example: 0.0082.
price.currencyusd
price.breakdownarray of object
price.breakdown[].labelstring
price.breakdown[].amountnumber
destination_carrierstring
The recipient's mobile carrier, when a cached lookup knows it. Nullable.
failureFailure
Null unless status is failed. Nullable.

Errors

Every error has the same JSON shape, and request_id matches the X-Request-Id response header. Errors lists every code and what to do about it.

401
Missing, malformed, or revoked API key
402
Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged
429
Rate limit or quota exceeded

import { TextKit } from 'jointextkit'; // npm install jointextkit

const sms = new TextKit(process.env.TEXTKIT_API_KEY);

const page = await sms.messages.list({ limit: 10 });

for (const message of page.data) console.log(message.id, message.status);

Response 200

{
  "data": [
    {
      "id": "msg_a1B2c3D4e5F6g7H8",
      "object": "message",
      "to": "+15005550006",
      "from": "+15005550100",
      "direction": "outbound",
      "status": "queued",
      "tags": [
        "spring-sale"
      ],
      "category": "marketing",
      "segments": 1,
      "encoding": "gsm7"
    }
  ],
  "has_more": true,
  "next_cursor": null
}