Skip to main content
POST
/
marketplace
/
messaging
/
send-sms
Send SMS
curl --request POST \
  --url http://api.gu1.ai/marketplace/messaging/send-sms \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "to": "<string>",
  "senderIndex": 123,
  "templateParams": {},
  "templateId": {},
  "body": "<string>"
}
'
Sends a single transactional SMS for the authenticated organization. Requires the SMS marketplace integration and a configured messaging provider. See Messaging overview for prerequisites and billing.

​
Endpoint

POST https://api.gu1.ai/marketplace/messaging/send-sms

​
Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
X-Organization-ID: <uuid>   # optional; multi-org session users

​
Request body

​
Common

​
to
string
required
Destination phone number (E.164 recommended, e.g. +5491112345678). Length limits apply (validated server-side).
​
senderIndex
integer
Optional index for the org’s Twilio SMS sender list in integration config (-1 or omit for platform default behavior, depending on provider). Same semantics as other SMS features in the app.
​
templateParams
object
Replacements for {{placeholders}} in the template or inline body. Default {}.

​
Mode A — Stored template

​
templateId
string (UUID)
required
Message template with channel sms.
Do not send body in this mode.

​
Mode B — Inline body

Do not send templateId.
​
body
string
required
SMS text. Max ~4,000 characters. May include {{variables}} replaced via templateParams.

​
Example — template

curl -X POST https://api.gu1.ai/marketplace/messaging/send-sms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5491112345678",
    "templateId": "550e8400-e29b-41d4-a716-446655440000",
    "templateParams": { "token": "482910" }
  }'

​
Example — inline with placeholders

curl -X POST https://api.gu1.ai/marketplace/messaging/send-sms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5491112345678",
    "body": "Your code is {{token}}",
    "templateParams": { "token": "482910" }
  }'

​
Success response

{
  "success": true,
  "messageId": "provider-message-id"
}

​
Common errors (400)

  • SMS integration not active or provider not configured
  • Insufficient balance / no pack execution when the integration has a cost
  • templateId and body both sent
  • Template not found or channel is not sms
  • Body empty after rendering
Errors are in English in the error field when success is false.