Template-based messaging
Overview
With template-based messaging, you are able to send unique/personalized SMS text message to each handset with a single email. This means you are not limited to one single text message for all mobile numbers in your mail.
The examples below demonstrate various template-based formats supported by the API. It requires that you are already familiar with non-template based messaging on this API. Three new parameters are used in the examples below. These parameters are explained in detail below the examples.
Note: Template-based messaging’s format can dramatically increase the size of your email. Due to this, we suggest sending no more than 50 000 messages per mail.
Simple template messaging
Example format 1:
api_id: 1234 user:xxxxxxxxx password:xxxxxxxxxxx text:#field1# delimiter:| csv: 1234567891 |Hallo Fred. Your custom message goes here. csv: 1234567892 |Hallo Jane! In this line I can write a unique message for you. csv: 1234567893 |Hallo Bob! Your vet appointment is scheduled for Tuesday, 1pm. csv: 1234567894 |Hi John. I can send 50 000 messages per email this way. |
Example format 2:
api_id: 1234 user:xxxxxxxxx password:xxxxxxxxxxx text:Hi #field1#, your balance is #field2#, please come to the office on #field3# delimiter:| csv: 1234567891 |Fred|€ 15.50 |Mondays,Wednesdays,Fridays csv: 1234567892 |Jane|€ 299.45 |Tuesdays,Thursdays,Saturdays Note: If a comma was used as the default delimiter, then it would only have passed through ‘Mondays’ as the value of field3 for Fred and ‘Tuesdays’ for Jane. |
Template messaging parameters
Parameter |
Description |
Restricted values |
Default value |
|
Each CSV line has a mobile number followed by a list of field values that are used to customize a text message. The text parameter value acts as a template with placeholders inserted into the text that are replaced by these field values when the message is sent. |
The mobile number must be the first value in the CSV field. |
|
|
This allows you to specify message parameters per message. |
||
|
Specifies a specific character to be used to delimit values in the CSV parameter field values. Useful if certain values contain a comma. |
This allows you to change the delimiter in the |
, (comma) |
CSV line parameter (csv) explained:
csv:mobile_number[delimiter]field-value[delimiter]field-value[delimiter]field-value etc. |
Where field-value is the data to be inserted into the template, and [delimiter] is the value as determined by the delimiter
parameter.
Placeholders may be inserted within the message body itself. These will take the form of #field1# through to #fieldn#. See the example below. If you wish to customize the whole message on each CSV line, you would then use text:#field1#
Advanced template messaging
Advanced template messaging allows you to set advanced messaging parameters.
Example:
api_id: 1234 user:xxxxxxxxx password:xxxxxxxxxxx text:Hi #field1#, your balance is #field2#, please come to the office on #field3# delimiter:| csvtemplate:deliv_time|cliMsgId|validity csv: 1234567891 | 10 |id_1| 60 |Fred|€ 15.50 |Mondays,Wednesdays,Fridays csv: 1234567892 | 40 |id_2| 60 |Jane|€ 299.45 |Tuesdays,Thursdays,Saturdays |
CSV template parameter (csv template) explained:
csvtemplate:[parameter- 1 ],[ parameter- 2 ],[parameter-n] |
Example:
csvtemplate:deliv_time,cliMsgId,validity |
These values would then appear on the CSV line immediately after the mobile number. The field-values for each of the placeholders that you have inserted in your text (text parameter) are then appended to the CSV line.
Format:
csv:mobile_number [optional csvtemplate parameters] template_placeholder_parameters |
More examples
Using a single template with fields
api_id:<place API ID here> user:<place username here> password:<place password here> text:Hi #field1#, text:you have an appointment at #field2# text:at #field3# csv:<recipient 1 number>,Alice,Green Field,10h00 csv:<recipient 2 number>,Bob,Hospital Corner,11h00 |
Having different content in each message
api_id:<place API ID here> user:<place username here> password:<place password here> text:#field1# delimiter:| csv:<recipient 1 number>|Welcome Alice to your new neighbourhood. csv:<recipient 2 number>|Bob, your account needs to be paid before end of July. csv:<recipient 3 number>|Hi Carl, your new card is ready to be collected. csv:<recipient 4 number>|David your car has finished being serviced, and is ready to be collected. |
Specifying message parameters for each message
api_id:<place API ID here> user:<place username here> password:<place password here> text:#field1# delimiter:| csvtemplate:cliMsgId|validity csv:<recipient 1 number>|welcome_alice| 120 |Welcome Alice to your new neighbourhood. csv:<recipient 2 number>|bob_account_over_due| 240 |Bob, your account needs to be paid before end of July. csv:<recipient 3 number>|carl_new_bank_card| 90 |Hi Carl, your new card is ready to be collected. csv:<recipient 4 number>|david_car_service| 600 |David your car has finished being serviced, and is ready to be collected. |
Example API response email for one recipient
ID: fdb82af8e77b6b45082fee80212c180d |
Example API response email for many recipients
ID: fdb82af8e77b6b45082fee80212c180d To: <Recipient 1 > ID: 3132a36d29f618fb59726eaf2d398d96 To: <Recipient 2 > ID: ff4ecf273fcb1fe18f0b7be2789b887a To: <Recipient 3 > |
Submit a Comment
Other Resources
Ask the Community
Visit Stack Overflow to join our community of developers and find the answer you need
Contact Support
Contact our support team and one of our agents will be in touch with you to answer any questions you have