API SMS Cookbook

Objective

Find out how to use the various combinations available with the API for the OVHcloud SMS platform.

On-the-fly SMS sending

On-the-fly SMS sending corresponds to a web service call to send SMS messages regularly, one by one. For each SMS to send, we make a POST web service call to the following method:

ServiceName corresponds to your SMS account. You can retrieve it either in your Control Panel, or by making a GET call to the following method:

Here is an example: /sms/sms-XXXXXX-1/jobs

Mandatory parameters:

• ServiceName
• Message (your message; be careful to take its length into account, as well as the addition of the STOP, the coding and the special characters, which can consume more SMS credit)

Recipients:

• Receivers (list of numbers; for on-the-fly SMS messages, this is the recommended parameter with a single number)
• receiversDocumentUrl (URL pointing to a CSV file containing the recipients' numbers)
• receiversSlotId (ID pointing to a pre-loaded CSV file)

Sender

• sender (selection of the sender name so that you are immediately identified as the sender of the SMS)
• senderForResponse (use of a short number enabling the 2-way SMS response)

Other

• charset
• class (type of SMS sent)
• coding (encoding on 7 or 8 bits; this impacts the number of characters available per SMS credit)
• differedPeriod (scheduling of the send)
• noStopClause (lets you indicate that this is a non-commercial SMS; the mention is removed from the message)
• priority (priority indication)
• tag (tagging to categorise the message)
• validityPeriod (expiry time of the message if there is a problem delivering it)

Bulk sending

To send the same message to a large number of recipients, we reuse the same POST method, but this time importing a CSV file via a URL:

There are two approaches.

The first uses the receiversDocumentUrl parameter (a URL pointing to a CSV file containing the recipients' numbers) directly with the method above.

The second pre-loads the CSV file with the following method, using the serviceName, csvUrl, description and slotId parameters:

Once the file is loaded, simply call the jobs method again with the receiversSlotId parameter, indicating the correct SlotId:

Mail merge

Bulk sending with mail merge builds on bulk sending and on the creation of a specific CSV contact file linked to a message. The messages can incorporate variable fields. By calling the name of a column, here is an example below to illustrate this use case:

contacts.csv file

number ;lastname ;firstname ;address
0662000000 ;Durant ;Pierre ;xx rue montaigne Paris
0662000001 ;Dupont ;Jean ;xx rue montaigne Paris
...

The message:

Hello #firstname# #lastname#, your order will be delivered to the following address: #address#. Best regards.

Campaign tracking

When creating a send via the POST jobs method, you can provide a value for the tag parameter:

This parameter will then allow you to track the messages sent with this tag.

To retrieve all the identifiers of outgoing messages, use the following method, providing the tag parameter as a filter in the request:

To retrieve all the details of each message, use:

With this information, you can build summary reports for each campaign. Here are some examples of information: rate of delivered messages, error rate, message delivery time, etc.

To track the evolution of your STOP SMS messages, and thus react if an SMS campaign generates a high unsubscribe rate, use:

SMS response

To take advantage of SMS responses, you will need to send your SMS messages with a short number using the senderForResponse parameter.

To configure a Callback call on each response received, so you are notified of responses in real time, use the following method:

With a Pull approach, you can choose to view the responses received by calling the following method:

Ordering SMS credits

To automatically generate SMS purchase orders, call the following method with the SMS account to credit and the amount of credits you wish to purchase as parameters:

In return, you will receive all the pricing information, excluding tax, including tax, the discounts, as well as the contracts and the link to the purchase order so that you can make the payment.

Beforehand, you can obtain the prices according to the desired quantity with the following method:

User management

For each SMS account, you can create users who can have their own sends as well as different management rules, allowing in particular the application of send quotas.

The first step is to create a user:

Then configure their settings (callback, quota, IP, etc.):

Finally, you can view a user's consumption status:

You can also track consumption using a campaign tag or the identity of a sender via the following method, and specify a period, for example to re-invoice consumption month by month:

Credit transfer

If you manage several SMS accounts (serviceName: sms-XXXX-1, sms-XXXXX-2, etc.), you can transfer credits between your different accounts. To do this, use the following method, indicating the SMS account to debit, the one to credit, and finally the amount of credits to transfer:

This mechanism is very useful for managing several SMS accounts independently, in particular for reselling to different parties. To isolate the accounts, you must set up separate Tokens to isolate the rights. This operation is carried out when creating your application Tokens: in the rights, you will have to explicitly specify that a given application only has rights on a ServiceName specified in the authorised URLs.

Go further

Talk to our community of users.