# SMS

Send and receive SMS over the REST API. Outbound (MT) messages are submitted
with a Bearer token and your `servicePlanId`; inbound (MO) messages and delivery
receipts are delivered to your callback URLs.

## Get started

1. **Authenticate.** Send your Bearer token in the `Authorization: Bearer <token>` header on every request. See [Authentication](/docs/api/authentication).
2. **Identify your account.** Include your `servicePlanId` so the platform can
authorize and route the message.
3. **Send a message.** Submit a single outbound SMS and receive an immediate
acceptance with a per-message status record. See
[Send SMS message](/docs/api/channels/sms/outbound-sms/send-sms-message).
4. **Track delivery.** Poll the message status, search your logs, or receive
delivery receipts (DLR) on your callback URL.


## Outbound SMS

Submit outbound (MT) SMS messages for delivery. Each request returns an
immediate acceptance with a per-message status record.

[Send SMS message →](/docs/api/channels/sms/outbound-sms/send-sms-message)

## Inbound SMS

Receive inbound (MO) SMS messages. The platform POSTs each inbound message to
the inbound callback URL configured on your account.

[Receive inbound SMS →](/docs/api/channels/sms/inbound-sms/receive-message)

## Logs / Status Reports

List and filter your SMS delivery records with cursor-based pagination.

[Messages list →](/docs/api/channels/sms/message-logs/list-message-logs)

Receive delivery receipts (DLR) via webhook callback or query delivery state
through the API.

[Delivery Receipts (DLR) →](/docs/api/channels/sms/status-reports/delivery-receipts)

## API Reference

The pages above are the primary, polished SMS documentation. For the raw
technical contract — backed by the SMS OpenAPI description — use the SMS API
reference for request/response schemas, examples, and status semantics for
`POST /v1/sendsms`, `GET /v1/messages/sms` (list/search), and
`GET /v1/messages/sms/{msgId}`.

Interactive Replay/Try it is enabled on the API reference for mock contract
testing. Use your own credentials and handle tokens as secrets.

When testing from Try it:

- Replay/Try it uses the **Mock server**.
- Use a placeholder token for schema/contract validation.
- For real delivery, call `https://api-sms.smscpr.com/v1/sendsms` outside
Replay with a real active token.


The status and delivery-receipt responses use the same `DeliveryReceipt` object.
Fields such as `price`, `ptf`, `mccmnc`, and `sentAt` may be `null` until the
message reaches a final delivered state, and `QUEUED` is an accepted state that
may persist while backend-to-carrier delivery progression is connected. You can
use whichever fields are relevant to your reporting, billing, or support systems.

[SMS API Reference →](/openapi/sms)

## Callbacks

Configure HTTPS endpoints to receive asynchronous events: delivery receipts
(DLR) for outbound messages and inbound (MO) message notifications.

## Mock / sandbox examples

Test your integration locally without calling production. Stand up a small local
HTTP server for the receiver examples, and point the Send SMS request at your own
local mock while developing. These examples use local URLs only — there is no
hosted public sandbox endpoint.

**Simulate a Send SMS API request** (point the base URL at your local mock):

```bash
curl -X POST "http://localhost:3000/messages/sms" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "servicePlanId": "222222222222222222222222",
    "channel": "SMS",
    "from": "+15550001111",
    "to": "+15550002222",
    "body": "Your verification code is 123456",
    "callbackUrl": "https://client.example.com/sms/status"
  }'
```

**Receive an inbound SMS (MO) webhook locally** (the platform POSTs this shape to
your inbound callback URL):

```bash
curl -X POST "http://localhost:3000/sms/inbound" \
  -H "Content-Type: application/json" \
  -d '{
    "servicePlanId": "222222222222222222222222",
    "msgId": "019f0000-aaaa-bbbb-cccc-000000000001",
    "channel": "SMS",
    "direction": "MO",
    "from": "+15550002222",
    "to": "+15550001111",
    "keyword": "Need",
    "body": "Need status update for order 12345",
    "receivedAt": "2026-06-22T05:10:03.120Z"
  }'
```

**Receive a delivery receipt (DLR) webhook locally** (the platform POSTs this
shape to your DLR callback URL):

```bash
curl -X POST "http://localhost:3000/sms/status" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "111111111111111111111111",
    "servicePlanId": "222222222222222222222222",
    "msgId": "019ee2da-e515-7322-805f-1ac6ce82f20f",
    "channel": "SMS",
    "direction": "MT",
    "from": "+15550001111",
    "to": "+15550002222",
    "body": "Your verification code is 123456",
    "status": "DELIVERED",
    "errorCode": "000",
    "errorMessage": "No error"
  }'
```

The Send SMS request follows the confirmed API contract (`servicePlanId`,
`channel`, `from`, `to`, `body`); the webhook payloads mirror the documented
inbound and delivery-receipt shapes.

## Developer resources

- [Authentication](/docs/api/authentication) — Bearer token usage.
- [Rate limits](/docs/api/rate-limits) — throttling and `429` behavior.
- [Error codes](/docs/api/error-codes) — HTTP status code reference.