List SMS/MMS history

GET

/api/v2/messages

curl --request GET \
  --url 'https://api.sipstack.com/api/v2/messages?page=1&limit=50&direction=inbound' \
  --header 'x-api-key: <x-api-key>'

import requests

url = "https://api.sipstack.com/api/v2/messages"

querystring = {"page":"1","limit":"50","direction":"inbound"}

headers = {"x-api-key": "<x-api-key>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())

const url = 'https://api.sipstack.com/api/v2/messages?page=1&limit=50&direction=inbound';
const options = {method: 'GET', headers: {'x-api-key': '<x-api-key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.sipstack.com/api/v2/messages',
  params: {page: '1', limit: '50', direction: 'inbound'},
  headers: {'x-api-key': '<x-api-key>'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Returns your organization’s messages, newest first. Both inbound and outbound messages are included; platform-only unrouted rows are excluded. Requires the sms:read scope.

Supports offset paging (page/limit, with a total/totalPages count) or keyset paging — pass the next_cursor from a response back as cursor to walk large result sets without drift. In cursor mode page, total, and totalPages are null.

Authorizations

apiKeyAuth

Parameters

Query Parameters

page

integer

default: 1 >= 1

limit

integer

default: 50 >= 1 <= 200

cursor

string

Opaque keyset cursor from a previous response’s next_cursor. Ignores page when set.

direction

string

Allowed values: inbound outbound

number

string

One of your own lines — digits matched against either party.

contact

string

The external party — a contact id (UUID) for an exact match, or a phone number (≥3 digits).

from_date

string format: date-time

ISO date/datetime lower bound (inclusive) on created_at.

to_date

string format: date-time

ISO date/datetime upper bound (inclusive) on created_at.

Responses

200

Paginated message list.

application/json

object

success

boolean

data

Array<object>

A single SMS record as returned by GET /api/v2/messages.

object

string format: uuid

uuid

string format: uuid

direction

string

Allowed values: inbound outbound

status

string

to_phone_number

string

from_phone_number

string

body

string

segments

integer

media_urls

Attached MMS media URLs; null for a plain SMS. For uploaded media these are time-limited signed URLs, valid for 24 hours from the time the message is read — re-fetch the message for a fresh URL rather than storing them. Hosted URLs are returned exactly as supplied.

Array<string>

nullable

error_code

string

nullable

error_message

string

nullable

sent_at

string format: date-time

nullable

delivered_at

string format: date-time

nullable

created_at

string format: date-time

updated_at

string format: date-time

pagination

Page metadata returned by the paginated Developer API list endpoints. Per-endpoint limit defaults and caps vary (see each endpoint’s limit parameter). In keyset (cursor) mode page, total, and totalPages are null — walk pages via next_cursor instead.

object

page

integer

nullable

limit

Items per page (the default and maximum vary by endpoint).

integer

total

Total matching records across all pages (null in cursor mode).

integer

nullable

totalPages

integer

nullable

next_cursor

Pass back as cursor to fetch the next page; null on the last page.

string

nullable

Examples

page

First page of messages

{
  "success": true,
  "data": [
    {
      "id": "3a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "uuid": "3a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "direction": "outbound",
      "status": "delivered",
      "to_phone_number": "+14165550100",
      "from_phone_number": "+16135550200",
      "body": "Hi! Your appointment is confirmed for tomorrow at 2pm.",
      "segments": 1,
      "media_urls": null,
      "error_code": null,
      "error_message": null,
      "sent_at": "2026-01-15T14:30:01.000Z",
      "delivered_at": "2026-01-15T14:30:04.000Z",
      "created_at": "2026-01-15T14:30:00.000Z",
      "updated_at": "2026-01-15T14:30:04.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 143,
    "totalPages": 3
  },
  "next_cursor": "eyJpZCI6IjNhMWIyYzNkIiwidHMiOjE3NjU0MzIwMDB9"
}

400

Invalid filter or cursor.

application/json

Inline error shape used by the messaging API and management endpoints.

object

success

boolean

error

string

Example

{
  "success": false,
  "error": "Recipient phone number (to) is required"
}

401

Missing or invalid API key.

application/json

Inline error shape used by the messaging API and management endpoints.

object

success

boolean

error

string

Example

{
  "success": false,
  "error": "Recipient phone number (to) is required"
}

403

The key is missing the sms:read scope.

application/json

Inline error shape used by the messaging API and management endpoints.

object

success

boolean

error

string

Example

{
  "success": false,
  "error": "Recipient phone number (to) is required"
}

500

Internal error.

application/json

Inline error shape used by the messaging API and management endpoints.

object

success

boolean

error

string

Example

{
  "success": false,
  "error": "Recipient phone number (to) is required"
}