--- title: "API SMS Cookbook" description: "Find out how to use the OVHcloud SMS API: on-the-fly and bulk sending, mail merge, campaign tracking, SMS responses, user and credit management" url: https://docs.ovhcloud.com/en/guides/web-cloud/messaging/sms/api-sms-cookbook lang: en lastUpdated: 2026-06-15 --- # API SMS Cookbook :::info OVHcloud SMS offers are only available in the following countries: France, the United Kingdom, Ireland, Spain, Italy and Poland. ::: ## 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: [🇪🇺POST/sms/{serviceName}/jobs](https://eu.api.ovh.com/console/?section=/sms&branch=v1#post-/sms/-serviceName-/jobs) 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: [🇪🇺GET/sms](https://eu.api.ovh.com/console/?section=/sms&branch=v1#get-/sms) 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: [🇪🇺POST/sms/{serviceName}/jobs](https://eu.api.ovh.com/console/?section=/sms&branch=v1#post-/sms/-serviceName-/jobs) 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: [🇪🇺POST/sms/{serviceName}/receivers](https://eu.api.ovh.com/console/?section=/sms&branch=v1#post-/sms/-serviceName-/receivers) Once the file is loaded, simply call the jobs method again with the `receiversSlotId` parameter, indicating the correct SlotId: [🇪🇺POST/sms/{serviceName}/jobs](https://eu.api.ovh.com/console/?section=/sms&branch=v1#post-/sms/-serviceName-/jobs) ## 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 ```csv number ;lastname ;firstname ;address 0662000000 ;Durant ;Pierre ;xx rue montaigne Paris 0662000001 ;Dupont ;Jean ;xx rue montaigne Paris ... ``` The message: ```text 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: [🇪🇺POST/sms/{serviceName}/jobs](https://eu.api.ovh.com/console/?section=/sms&branch=v1#post-/sms/-serviceName-/jobs) 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: [🇪🇺GET/sms/{serviceName}/outgoing](https://eu.api.ovh.com/console/?section=/sms&branch=v1#get-/sms/-serviceName-/outgoing) To retrieve all the details of each message, use: [🇪🇺GET/sms/{serviceName}/outgoing/{id}](https://eu.api.ovh.com/console/?section=/sms&branch=v1#get-/sms/-serviceName-/outgoing/-id-) 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: [🇪🇺GET/sms/{serviceName}/blacklists](https://eu.api.ovh.com/console/?section=/sms&branch=v1#get-/sms/-serviceName-/blacklists) ## SMS response :::info SMS response (short number via `senderForResponse`) is available in France only. ::: 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: [🇪🇺PUT/sms/{serviceName}](https://eu.api.ovh.com/console/?section=/sms&branch=v1#put-/sms/-serviceName-) With a `Pull` approach, you can choose to view the responses received by calling the following method: [🇪🇺GET/sms/{serviceName}/incoming](https://eu.api.ovh.com/console/?section=/sms&branch=v1#get-/sms/-serviceName-/incoming) ## 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: [🇪🇺POST/order/sms/{serviceName}/credits](https://eu.api.ovh.com/console/?section=/order&branch=v1#post-/order/sms/-serviceName-/credits) 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: [🇪🇺GET/order/sms/{serviceName}/credits](https://eu.api.ovh.com/console/?section=/order&branch=v1#get-/order/sms/-serviceName-/credits) ## 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: [🇪🇺POST/sms/{serviceName}/users](https://eu.api.ovh.com/console/?section=/sms&branch=v1#post-/sms/-serviceName-/users) Then configure their settings (callback, quota, IP, etc.): [🇪🇺PUT/sms/{serviceName}/users/{login}](https://eu.api.ovh.com/console/?section=/sms&branch=v1#put-/sms/-serviceName-/users/-login-) Finally, you can view a user's consumption status: [🇪🇺GET/sms/{serviceName}/users/{login}](https://eu.api.ovh.com/console/?section=/sms&branch=v1#get-/sms/-serviceName-/users/-login-) 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: [🇪🇺GET/sms/{serviceName}/outgoing](https://eu.api.ovh.com/console/?section=/sms&branch=v1#get-/sms/-serviceName-/outgoing) ## 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: [🇪🇺POST/sms/{serviceName}/transferCredits](https://eu.api.ovh.com/console/?section=/sms&branch=v1#post-/sms/-serviceName-/transferCredits) 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](https://community.ovhcloud.com/).