Six endpoints.
Every field documented.

Conventions

Requests accept application/json or form-encoded bodies; responses are always JSON. Timestamps are ISO 8601 in UTC. Money is a decimal string in USD with four places. Phone numbers are E.164 with the leading plus. Identifiers are prefixed: msg_, bat_, evt_, cmp_. Every response carries X-Request-Id; quote it when you write to support.

Authentication

Authorization: Bearer sk_live_9f2c...a71e

Scopes: send (create messages), read (everything GET). A key may carry an IP allowlist; requests from other addresses receive 401 unauthorized. Test keys (sk_test_) behave identically but never send and never bill.

Idempotency

Any POST accepts Idempotency-Key, a string of up to 128 characters chosen by you. Same key and same payload within 24 hours: the original response is returned, with the header Idempotent-Replayed: true. Same key, different payload: 409 idempotency_conflict.

Create a message

POST/v1/messages

POST /v1/messages
Authorization: Bearer sk_live_...
Idempotency-Key: order-4821-ship
Content-Type: application/json

{
  "to": "+14155550142",
  "from": "METEOR",
  "text": "Your order #4821 has shipped. Track it: smsmtr.io/t/8fK2",
  "campaign": "shipping",
  "reference": "order-4821"
}

{
  "id": "msg_9Kd2fQ",
  "status": "queued",
  "to": "+14155550142",
  "from": "METEOR",
  "text": "Your order #4821 has shipped. Track it: smsmtr.io/t/8fK2",
  "segments": 1,
  "encoding": "gsm7",
  "price": "0.0084",
  "currency": "USD",
  "country": "us",
  "campaign": "shipping",
  "reference": "order-4821",
  "created_at": "2026-09-21T11:42:07Z",
  "sent_at": null,
  "delivered_at": null,
  "carrier_code": null
}

Create a batch

POST/v1/messages/batch

Up to 1,000 messages per API request, each with its own to, text and optional from, reference. Top-level from, campaign, send_at, window and pace apply to every message that does not override them. The whole batch is accepted or rejected atomically on syntax; individual messages can still be rejected for destination or content and are listed with their reason.

{
  "batch_id": "bat_3Hq9Zr",
  "accepted": 2, "rejected": 1,
  "total_price": "0.0214", "currency": "USD",
  "messages": [
    { "id": "msg_9Kd2fQ", "to": "+14155550142", "status": "queued", "price": "0.0084" },
    { "id": "msg_9Kd2fR", "to": "+447700900123", "status": "queued", "price": "0.0130" },
    { "to": "+99912345", "status": "rejected", "error": { "code": "unsupported_destination" } }
  ]
}

Scheduling parameters

Three ways to time a send, on single messages and batches. They combine: a window with a pace is the usual setting for marketing.

Retrieve a message

GET/v1/messages/{id}

Returns the Message object with its current status, timestamps, price and carrier code when a failure has one.

List messages

GET/v1/messages

{ "data": [ { "id": "msg_9Kd2fQ", "status": "delivered", "...": "..." } ],
  "next_cursor": "eyJpZCI6Im1zZ185S2QyZlEifQ", "has_more": true }

Rates

GET/v1/ratesandGET/v1/rates/{iso}

The public rate card, identical to the pricing page. Each entry has the destination, dial code, price per segment, sender-ID rule and quiet-hours window. Cacheable for an hour; rates change at most once a day. No key required.

{ "country": "gb", "name": "United Kingdom", "dial": "44",
  "price": "0.0130", "currency": "USD",
  "sender": "alphanumeric", "quiet_hours": { "start": "08:00", "end": "21:00" },
  "updated_at": "2026-09-21" }

Balance

GET/v1/balance

{ "balance": "1240.60", "currency": "USD", "pending": "0.00",
  "low_threshold": "100.00", "updated_at": "2026-09-21T11:40:00Z" }

The Message object

Statuses

1. queuedAccepted and priced, waiting for a route slot.
2. sentHanded to the carrier. Billing point.
3. deliveredHandset confirmed receipt. Final.
4. failedCarrier could not deliver; carrier_code set. Final.
5. expiredValidity elapsed without delivery. Final.
6. rejectedRefused before sending. Never billed. Final.

Errors

{ "error": { "code": "insufficient_balance", "message": "Balance 0.42 USD is below the message price 0.85 USD", "field": null } }

Rate limits

50 requests per second per key, measured on a sliding window. Batch requests count as one request each. Responses include X-RateLimit-Limit, X-RateLimit-Remaining and, on 429, Retry-After in seconds.

Changelog

• 2026-09 window.quiet_hours accepts bypass for transactional traffic.
• 2026-07 Batch responses list rejected items with their error instead of failing the whole batch.
• 2026-06 reference field echoed in webhooks.
• 2026-04 GET /v1/rates/{iso} added.