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.

POST /send/template

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

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.

All endpoints shown in this documentation use a sample base URL. The production API endpoint is provided by our team upon request.

This endpoint behaves similarly to batch messaging 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.

{
  "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.