---
title: "Send Customized SMS"
description: "Send personalized SMS messages using contact data and placeholders."
---

# Send Customized SMS

Customized SMS lets you merge recipient data into the final message before it is sent.

## Endpoints

```http
POST /api/v2/messages/sms/bulk
```

Use the standard bulk SMS endpoint with `custom_data` to render one message per recipient.

## Authorization

Pass your API token using standard HTTP Bearer authentication:

```http
Authorization: Bearer bk_live_8n6JQv3K1h9Lp0Md
Content-Type: application/json
```

<Info>
For backward compatibility, legacy body credentials (`apikey` and `apisecret`) or legacy headers (`X-API-Key` & `X-API-Secret`) remain supported.
</Info>

## Supported placeholder formats

Bulkit supports both:

- `{{first_name}}`
- `__FIRST_NAME__`

Common aliases like `Number`, `Phone`, and `Mobile` resolve to the recipient number.

## Example template

```text
Hello {{first_name}}, your account __ACCOUNT__ is due on {{due_date}}.
```

## Example cURL Request

```bash
curl -X POST "https://api.bulkitsms.com/api/v2/messages/sms/bulk" \
  -H "Authorization: Bearer bk_live_8n6JQv3K1h9Lp0Md" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "BULK_IT",
    "mobiles": ["254700000001", "254733000002"],
    "message": "Hello {{first_name}}, your balance is {{balance}}.",
    "custom_data": [
      {
        "Mobile": "254700000001",
        "first_name": "Amina",
        "balance": "KES 1,240"
      },
      {
        "Mobile": "254733000002",
        "first_name": "Brian",
        "balance": "KES 560"
      }
    ]
  }'
```

## How it works

- the backend matches each `custom_data` row to a recipient by mobile number
- placeholders are rendered before the message is stored and queued
- outbox and history show the final rendered message, not the raw template

## Notes

- make sure each custom data row contains the correct recipient number
- use consistent field names across all rows
- if a placeholder value is missing, the unresolved token may remain in the message

## Error response

```json
{
  "status": "error",
  "message": "Invalid message"
}
```