Send Predefined SMS Template

POST /SMS/PredefinedSMS

This endpoint is used to trigger SMS sendings on the basis of pre-saved SMS trigger templates. SMS trigger templates allow you to save all the details necessary to trigger an SMS sending as a template. These templates contain SMS sending details like the Sender name, the SMS content and text, and unsubscribe options at the time of campaign distribution, etc.

Usage scenario for this endpoint:

This endpoint is used to trigger SMSs on the basis of details pre-saved as SMS trigger templates – no need to pass the details individually.

Method Details
HTTP Method POST
Content type Application/json
Requires authentication? YES
Rate limited? YES
Headers User-Agent
Module SMS
End Point

https://apisms.mainbrainer.com/sms/predefinedsms

Required Parameters Usage Description
Access Token or API Key Authorization: Bearer {token} header Pass the API key in the request header for request authentication.Read more about our authentication process.
ListID listId (uuid) eg: "3fa85f64-5717-4562-b3fc-2c963f66afa6 Each contact list in the MainBrainer CRM is assigned a unique List ID that acts as a Unique identifier for the particular list. In case you wish to send the SMS to contacts of a particular list, specify the list ID of the desired list using the parameter listId.
Template ID Used in the request body and typically looks like this - TSMS-896 It is the unique identifier for a trigger template created in your MainBrainer account. The SMS sending details are fetched as per the details saved under this specified template ID.
Recipient Used in the request body In case you would like to send the SMS to multiple recipients and wish to specify the recipients manually, use the parameter recipients to pass the mobile numbers of the intended recipients as an array.
Also, ensure that you prefix the country code to the mobile number. For example, when sending messages to a mobile number in Norway, the to parameter value should look like – 4793454496, where 47 is the country code for Norway, and 93454496 is the intended recipient mobile number.
Personalization Substitution Tags tagName = string, tagValue = string These tags help you insert dynamic data at the time of SMS sending. In order to substitute the data at the time of the sending, follow the pattern "substitution_tag":"value” to substitute for the key/value pairs.

-- In case you use the parameter recipients to identify the SMS recipients, the substitutions will work as specified.
-- In case you use the parameter listID to identify the recipients, the data will get substituted on the basis of the information stored in the MainBrainer CRM for the recipient mobile number.
-- In case you use both the parameters listID and recipients to identify the SMS recipients, and the information passed under recipients is not in conformity with the information stored in the CRM list, data will get substituted on the basis of information passed under the parameter recipients.
-- In case you use the parameter ListID to identify multiple Lists, and a contact exists in both the lists with different information, data will get substituted with information from the most recently updated contact.
ScheduledDate-time RFC3339 format (Y-m-d\TH:i:sP) Pass the scheduled date and time of the message in RFC3339 format (Y-m-d\TH:i:sP). The date and time passed in this parameter will be converted as per the offset value specified in your account settings.
Webhook URL Delivery Status Use this parameter to specify the webhook URL where you want to receive delivery status updates for the SMS being sent. When the SMS operator returns a delivery status, the status is instantly posted to this webhook URL. Using a Webhook enables your application to receive delivery updates as they happen, in an easily parsable JSON format.
Updates will be sent for the following delivery statuses:
+ Submitted
+ Processed
+ Delivered
+ Failed
note:

In case the message body is more than 160 GSM-7 characters long (or more than unicode 70 UCS-2 characters), your messages will be split into multiple 160-character messages and concatenated, resulting in separately billed messages.Read more about SMS encoding on MainBrainer.

note

To identify the recipients for the SMS sending, it is mandatory to specify at least one of the parameters - List ID or the parameter - recipients. In case you wish to include manually added recipients in addition to contacts of a MainBrainer CRM list, pass the relevant values in both the parameters - List ID and recipients.

note

MainBrainer supports Alphanumeric Sender IDs for use as Sender Names. Kindly ensure that you use a sender name compliant with the rules and regulations of the country where you wish to send the SMSs.

note

The scheduled date and time of the message should be specified in the RFC3339 format (Y-m-d\TH:i:sP)

Predefined SMS Templates and Predefined Template ID

SMS trigger templates allow you to save all the details necessary to trigger an SMS sending as a template. Every SMS trigger template on MainBrainer.com is assigned a unique template ID. This template ID acts as the unique identifier for the template created in your MainBrainer account.

Response

In case there is a problem with the data in the request body, or if there are no properties included in the request, we'll return a 400 and 422 response along with additional details listing the cause.

Copy
Copied

This example demonstrates how to trigger an SMS sending on the basis of a predefined template ID.
post url: https://apisms.mainbrainer.com/sms/predefinedsms

{
"predefinedTemplateId": "TSMS-896",
"listId": [
  "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
"scheduleDateTime": "2021-03-18T09:37:38.633Z",
"recipients": [
  {
    "recipient": 4790812501,
    "personalizationSubstitutionTags": [
      {
        "tagName": "[firstname]",
        "tagValue": "Tom"
      }
    ]
  }
],
"webHookUrl" : "https://webhook-url.yourdomain.com"
}

Returns a 202 Accepted response with content on success.
    

Response Body

Copy
Copied
{
  "status": true,
  "message": "SMS Accepted and pushed to gateway provider",
  "data": {
    "Id": "6dd126e4-ce87-eb11-84b4-85bf40289422",
    "Priority": 1,
    "CreatedAt": "2021-03-18T09:47:07.6778117+00:00",
    "ScheduledAt": null,
    "Body": "Distribution as template",
    "Recipient": "+0"
  }
}