Send SMS message

Authorizations

bearerAuthHTTP · Bearer

Send your token in the Authorization: Bearer <token> header on every request.

Request body schema

application/json · required

Field	Type	Description
`servicePlanId`required	`string`	24-character hex service plan identifier. pattern: ^[a-fA-F0-9]{24}$
`channel`required	`string`	SMS payload contract. enum: SMS
`from`required	`string`	Sender address: a 3-8 digit short code, an E.164 phone number, or an alphanumeric sender ID (up to 11 chars, must contain a letter).
`to`required	`string`	Destination address in E.164 format.
`body`required	`string`	SMS message text. maxLength: 1600
`callbackUrl`	`string<uri>`	Optional HTTPS delivery-receipt URL. Must use https, have a valid hostname without underscores, and must not target an internal address.

Example request body

{
  "servicePlanId": "222222222222222222222222",
  "channel": "SMS",
  "from": "+15550001111",
  "to": "+15550002222",
  "body": "Your verification code is 123456",
  "callbackUrl": "https://client.example.com/sms/status"
}

Responses

Status	Description
202	Message accepted and queued for delivery to the carrier. The body is the per-message status record with status QUEUED.
400	Invalid request. Returned for malformed payloads, validation errors, a non single-message shape, or incomplete service-plan configuration.
401	Missing Bearer token, malformed Authorization header, invalid token, or service plan found but currently not active.
403	Token is valid but not authorized for account mapping, or sender authorization is denied for the provided account and service plan.
404	Service plan is not provisioned for the authenticated account.
409	Sender subscription exists but is pending approval.
422	Sender subscription status is not recognized.
413	The message record exceeds the maximum allowed size.
429	Rate limit exceeded. Retry after the indicated interval. This response is typically enforced by upstream edge or API gateway controls.
500	The message could not be queued (internal error) or, when the single message failed to enqueue, a per-message status record with status FAILED.

Example response body

202 · per-message status record

{
  "accountId": "111111111111111111111111",
  "servicePlanId": "222222222222222222222222",
  "msgId": "019ef0d9-35a5-7592-b209-1f10ece6b38f",
  "channel": "SMS",
  "direction": "MT",
  "from": "+15550001111",
  "to": "+15550002222",
  "body": "Your verification code is 123456",
  "status": "QUEUED",
  "errorCode": "000",
  "errorMessage": "No error",
  "segments": 1,
  "price": null,
  "ptf": null,
  "currency": "USD",
  "mccmnc": null,
  "country": "PR",
  "createdAt": "2026-06-20T04:20:40.982Z",
  "sentAt": null,
  "updatedAt": "2026-06-20T04:20:40.982Z"
}

Acceptance and message identifier

A 202 Accepted response means the message passed validation and was accepted for delivery. The response body is the per-message status record, and msgId is the server-generated identifier (UUID) for the message. Store msgId. The Location response header points to the read-only status resource, which you can query with GET /v1/messages/{msgId} and use to correlate later delivery receipts on your callback URL.

What happens after acceptance

On acceptance, the message starts in QUEUED. The status then progresses as downstream delivery proceeds. The price, ptf, mccmnc, and sentAt fields are null at submission time and populate as the message progresses. For later status, use the read-only status resource: GET /v1/messages/{msgId}.

If callbackUrl is provided, delivery updates are sent to that endpoint. See the Delivery receipts webhook page for the webhook contract.

Immediately after a send, status lookup can be eventually consistent: a request right after 202 may briefly return 404 MESSAGE_NOT_FOUND while the record becomes available. Retry after a short delay.

Request notes

from (sender): a 3–8 digit short code, an E.164 phone number, or an alphanumeric sender ID (up to 11 characters and containing at least one letter). Allowed sender types depend on your service plan and destination.
to (recipient): a single destination address in E.164 format (for example +15550002222).
body (content): the message text, up to 1600 characters. Encoding and route-specific limits can affect the number of billable segments; the API returns the calculated segments value when available.
callbackUrl: optional HTTPS URL for delivery receipts. It must use https, resolve to a public hostname without underscores, and must not target an internal address.

Common validation errors

Validation failures return 400 with errorCode: VALIDATION_ERROR and an errors array identifying the offending fields. Typical causes include a missing or empty body, a to value that is not valid E.164, a from value outside the allowed sender formats, a servicePlanId that is not a 24-character hex string, or a callbackUrl that is not a valid public HTTPS URL. See Error codes for the full reference.