List messages

GET /v1/messages

Send your API key as a bearer token: Authorization: Bearer ssms_sk_.... Test keys run this endpoint against the sandbox; see Authentication for key modes and scopes.

Query parameters

Name	Type	Required	Description
`limit`	integer	No	Default 25. Maximum 100.
`cursor`	string	No
`number`	string	No	Filter to messages to or from this number
`to`	string	No	Exact destination number (E.164)
`from`	string	No	Exact sending number (E.164)
`status`	`queued`, `sent`, `delivered`, `failed`, `received`	No
`direction`	`outbound`, `inbound`	No
`created_after`	string	No	Inclusive. ISO timestamp or epoch ms.
`created_before`	string	No	Exclusive. ISO timestamp or epoch ms.
`customer_id`	string	No	Filter to one customer's messages
`schedule_id`	string	No	Filter to the occurrences of one recurring schedule (sch_...)

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

Responses

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

200: each item in `data` (Message)

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

Field	Type	Description
`id`	string	Example: `msg_a1B2c3D4e5F6g7H8`.
`object`	`message`
`to`	string	Example: `+15005550006`.
`from`	string	Example: `+15005550100`.
`body`	string
`direction`	`outbound`, `inbound`
`status`	`queued`, `sent`, `delivered`, `failed`, `received`
`test`	boolean
`simulated`	boolean	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`.
`notice`	string	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_id`	string	The recurring schedule this message is an occurrence of. Present only when set.
`created_at`	string (date-time)
`media`	array of string (uri)	MMS attachments (inbound today).
`sent_by`	string	Console user or API key that composed it.
`failure_reason`	string	The carrier's raw text for a failed send. Kept for compatibility; see `failure`.
`attempts`	integer	Live sends: carrier submissions so far. More than 1 means it was retried.
`next_attempt_at`	string (date-time)	Present while queued for an automatic carrier retry.
`receipt_status`	`missing`	The carrier accepted the message but sent no delivery report within 72 hours. status stays sent.
`customer_id`	string	The customer this is attributed to. Present only when set.
`timeline`	array of object	Every status transition, oldest first. Inbound messages have a single `received`.
`timeline[].status`	`accepted`, `validated`, `queued`, `sent_to_carrier`, `carrier_accepted`, `retry_scheduled`, `delivered`, `failed`, `received`
`timeline[].at`	string (date-time)
`timeline[].attempt`	integer	Carrier attempt this step belongs to (from sent_to_carrier on).
`segments`	integer	Parts the body is split into (GSM-7: 160, then 153 each; UCS-2: 70, then 67). Example: `1`.
`encoding`	`gsm7`, `ucs2`
`price`	object	What this message costs, in USD. One all-in rate per outbound message; carrier fees are included (a 0 line). Null on messages sent before prices were recorded. Nullable.
`price.total`	number	Example: `0.009`.
`price.currency`	`usd`
`price.breakdown`	array of object
`price.breakdown[].label`	string
`price.breakdown[].amount`	number
`destination_carrier`	string	The recipient's mobile carrier, when a cached lookup knows it. Nullable.
`failure`	Failure	Null unless status is `failed`. Nullable.

Errors

Status	When
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

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.

json

{
  "error": {
    "code": "invalid_request",
    "message": "What went wrong, in plain words.",
    "param": "the_field",
    "request_id": "req_a1B2c3D4e5F6g7H8"
  }
}

Examples

curl

bash

curl -X GET "https://api.joinsimplesms.com/v1/messages?limit=10" \
  -H "Authorization: Bearer $SIMPLESMS_API_KEY"

Node.js

javascript

import { SimpleSMS } from 'joinsimplesms'; // npm install joinsimplesms

const sms = new SimpleSMS(process.env.SIMPLESMS_API_KEY);

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

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

Python

python

import os
from joinsimplesms import SimpleSMS  # pip install joinsimplesms

client = SimpleSMS(os.environ["SIMPLESMS_API_KEY"])

page = client.messages.list(limit=10)

for message in page["data"]:
    print(message["id"], message["status"])