Send SMS messages
Queue single, batch, and scheduled 10DLC messages and track delivery safely.
Every send is durable and asynchronous. Speko stores the message, compliance decision, campaign snapshot, and credit reservation before enqueueing it, then returns 202. A response of queued or accepted never means carrier delivery.
Send one message
curl -X POST https://api.speko.dev/v1/sms/messages \
-H "Authorization: Bearer $SPEKO_API_KEY" \
-H "Idempotency-Key: order-982-confirmation" \
-H "Content-Type: application/json" \
-d '{
"from_phone_number_id": "8f0e9a96-...",
"to": "+12025550123",
"text": "Acme: your order 982 is confirmed. Reply STOP to opt out.",
"recipient_timezone": "America/New_York",
"metadata": { "order_id": "982" }
}'The sender must belong to your workspace, be active and outbound-capable, show a ready messaging profile, and have an ASSIGNED approved campaign. You never provide a campaign or brand ID; Speko derives and snapshots both from the sender.
If no number in the workspace is on an approved campaign, the send returns 403 with code SMS_SENDING_NOT_APPROVED. If the workspace can send but the chosen number is not on the campaign, the send returns 409 with PHONE_NOT_SMS_READY.
Canadian numbers
A Speko-managed Canadian number sends without a 10DLC campaign. 10DLC is a US registration, and Canadian numbers cannot join a campaign. The number is ready once its messaging profile is, which happens on its own shortly after purchase. If your workspace's messaging profile was set up before Canadian sending was available, the number waits until Speko updates that profile to allow Canada; until then sends return 409 with MESSAGING_PROFILE_NOT_READY.
A Canadian number texts Canadian numbers only. A send to any other number returns 422 with code SMS_DESTINATION_NOT_SUPPORTED, and no credits are reserved. Agent auto-replies follow the same rule: a text from a US number to your Canadian number is stored in the inbox, but the agent does not answer it. To text US numbers, send from a US number on an approved campaign.
Messages from a Canadian number carry campaign_id: "ca_long_code". Record consent for Canadian recipients against that id. Canada's anti-spam law (CASL) has its own consent rules, so check that your consent records meet them.
Check whether the workspace can send
curl https://api.speko.dev/v1/sms/capabilities \
-H "Authorization: Bearer $SPEKO_API_KEY"{ "sending": { "enabled": false, "reason": "no_approved_campaign" } }sending.enabled is true once at least one live number is assigned to an approved campaign: your own business or sole proprietor campaign, a campaign Speko assigned to the workspace, or Speko's shared campaign where it is enabled for you. A Canadian number on the messaging profile turns it on too. reason is null when sending is enabled, and otherwise one of:
reason | Meaning |
|---|---|
no_approved_campaign | No number is on an approved campaign yet. Register and assign a number. |
campaign_billing_suspended | Your own campaign's monthly fee is unpaid past its grace period. Add credits to resume. |
The same object is features.smsSending on GET /v1/organization. The older features.smsMessaging mirrors smsSending.enabled.
Idempotency-Key is required. Reusing the key with the same JSON returns the original message. Reusing it with different JSON returns 409 IDEMPOTENCY_CONFLICT. A missing key, or one longer than 128 characters, returns 422 IDEMPOTENCY_CONFLICT. Persist the key before calling Speko and reuse it after client timeouts.
Schedule and quiet hours
Add an RFC 3339 send_at up to 90 days ahead. Proactive traffic is allowed from 08:00 through 21:00 recipient local time. Speko resolves timezone from the active consent, conversation, request, or organization default and shifts work to the next valid boundary when needed.
The response exposes both requested_send_at and effective_send_at. A proactive send with no resolvable IANA timezone fails with RECIPIENT_TIMEZONE_REQUIRED. Consent, suppression, readiness, credits, and quiet hours are rechecked when scheduled work becomes due.
Send a batch
POST /v1/sms/batches accepts one sender and 1–1,000 recipient rows:
{
"from_phone_number_id": "8f0e9a96-...",
"send_at": "2026-09-03T14:00:00Z",
"recipients": [
{
"to": "+12025550123",
"text": "Acme: your appointment is tomorrow at 10 AM.",
"recipient_timezone": "America/New_York",
"metadata": { "appointment_id": "apt_1" }
}
]
}Use a batch-level Idempotency-Key. Sender or envelope errors reject the whole request. Recipient-specific issues create rejected message rows while valid rows continue. Batch traffic is always proactive and cannot use the 24-hour conversational reply exception.
Read progress at GET /v1/sms/batches/{batch_id} and row results at GET /v1/sms/batches/{batch_id}/messages. Cancel remaining queued/scheduled rows with POST /v1/sms/batches/{batch_id}/cancel.
Status lifecycle
| Status | Meaning |
|---|---|
queued / scheduled | Durable and waiting for processing or its effective time |
submitting | Provider submission has begun; no longer cancelable |
accepted / sent | Accepted by Telnyx or handed to the carrier |
delivered | Authoritative delivery receipt received |
delivery_failed | Carrier reported a terminal delivery failure; error holds the carrier's code |
delivery_unconfirmed | Carrier accepted the message but never confirmed delivery; a later receipt can still move it to delivered or delivery_failed |
rejected | Rejected locally before submission |
submission_unknown | The request may have reached Telnyx; Speko will not blindly retry |
canceled | Canceled before provider submission |
received | Inbound message |
Poll GET /v1/sms/messages/{message_id}, subscribe to signed webhooks, or use GET /v1/sms/stream for a live dashboard. Delivery events are idempotent and later authoritative receipts can repair out-of-order state.
Limits
- SMS only; MMS is not accepted.
- Recipients must be E.164.
- Text is limited to 1,600 characters.
- Metadata allows 50 keys and 8 KB serialized.
- Only
queuedandscheduledmessages can be canceled.