# Send A Campaign Based On Template

Template-based campaigns allow you to send SMS messages using a **predefined template** stored in your Mobivate account. Messages can be sent to:

* Individual recipients
* Mailing lists / contact groups
* Or a combination of both

Per-recipient metadata and language selection are supported for dynamic message rendering.

### <mark style="color:green;">`POST`</mark> `/send/template`&#x20;

#### Required Permission

```
create:TemplateSMS
```

Your API key must have this permission enabled to use this endpoint.

### How Templates Work

Templates are created and managed within the Mobivate platform. Each template can contain placeholders (for example `{{NAME}}`, `{{CITY}}`) which are populated using recipient `meta` fields at send time.

If a template supports multiple languages, the `language` field can be supplied per recipient to control which version is used.

#### Example Request

```bash
curl --location 'https://<hostname>/send/template' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
    "recipients": [
      {
        "recipient": "3392287d-7a79-4789-9ef8-7dc174836688",
        "meta": {
          "type": "mailinglist"
        }
      },
      {
        "recipient": "3379000000001",
        "reference": "f1",
        "language": "FR",
        "meta": {
          "NAME": "John",
          "CITY": "Paris"
        }
      },
      {
        "recipient": "4979000000001",
        "reference": "d1",
        "language": "DE",
        "meta": {
          "NAME": "John",
          "CITY": "Munich"
        }
      }
    ],
    "templateID": "aaaaaaa-bbbbbbbb-cccccc-ddddddd-eee"
  }'

```

Replace `YOUR_API_KEY` with your API key.

{% hint style="info" %}
All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request.
{% endhint %}

This endpoint behaves similarly to [batch messaging](/sending-sms/send-batch-sms-messages.md) but uses a predefined message template stored in your account.

#### Request Parameters

| Field            | Type                       | Required | Description                                                                                                                                                                                                   |
| ---------------- | -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| templateID       | string                     | Yes      | The unique identifier of the message template you want to use for this request.                                                                                                                               |
| recipients       | array                      | Yes      | An array of recipient objects. Each object defines a destination and optional metadata. See recipient object fields below.                                                                                    |
| shortenUrls      | boolean                    | No       | Whether URLs in the message should be automatically shortened.                                                                                                                                                |
| excludeOptouts   | boolean                    | No       | Whether opted-out recipients should be excluded from delivery.                                                                                                                                                |
| scheduleDateTime | string (ISO 8601 datetime) | No       | Schedules the message or campaign to be sent at a future date and time. The value must be provided in ISO 8601 format (e.g. `2025-03-01T14:30:00Z`). If omitted, the message or campaign is sent immediately. |

#### Recipient Object

| Field     | Type   | Required | Description                                                                                                                                                                                                  |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| recipient | string | Yes      | The destination phone number in international format.                                                                                                                                                        |
| reference | string | No       | An optional identifier for this recipient, used for tracking in delivery reports.                                                                                                                            |
| language  | string | No       | Language code (e.g. `FR`, `DE`) to select a specific language variant of the template, if the template supports multiple languages.                                                                          |
| meta      | object | No       | Key-value pairs used to populate template placeholders (e.g. `NAME`, `CITY`). For mailing list recipients, use `{ "type": "mailinglist" }` to identify the entry as a list rather than an individual number. |

#### Responses

**Authentication Error (HTTP 403)**

Returned when the API key is invalid or does not have the required permission.

**Validation Error (HTTP 400)**

Returned when required fields are missing or invalid.

**Success (HTTP 200)**

Returned when the message has been successfully accepted for delivery.

```json
{
  "success": true,
  "record": {
    "id": "8af60d9-de7f-45ce-97f1-35a91b45277",
    "type": "TemplateSMS",
    "scheduled": "2025-11-10T21:12:32.786Z",
    "recipientCount": 3
  }
}
```

A successful response confirms that the campaign has been queued. Message delivery and delivery receipts are handled asynchronously.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.mobivatebulksms.com/sending-sms/send-a-campaign-based-on-template.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.