Sign in
Messages

Send an SMS through one of the caller's own eSIMs

Sends an outbound SMS through one of the caller's own eSIMs, addressed by esimId. Returns 404 if the eSIM doesn't exist or isn't owned by the caller. Returns 409 when the eSIM isn't in a state that can send (see reason). May be disabled for this deployment (403 send_disabled), and is subject to a per-owner daily cap and a burst rate limit (429).

Idempotent via clientRequestId: replaying the same key with the same payload returns the original send; the same key with a different payload returns 409 idempotency_conflict. The message is queued and sent asynchronously — this call returns 202 immediately.

post/numbers/messages

Request body

esimIdstring uuid required

The eSIM this send goes out through — resolves the device/subscription; a foreign or nonexistent id is a 404

tostring required

Recipient phone number — normalized to E.164 (spaces/dashes/dots stripped); rejected with 400 if it doesn't validate as E.164 afterward.

bodystring required

SMS body text (max 320 chars — smaller than the admin tier's cap; see the schema's own doc comment for why)

clientRequestIdstring

Client-supplied idempotency key, scoped to (owner, esimId, key). Replaying the same key + identical payload returns the original send; the same key with a DIFFERENT payload is a 409 conflict.

deliveryReportboolean

Wait for physedge to confirm carrier delivery before completing the send (adds executor-side latency, never on this request — sends are always async/202). Defaults to false for the public tier (opt-in, unlike the admin tier's default-true).

Example request

{
  "to": "+15551230001"
}

Response

Outbound message queued

Changes