---
title: "List SMS"
method: GET
path: "/v2/sms"
tags: ["SMS"]
---

# List SMS

`GET /v2/sms`

Retrieves a list of SMS messages. You can limit the number of messages returned and filter by properties listed in the parameters section.

## Query parameters

- `query` ListSMSRequest
  - `limit` string — Limit the number of SMS. Defaults to 100 for JSON.
  - `page` string — Page number in combination with limit. Defaults to 1 for JSON.
  - `start_date` string, string — Start date for SMS created, in RFC3339 format.
  - `end_date` string, string — End date for SMS created date, in RFC3339 format.
  - `recipient` string — Recipient filter.
  - `sender` string — Sender filter.
  - `message_ref` string — Message reference filter.
  - `status` 'PENDING' | 'SENT' | 'FAILED' | 'DELIVERED' | 'ACCEPTED' | 'SOFT_BOUNCE' | 'HARD_BOUNCE' | 'OTHER' | 'REJECTED' | 'PENDING_APPROVAL' | 'SUBMITTED' | 'UNDELIVERABLE' | 'READ', nullable — Message status. - PENDING: Queued for processing. - SENT: Submitted to the provider. - FAILED: Failed because of an error from the provider, a carrier, or the handset. - DELIVERED: Delivered to handset. - ACCEPTED: Accepted by the provider and delivery might have been attempted (but is not confirmed). - SOFT_BOUNCE: Undeliverable due to handset being switched off, out of range or other temporary deliverability issue. - HARD_BOUNCE: Handset was disconnected. - OTHER: Any other DLR status from the provider. - REJECTED: Message pending approval was rejected by the Kudosity support team. - PENDING_APPROVAL: Message is pending approval by the Kudosity support team. - SUBMITTED: Message is submitted to the provider. - UNDELIVERABLE: Message is undeliverable. - READ: Message is read by the recipient.
  - `format` 'JSON' | 'CSV', nullable — Response format
  - `recipient_countries` string[] — ISO 3166 country codes. https://www.iso.org/iso-3166-country-codes.html
  - `direction` 'OUT' | 'IN', nullable — Message direction. - OUT: Sent to the provider. - IN: Sent from the provider.
  - `order_by` OrderByField[] — Sort order. Default is CREATED_AT_ASC.

## Response `200`

A list of SMS messages

- ListSMSResponse — List of SMS messages.
  - `smses` SMSResponse[], required
    - `id` string, required — Unique identifier for the SMS message.
    - `recipient` string, required — The destination number for delivery.
    - `recipient_country` string, required — Recipient country code.
    - `sender` string, required — The sender number.
    - `sender_country` string, required — Sender country code.
    - `message_ref` string, required — Reference supplied by your system.
    - `message` string, required — Body text of the SMS message.
    - `status` string, required — Status of the message.
    - `sms_count` string, required — Number of SMS parts the message was split into.
    - `is_gsm` boolean, required — Whether the message uses GSM encoding.
    - `is_sandbox` boolean, required — Deprecated. Will be removed in a future version.
    - `routed_via` string, required — The route used to send the message.
    - `track_links` boolean, required — Whether link tracking is enabled.
    - `direction` string, required — Direction of the message (IN/OUT).
    - `created_at` string, required — Timestamp when the SMS was created.
    - `updated_at` string, required — Timestamp when the SMS was last updated.
  - `total_records` string, required
  - `total_segments` string, required

---

[API](https://skmtc.net/kudosity/apis/transmit-message-api.md) · [All operations](https://skmtc.net/kudosity/apis/transmit-message-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kudosity/transmit-message-api/versions/bf132756e067/schema)