Template based messaging

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.

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

csv

Each CSV line has a mobile number followed by a list of field values that are used to customise a text message. The text parameter value acts as a template with placeholders inserted into the text which are replaced by these field values when the message is sent

The mobile number must be the first value in the CSV field.

 

csvtemplate

This allows you to specify message parameters per message.

   

delimiter

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 csv option.

, (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 example below. If you wish to customise 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>