Envoyer des SMS avec un agent IA via l'API SMS Mailpro™

L'email est le canal par défaut. Le SMS est le canal de l'urgence. Quand votre agent IA doit pinguer un vrai humain en quelques secondes — une panne, une alerte fraude, un OTP, une mise à jour de livraison — le SMS est ce qui est effectivement lu dans la minute. Ce guide explique comment brancher Claude, GPT ou n'importe quel LLM à tool calling sur l'API SMS Mailpro, aussi bien pour les envois unitaires que pour les campagnes en masse.

En résumé

• L'API SMS Mailpro s'authentifie avec id_client + api_key en HTTPS.
• Utilisez /send/add_single.json pour un SMS unitaire et /send/add.json pour un envoi en masse.
• Les numéros sont au format international E.164 (ex. +33671234567) ou avec préfixe 00 — l'API accepte les deux et stocke la forme normalisée.
• Chaque endpoint est documenté dans plus de 20 langages sur notre portail développeurs.

Où le SMS piloté par IA a vraiment du sens

Alertes temps réel

Votre pipeline de monitoring détecte un pic d'erreurs 5xx. Un agent IA lit l'anomalie, classe sa sévérité, et envoie un SMS à l'ingénieur de permanence avec du contexte (« API v3 en hausse d'erreurs × 12 sur 5 min, endpoints CRM affectés ») — pas juste un bip de pager. Diagnostic plus rapide, moins de fatigue d'alerte.

OTP et flux two-factor

L'agent reçoit une requête « authentifie cet utilisateur », génère un code à 6 chiffres, le stocke avec une expiration, et l'envoie par SMS. L'utilisateur tape le code dans l'app, l'agent le vérifie. Aujourd'hui c'est un flux à coder soi-même ; avec le prochain endpoint Verify/OTP (voir la roadmap API SMS), ce sera un seul appel.

Fallback multi-canal

L'email n'a pas été ouvert en 2 h, mais c'est urgent. L'agent bascule en SMS — « Votre rendez-vous est dans 1 h » — en utilisant la même fiche contact depuis Mailpro v3. Orchestration multicanal pilotée par le raisonnement du LLM.

Campagnes événementielles

Black Friday à midi : l'agent choisit l'audience selon un critère de fraîcheur (« clients qui ont ouvert un email dans les 14 derniers jours »), rédige une offre de 140 caractères, et tire une campagne en masse via /send/add.json. Offre en ligne en moins d'une minute, zéro clic dans un tableau de bord.

Setup et modèle de facturation SMS

id_client + api_key

Même pattern d'auth que l'API email v2. Les deux valeurs se trouvent dans votre compte Mailpro sous Paramètres → Accès API. L'API SMS utilise des paramètres en snake_case (id_client et pas IdClient) — petite différence avec v2, à signaler à l'agent dans son prompt système.

Crédits, tarifs par pays, solde test

Les SMS ne sont pas à prix fixe : le coût par message dépend du pays de destination. Consultez votre solde à tout moment :

curl "https://api.mailpro.com/sms/credit/get.json?id_client=YOUR_ID&api_key=YOUR_API_KEY"

Réponse :

{ "TotalCredits": 1476 }

Pour les tarifs par pays, consultez la grille sur les tarifs Mailpro.

Sandbox

Pas de sandbox dédiée pour l'instant — testez avec de petits volumes sur votre compte réel. Commencez avec /send/add_single.json en vous envoyant des SMS à votre propre numéro avant d'ouvrir les vannes du bulk.

Pas à pas : SMS unitaire envoyé par un agent IA

1. Schéma d'outil

tools = [{
    "name": "send_sms",
    "description": "Envoie un SMS unitaire à un numéro via Mailpro.",
    "input_schema": {
        "type": "object",
        "properties": {
            "to":      {"type": "string", "description": "Numéro au format international E.164, ex +33671234567"},
            "message": {"type": "string", "description": "Corps du SMS, max 160 car. pour un segment"}
        },
        "required": ["to", "message"]
    }
}]

2. Formatage des numéros

Utilisez le format international E.164 : signe +, indicatif pays, numéro national, sans espaces ni tirets. Le préfixe 00 00e0 la place du + fonctionne aussi. Exemples :

• France : +33671234567
• Suisse : +41791234567
• Belgique : +32475123456
• Canada : +15145551234

Si votre agent reçoit des entrées en vrac (« 06 71 23 45 67 »), normalisez avant d'envoyer — des librairies comme phonenumbers (Python) ou libphonenumber-js (Node) s'en chargent parfaitement.

3. Appeler /send/add_single.json

curl -X POST "https://api.mailpro.com/sms/send/add_single.json" \
  -d "id_client=YOUR_ID&api_key=YOUR_API_KEY" \
  -d "to=+33671234567" \
  -d "message=Votre code de vérification est 482913. Valide 10 min."

Réponse :

{
  "Result": "OK",
  "IdSend": 98765,
  "RemainingCredits": 1474
}

4. Statut de livraison dans la réponse

Result: "OK" signifie que le SMS a été accepté par la gateway, pas encore livré sur le handset. Pour la confirmation de livraison (DLR), écoutez le prochain webhook sms.delivered (voir la roadmap API SMS). En attendant, RemainingCredits vous dit que l'envoi a été facturé.

SMS en masse : cibler une liste entière

Gérer les listes de numéros (/list, /phone)

Les listes SMS sont l'équivalent des carnets d'adresses email côté SMS. Les endpoints pour lister, ajouter, modifier, supprimer listes et numéros sont sous /list/*.json et /phone/*.json.

Envoyer une campagne avec /send/add.json

curl -X POST "https://api.mailpro.com/sms/send/add.json" \
  -d "id_client=YOUR_ID&api_key=YOUR_API_KEY" \
  -d "id_list=11088" \
  -d "message=Black Friday : -30% jusqu'à minuit. mailp.ro/bf2026"

L'endpoint place la campagne en file et tire des SMS sur chaque numéro de la liste.

Programmé vs immédiat

Ajoutez plan_date=2026-11-27T12:00:00 pour programmer. Omettez-le pour un envoi immédiat. L'agent peut choisir l'heure selon le fuseau horaire des destinataires — mais surveillez le délai agrégé : 10 000 SMS peuvent prendre plusieurs minutes à traverser la gateway.

Importer des numéros en masse via fichier

Comme l'API email, l'API SMS expose désormais un endpoint d'upload de fichier :

Vous construisez un agent IA qui envoie des SMS ? Les offres Mailpro incluent l’API SMS, le suivi de livraison et le volume nécessaire — à un prix prévisible.

curl -X POST "https://api.mailpro.com/sms/import/upload.json" \
  -F "id_client=YOUR_ID" \
  -F "api_key=YOUR_API_KEY" \
  -F "id_list=11088" \
  -F "[email protected]" \
  -F "webhook_url=https://example.com/hooks/import-done"

La première colonne du CSV doit s'appeler Phone ou PhoneNumber. Les numéros sont normalisés en E.164 côté serveur ; les entrées invalides sont écartées (et remontées dans le bilan du job). Spec complète dans la section Import de la référence SMS.

Exemples de code

Python (agent → SMS avec retry)

import anthropic, requests, time

def send_sms(to, message, retries=3):
    for attempt in range(retries):
        r = requests.post(
            "https://api.mailpro.com/sms/send/add_single.json",
            data={
                "id_client": MAILPRO_ID, "api_key": MAILPRO_KEY,
                "to": to, "message": message
            }
        )
        if r.status_code == 429:
            time.sleep(2 ** attempt)  # backoff exponentiel
            continue
        return r.json()
    raise Exception("Envoi SMS échoué après plusieurs essais")

Node.js (webhook Express → Claude → SMS)

import express from "express";
import Anthropic from "@anthropic-ai/sdk";

const app = express();
const ai = new Anthropic();

app.post("/alert", async (req, res) => {
  const { severity, message } = req.body;
  const resp = await ai.messages.create({
    model: "claude-sonnet-4-5",
    max_tokens: 256,
    tools: [/* schéma send_sms */],
    messages: [{ role: "user", content: `Alerte ${severity} : ${message}. Notifie l'astreinte.` }]
  });
  for (const b of resp.content) {
    if (b.type === "tool_use") {
      await fetch(`https://api.mailpro.com/sms/send/add_single.json`, {
        method: "POST",
        body: new URLSearchParams({
          id_client: ID, api_key: KEY,
          to: b.input.to, message: b.input.message
        })
      });
    }
  }
  res.sendStatus(200);
});

cURL

curl -X POST "https://api.mailpro.com/sms/send/add_single.json" \
  -d "id_client=YOUR_ID&api_key=YOUR_API_KEY" \
  -d "to=+33671234567" \
  -d "message=Votre sauvegarde Mailpro s'est terminée à 03:04 UTC."

Pour le même appel dans une vingtaine de langages supplémentaires (PHP, Go, Ruby, C#, Java, Swift…), consultez la référence SMS — chaque endpoint propose le snippet équivalent à copier.

À venir : Verify/OTP et Phone Lookup

Deux features de la roadmap API SMS sont particulièrement utiles aux intégrations d'agent IA :

Endpoint Verify / OTP

Plutôt que de coder votre propre flux OTP (générer le code, stocker, envoyer, vérifier), les prochains endpoints /verify/start et /verify/check feront tout : génération de code, hachage, rate limits, templates multilingues, comptage des essais. L'agent appelle simplement /verify/start puis /verify/check.

HLR Phone Lookup

Le prochain endpoint /phone/lookup retournera en temps réel les infos opérateur (mobile / fixe / voip), la détection de portabilité (MNP) et la joignabilité. Essentiel pour nettoyer vos listes avant une campagne SMS — inutile d'envoyer à un numéro déconnecté.

Les deux features se brancheront sur le même modèle d'auth et seront donc immédiatement consommables par un agent IA.

Astuces et pièges

Réponses en PascalCase (comme l'email v2)

L'API SMS Mailpro renvoie Result, IdSend, RemainingCredits — en PascalCase. Cohérent avec v2 email, différent de v3 CRM (snake_case). À préciser dans le prompt système.

Gestion du STOP et suppression des numéros

Les utilisateurs peuvent répondre STOP pour se désinscrire. Actuellement, notre gateway gère ça et bloque automatiquement les envois futurs. Le futur endpoint /suppressions exposera la liste de suppressions comme ressource API — pour l'audit et la gestion manuelle.

RGPD et consentement

Ayez toujours un consentement explicite avant d'envoyer des SMS marketing. Pour les SMS transactionnels (OTP, alertes déclenchées par une action utilisateur), le consentement est implicite. Votre agent ne doit pas être celui qui décide d'inscrire un utilisateur — c'est une décision légale, pas une décision de prompt.

Cas d'usage (fictif) : « VeloCourrier », livraison à vélo à Genève avec SMS d'ETA pilotés par IA

VeloCourrier livre nourriture et colis à Genève. Historiquement, le client recevait un SMS « votre coursier est en route » au moment du pickup, et c'était tout. L'équipe a branché Claude derrière le système de dispatch : dès que le GPS du coursier signale qu'il est à moins de 500 m du point de chute, l'agent tire un SMS Mailpro avec un message adapté au type de commande (« Votre café arrive dans 2 minutes — merci d'être à la porte »). Le NPS client sur l'étape d'arrivée a monté de 18 points. Le volume SMS a augmenté de 30 %, ce qui reste largement en dessous des économies sur les appels au support. L'équipe dispatch surveille les messages envoyés par l'agent dans l'historique Mailpro ; ajuste le prompt de temps en temps quand le ton n'est pas tout à fait juste.

Et maintenant ?

Le SMS est le dernier canal majeur de la stack Mailpro. Si vous n'avez pas encore lu le guide pilier sur les agents IA et Mailpro, commencez par là pour la vue d'ensemble. Pour les guides email, voir emails transactionnels v2 et CRM v3.

Référence : API SMS Mailpro. Tarifs : prix Mailpro.

FAQ

Un agent IA peut-il envoyer des OTP via Mailpro ?

Aujourd'hui oui, en codant soi-même : générer un code à 6 chiffres, le stocker avec une expiration, l'envoyer via /send/add_single.json. Très prochainement, un endpoint dédié /verify/start + /verify/check fera tout en un seul appel. Voir la roadmap API SMS.

Quel est le prix par SMS ?

Variable selon le pays de destination. Consultez les tarifs pour la grille actuelle.

L'API supporte-t-elle les numéros internationaux ?

Oui, Mailpro envoie vers plus de 200 pays. Utilisez le format E.164 (+lindicatif><numéro>, ex. +33671234567) ou le préfixe 00 équivalent — l'API accepte les deux.

Comment bloquer un numéro qui a répondu STOP ?

Aujourd'hui c'est automatique au niveau de la gateway. Le prochain endpoint /suppressions vous permettra de lister, ajouter et retirer les numéros supprimés par API — utile pour synchroniser avec votre propre base de préférences.