Send an SMS
Sends a text from one of your numbers. Needs the sms-send scope, granted only by name (full access never includes it). Before anything is sent Gauge checks, in order: the do-not-contact list, the recipient's consent for this purpose (transactional: true is utility, otherwise marketing, which needs a recorded opt-in for SMS: consent_required otherwise), and quiet hours where the recipient is. Then it reserves the estimated cost (segments × the destination rate) against your balance and this key's daily spend cap. Any refusal sends nothing and charges nothing. On carrier acceptance the actual cost is charged and the rest released. inbox: false (the default) keeps the message out of the inbox; inbox: true threads it into the contact's SMS conversation. The response carries the encoding, segment count and the estimate. Follow delivery with sms.status_updated.
ApiKeyAuthorizationBearer <token>An API key from Developers → API keys: Authorization: Bearer gauge_live_… (or pulse_k_live_…).
Gauge-Version?stringA dated version. Default 2026-10-21.
Idempotency-Key*stringRequired on every POST. Retries with the same key replay the first response for 24 h.
1 <= length <= 255application/json- body
to*stringThe recipient, in E.164.
^\+[1-9]\d{6,14}$numberId*stringThe Gauge number to send from (GET /v2/numbers). It must be able to send SMS.
uuidtext*stringThe message. At most 10 segments.
1 <= length <= 1600transactional?booleanA transactional (utility) message: an order update, a reminder, a code. Marketing is false. Checked against the recipient's consent for that purpose; exempt from quiet hours only when your workspace allows it.
falseinbox?booleanfalse (default): the SMS is recorded and billed but does not appear in the inbox. true: it is threaded into the contact's SMS conversation like an agent reply.
falseThe SMS, accepted by the carrier (status: queued).
application/json- response
id*stringuuidstatus*stringqueued when the carrier accepted it; then sent, delivered, undelivered or failed as receipts arrive (sms.status_updated).
"queued""sent""delivered""undelivered""failed"to*stringfrom*stringnumberId*stringuuidcontactId*|uuidinbox*booleantransactional*booleanconversationId*|Set for an inbox: true send.
uuidmessageId*|Set for an inbox: true send.
uuidtext*stringencoding*stringgsm7 (160 characters per single segment) or ucs2 (70), chosen from the text.
"gsm7""ucs2"segments*integer1 <= valueestimateCents*integerThe estimate reserved before sending (segments × the rate for the destination).
0 <= valuecostCents*|What was charged, once the carrier accepted the message.
0 <= valueerror*|nullcreatedAt*stringupdatedAt*stringcurl -X POST 'https://app.gauge.chat/api/v2/sms' \ -H 'Idempotency-Key: string' \ -H 'Content-Type: application/json' \ -d '{ "to": "string", "numberId": "4960e75f-5738-4a19-bb92-2459f0660f6c", "text": "string"}'{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "status": "queued", "to": "string", "from": "string", "numberId": "4960e75f-5738-4a19-bb92-2459f0660f6c", "contactId": "b5ec5d98-4bee-4da1-ad24-dde86346cb1d", "inbox": true, "transactional": true, "conversationId": "ee6e55e8-45fe-4a3e-9bc8-4669f9fdf77a", "messageId": "8540d774-4863-4d2b-b788-4ecb19412e85", "text": "string", "encoding": "gsm7", "segments": 1, "estimateCents": 0, "costCents": 0, "error": { "code": "string", "reason": "string" }, "createdAt": "string", "updatedAt": "string"}