> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Send SMS

> POST /marketplace/messaging/send-sms — transactional SMS with optional template or inline body — through the gu1 messaging API for customer communications.

Sends a single transactional SMS for the authenticated organization. Requires the **SMS** marketplace integration and a configured messaging provider. See [Messaging overview](/en/api-reference/messaging/overview) for prerequisites and billing.

## Endpoint

```http theme={null}
POST https://api.gu1.ai/marketplace/messaging/send-sms
```

## Headers

```http theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
X-Organization-ID: <uuid>   # optional; multi-org session users
```

## Request body

### Common

<ParamField body="to" type="string" required>
  Destination phone number (E.164 recommended, e.g. `+5491112345678`). Length limits apply (validated server-side).
</ParamField>

<ParamField body="senderIndex" type="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.
</ParamField>

<ParamField body="templateParams" type="object">
  Replacements for `{{placeholders}}` in the template or inline `body`. Default `{}`.
</ParamField>

### Mode A — Stored template

<ParamField body="templateId" type="string (UUID)" required>
  Message template with channel **sms**.
</ParamField>

Do **not** send `body` in this mode.

### Mode B — Inline body

Do **not** send `templateId`.

<ParamField body="body" type="string" required>
  SMS text. Max \~4,000 characters. May include `{{variables}}` replaced via `templateParams`.
</ParamField>

## Example — template

```bash theme={null}
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

```bash theme={null}
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

```json theme={null}
{
  "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`.