SMS Messages

Send, retrieve, and track SMS messages through the Txtly API. SMS is delivered via AWS SNS and supports both transactional and promotional message types.

Send SMS

POST

/v1/sms

Send a single SMS message. Supports idempotency via the Idempotency-Key header.

Parameters

Parameter	Type	Description
`to`required	`string`	Recipient phone number in E.164 format (e.g. +61412345678)
`body`required	`string`	Message text (max 1600 characters). Long messages are automatically split into segments.
`senderId`required	`string (UUID)`	ID of the SMS sender identity to send from. Must be active.
`messageType`	`string`	Either "transactional" or "promotional". Defaults to the sender's default message type.

Headers

Parameter	Type	Description
`Idempotency-Key`	`string`	Unique key to prevent duplicate sends. If a message with the same key exists, the existing message is returned.

Example Request

curl -X POST https://api.txtly.com.au/v1/sms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-123" \
  -d '{
    "to": "+61412345678",
    "body": "Your verification code is 123456",
    "senderId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "messageType": "transactional"
  }'

Example Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "to": "+61412345678",
  "body": "Your verification code is 123456",
  "messageType": "transactional",
  "status": "sent",
  "segments": 1,
  "zone": "Zone2",
  "bundleCovered": true,
  "billableCents": 0,
  "providerMessageId": "sns-msg-abc123",
  "senderId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "senderName": "Acme Alerts",
  "createdAt": "2026-04-12T10:30:00Z",
  "sentAt": "2026-04-12T10:30:01Z"
}

zone: pricing zone the send was billed against (Zone1/Zone2/Zone3). bundleCovered: true when the send was paid for from your monthly SMS credit; false when it overflowed to metered overage billing. billableCents: amount reported to Stripe metered billing for this send (0 when bundle-covered, otherwise the zone retail rate).

Error: Unsupported destination

Sends to country codes outside the rate card return 422 Unprocessable Entity before any provider call:

{
  "error": "UNSUPPORTED_DESTINATION_COUNTRY",
  "message": "SMS sends to this destination country are not currently supported. Contact support to request coverage."
}

Country resolution is based on the E.164 prefix. See pricing zones for the supported list.

Send Batch SMS

POST

/v1/sms/batch

Send up to 100 SMS messages in a single request. Individual message failures do not abort the batch.

Parameters

Parameter	Type	Description
`messages`required	`object[]`	Array of SMS message objects (max 100, or your plan's batch limit). Each object has the same fields as the single send endpoint.

Example Request

curl -X POST https://api.txtly.com.au/v1/sms/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "to": "+61412345678",
        "body": "Your order has shipped!",
        "senderId": "d290f1ee-6c54-4b01-90e6-d701748f0851"
      },
      {
        "to": "+61498765432",
        "body": "Your appointment is confirmed for tomorrow at 2pm",
        "senderId": "d290f1ee-6c54-4b01-90e6-d701748f0851"
      }
    ]
  }'

Example Response

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "to": "+61412345678",
      "status": "sent",
      "segments": 1,
      "senderName": "Acme Alerts"
    },
    {
      "id": "e5f6a7b8-...",
      "to": "+61498765432",
      "status": "sent",
      "segments": 1,
      "senderName": "Acme Alerts"
    }
  ]
}

List SMS Messages

GET

/v1/sms

Retrieve a paginated list of SMS messages with optional filtering.

Query Parameters

Parameter	Type	Description
`limit`	`integer`	Number of messages to return (default 25, max 100)
`cursor`	`string`	Cursor for pagination (from previous response)
`status`	`string`	Filter by status: accepted, queued, sent, delivered, failed, undelivered
`senderId`	`string`	Filter by sender identity ID
`search`	`string`	Search by phone number or message body text

Get SMS Message

GET

/v1/sms/{id}

Retrieve a single SMS message by ID.

Path Parameters

Parameter	Type	Description
`id`required	`string (UUID)`	SMS message ID

Get SMS Events

GET

/v1/sms/{id}/events

Retrieve delivery events for a specific SMS message.

Path Parameters

Parameter	Type	Description
`id`required	`string (UUID)`	SMS message ID

Example Response

{
  "data": [
    {
      "id": "evt-001",
      "type": "sent",
      "createdAt": "2026-04-12T10:30:01Z"
    },
    {
      "id": "evt-002",
      "type": "delivered",
      "createdAt": "2026-04-12T10:30:05Z"
    }
  ]
}

Message Segments

Long SMS messages are split into segments. The number of segments depends on the character encoding:

Encoding	Chars per segment	When used
GSM-7	`160`	Standard ASCII characters only
UCS-2	`70`	Messages containing Unicode characters (emoji, accented chars, etc.)

SMS Event Types

SMS messages generate events throughout their delivery lifecycle:

acceptedMessage accepted by the API
queuedMessage queued for delivery with the carrier
sentMessage sent to the carrier network
deliveredMessage delivered to the recipient's device
failedMessage failed to send (carrier rejection or network error)
undeliveredMessage was sent but could not be delivered to the recipient

SMS Rate Limits

SMS sending is subject to daily message limits and spend caps per team:

Plan	Daily limit	Batch size	Daily spend cap
Free	0 (not included)	—	—
Pro	10,000	100	$100.00
Scale	100,000	100	$1,000.00
Enterprise	500,000	100	$10,000.00

When either limit is exceeded, the API returns a 429 response. Per-team overrides can be configured by contacting support.

Pricing zones

Each supported country is assigned to one of three pricing zones. The zone determines the customer-facing retail rate per send. The destination country is resolved from the recipient's E.164 prefix when the send is accepted.

Zone	Retail (AUD)	Countries
Zone 1	`$0.02`	United States, Canada
Zone 2	`$0.08`	United Kingdom, Australia, New Zealand, Ireland, Netherlands, Spain, Italy, Germany, France, Belgium, Austria, Switzerland, Denmark, Sweden, Norway, Finland, Japan, Singapore
Zone 3	`$0.25`	Mexico, South Africa, Malaysia, Philippines, Brazil

Sends to countries outside this list return 422 UNSUPPORTED_DESTINATION_COUNTRY. Each paid plan includes a monthly SMS credit (Pro $2.00, Scale $20.00, Enterprise $80.00) that's debited at the destination zone rate. Once the credit is exhausted, additional sends are billed via Stripe Billing Meters at the same per-zone rate.