--- title: "API SMS Cookbook" description: "Découvrez comment utiliser l'API SMS OVHcloud : envoi au fil de l'eau et en masse, publipostage, suivi des campagnes, SMS réponse, gestion des utilisateurs et des crédits" url: https://docs.ovhcloud.com/fr/guides/web-cloud/messaging/sms/api-sms-cookbook lang: fr lastUpdated: 2026-06-15 --- # API SMS Cookbook :::info Les offres SMS d’OVHcloud sont commercialisées uniquement dans les pays suivants : France, Royaume-Uni, Irlande, Espagne, Italie et Pologne. ::: ## Objectif **Découvrez comment utiliser les différentes combinaisons possibles avec l'API pour la plateforme SMS OVHcloud.** ## Envoi de SMS au fil de l’eau L’envoi de SMS au fil de l’eau correspond à un appel webservice pour envoyer régulièrement un à un des SMS. Pour chaque SMS à envoyer, nous réalisons un appel Webservice en POST à la méthode suivante : [🇪🇺POST/sms/{serviceName}/jobs](https://eu.api.ovh.com/console/?section=/sms&branch=v1#post-/sms/-serviceName-/jobs) Le ServiceName correspond à votre compte SMS. Vous pouvez le récupérer soit dans votre espace client, soit en réalisant un appel GET à la méthode suivante : [🇪🇺GET/sms](https://eu.api.ovh.com/console/?section=/sms&branch=v1#get-/sms) Voici un exemple : /sms/sms-XXXXXX-1/jobs Paramètres obligatoires : - ServiceName - Message (votre message, attention à prendre en compte sa longueur et en fonction aussi de l’ajout du STOP, du coding et des caractères spéciaux qui peuvent consommer plus de crédit SMS) Destinataires : - Receivers (liste de numéros, pour des sms au fil de l’eau c’est le paramètre recommandé avec un numéro) - receiversDocumentUrl (url pointant vers un fichier csv contenant les numéros des destinataires) - receiversSlotId (id pointant vers un fichier csv pré-chargé) Émetteur - sender (sélection du nom d’émetteur afin que vous soyez identifié tout de suite comme émetteur du sms) - senderForResponse (utilisation d’un numéro court permettant le SMS réponse 2 way) Autres - charset - class (type de sms envoyé) - coding (encode sur 7 ou 8 bit, cela impact le nombre de caractère disponible par crédit SMS) - differedPeriod (planification de l’envoi) - noStopClause (permet d’indiquer que c’est un sms non commercial, la mention est retirée du message) - priority (indication de priorité) - tag (marquage du tag pour le catégoriser) - validityPeriod (durée d’expiration du message en cas de problème pour le délivrer) ## Envoi de masse Pour envoyer un même message vers un nombre important de destinataires, nous réutilisons la même méthode POST, mais en important cette fois un fichier CSV via une URL : [🇪🇺POST/sms/{serviceName}/jobs](https://eu.api.ovh.com/console/?section=/sms&branch=v1#post-/sms/-serviceName-/jobs) Deux approches sont possibles. La première utilise directement le paramètre `receiversDocumentUrl` (URL pointant vers un fichier CSV contenant les numéros des destinataires) avec la méthode ci-dessus. La seconde charge au préalable le fichier CSV avec la méthode suivante, en utilisant les paramètres `serviceName`, `csvUrl`, `description` et `slotId` : [🇪🇺POST/sms/{serviceName}/receivers](https://eu.api.ovh.com/console/?section=/sms&branch=v1#post-/sms/-serviceName-/receivers) Une fois le fichier chargé, il suffit d’appeler à nouveau la méthode jobs avec le paramètre `receiversSlotId` en indiquant le bon SlotId : [🇪🇺POST/sms/{serviceName}/jobs](https://eu.api.ovh.com/console/?section=/sms&branch=v1#post-/sms/-serviceName-/jobs) ## Publipostage L’envoi de masse avec publipostage s’appuie sur l’envoi de masse et la construction d’un fichier contact csv particulier en lien avec un message. Les messages vont pouvoir incorporer des champs variables. En appelant le nom d’une colonne, voici ci dessous un exemple pour illustrer ce cas d’usage : Fichier contacts.csv ```csv Numero ;nom ;prenom ;adresse 0662000000 ;Durant ;Pierre ;xx rue montaigne Paris 0662000001 ;Dupont ;Jean ;xx rue montaigne Paris ... ``` Le message : ```text Bonjour #prenom# #nom#, votre commande va être livrée à l’adresse : #adresse# . Cordialement. ``` ## Suivi des campagnes Lors de la création d’un envoi via la méthode POST jobs, vous pouvez renseigner une valeur pour le paramètre `tag` : [🇪🇺POST/sms/{serviceName}/jobs](https://eu.api.ovh.com/console/?section=/sms&branch=v1#post-/sms/-serviceName-/jobs) Ce paramètre vous permet ensuite de tracer les messages envoyés avec ce tag. Pour récupérer tous les identifiants de messages sortants, utilisez la méthode suivante en renseignant le paramètre tag en filtre de la requête : [🇪🇺GET/sms/{serviceName}/outgoing](https://eu.api.ovh.com/console/?section=/sms&branch=v1#get-/sms/-serviceName-/outgoing) Pour récupérer tous les détails de chaque message, utilisez : [🇪🇺GET/sms/{serviceName}/outgoing/{id}](https://eu.api.ovh.com/console/?section=/sms&branch=v1#get-/sms/-serviceName-/outgoing/-id-) Avec ces informations, vous pouvez établir des rapports de synthèse pour chaque campagne. Voici quelques exemples d’informations : taux de messages distribués, taux d’erreurs, temps de diffusion du message, etc. Pour suivre l’évolution de vos STOP SMS, et ainsi réagir si une campagne SMS génère un fort taux de désinscription, utilisez : [🇪🇺GET/sms/{serviceName}/blacklists](https://eu.api.ovh.com/console/?section=/sms&branch=v1#get-/sms/-serviceName-/blacklists) ## SMS réponse :::info Le SMS réponse (numéro court via `senderForResponse`) est disponible en France uniquement. ::: Pour profiter du SMS réponse, vous devez envoyer vos SMS avec un numéro court en utilisant le paramètre `senderForResponse`. Pour configurer un appel Callback à chaque réponse reçue, afin d’être notifié en temps réel des réponses, utilisez la méthode suivante : [🇪🇺PUT/sms/{serviceName}](https://eu.api.ovh.com/console/?section=/sms&branch=v1#put-/sms/-serviceName-) En approche `Pull`, vous pouvez choisir de consulter les réponses reçues en appelant la méthode suivante : [🇪🇺GET/sms/{serviceName}/incoming](https://eu.api.ovh.com/console/?section=/sms&branch=v1#get-/sms/-serviceName-/incoming) ## Commande de crédits SMS Pour générer automatiquement des bons de commande de SMS, appelez la méthode suivante avec, en paramètres, le compte SMS à créditer et le montant de crédits que vous souhaitez acheter : [🇪🇺POST/order/sms/{serviceName}/credits](https://eu.api.ovh.com/console/?section=/order&branch=v1#post-/order/sms/-serviceName-/credits) Vous obtenez en retour toutes les informations de prix (hors taxes, toutes taxes comprises), les remises, les contrats ainsi que le lien vers le bon de commande afin de réaliser le paiement. Au préalable, vous pouvez obtenir les prix en fonction de la quantité désirée avec la méthode suivante : [🇪🇺GET/order/sms/{serviceName}/credits](https://eu.api.ovh.com/console/?section=/order&branch=v1#get-/order/sms/-serviceName-/credits) ## Gestion des utilisateurs Pour chaque compte SMS, vous pouvez créer des utilisateurs qui pourront avoir leurs propres envois ainsi que différentes règles de gestion permettant notamment d’appliquer des quotas d’envois. La première étape consiste à créer un utilisateur : [🇪🇺POST/sms/{serviceName}/users](https://eu.api.ovh.com/console/?section=/sms&branch=v1#post-/sms/-serviceName-/users) Puis à paramétrer ses réglages (callback, quota, IP, etc.) : [🇪🇺PUT/sms/{serviceName}/users/{login}](https://eu.api.ovh.com/console/?section=/sms&branch=v1#put-/sms/-serviceName-/users/-login-) Enfin, vous pouvez consulter l’état de consommation d’un utilisateur : [🇪🇺GET/sms/{serviceName}/users/{login}](https://eu.api.ovh.com/console/?section=/sms&branch=v1#get-/sms/-serviceName-/users/-login-) Vous pouvez aussi tracer la consommation en utilisant un tag de campagne ou l’identité d’un sender via la méthode suivante, et spécifier une période, par exemple pour refacturer la consommation de mois en mois : [🇪🇺GET/sms/{serviceName}/outgoing](https://eu.api.ovh.com/console/?section=/sms&branch=v1#get-/sms/-serviceName-/outgoing) ## Transfert de crédits Si vous gérez plusieurs comptes SMS (serviceName : sms-XXXX-1, sms-XXXXX-2, etc.), vous pouvez transférer des crédits entre vos différents comptes. Pour cela, utilisez la méthode suivante en indiquant le compte SMS à débiter, celui à créditer et enfin le montant de crédits à transférer : [🇪🇺POST/sms/{serviceName}/transferCredits](https://eu.api.ovh.com/console/?section=/sms&branch=v1#post-/sms/-serviceName-/transferCredits) Ce mécanisme est utile pour gérer plusieurs comptes SMS de façon indépendante notamment pour de la revente à différents acteurs. Pour isoler les comptes vous devez mettre en place des Tokens distincts afin d’isoler les droits. Cette opération se réalise au moment de créer vos Tokens d’application, dans les droits vous aurez à spécifier explicitement que telle application n’a des droits que sur un ServiceName spécifié dans les url autorisées. ## Aller plus loin Échangez avec notre [communauté d’utilisateurs](https://community.ovhcloud.com/).