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

# SMS campaigns

> Send one message to whole contact lists and tags, personalised for each person, now or later.

A campaign is built from **contact lists**, **contact tags** and/or extra **numbers**. Repeated numbers are removed, and people who opted out are left out when it's sent. Sending happens in the background, paced by Messaly.

**1. Create the campaign**

```bash theme={null}
curl -X POST https://app.telaven.com/api/v1/sms/campaigns \
  -H "Authorization: Bearer $TELAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "November offer",
    "message": "Hi {first_name}, 20% off until Friday.",
    "contactListIds": ["c51e…"],
    "tags": ["vip"]
  }'
```

It's saved as a `draft`. The response gives its `id` and `totalRecipients`.

**2. Send it, or schedule it**

```bash theme={null}
# Send now (202 Accepted)
curl -X POST https://app.telaven.com/api/v1/sms/campaigns/6f1c…/send \
  -H "Authorization: Bearer $TELAVEN_API_KEY"

# Or schedule it
curl -X PATCH https://app.telaven.com/api/v1/sms/campaigns/6f1c…/schedule \
  -H "Authorization: Bearer $TELAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scheduledAt": "2026-11-15T08:00:00+03:00" }'
```

If your wallet doesn't cover the campaign, sending returns `402 INSUFFICIENT_BALANCE`. If everyone in it has opted out, it returns `400 ALL_OPTED_OUT`.

**3. Follow its progress**

Call [`GET /sms/campaigns/{id}`](https://docs.telaven.com/api-reference/sms-campaigns/get-campaign) for totals and delivery rate, and
[`GET /sms/campaigns/{id}/recipients`](https://docs.telaven.com/api-reference/sms-campaigns/campaign-recipients) for each person. Or wait for the `campaign.completed` [webhook](https://docs.telaven.com/guides/webhooks.md).

## Personalisation

Use these placeholders in `message`. Each one is filled in from the contact:

| Placeholder | Becomes |
| - | - |
| `{first_name}` | The contact's first name |
| `{name}` | The contact's full name |
| `{phone}` | The contact's phone number |

## Campaign status

| Status | Meaning |
| - | - |
| `draft` | Created, not sent. You can still edit it with `PATCH /sms/campaigns/{id}`. |
| `scheduled` | Will send at `scheduledAt` (stored in UTC+3). |
| `processing` | Sending now. |
| `completed` | Finished. |
| `failed` | Stopped; see the campaign for details. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.