Documentation EasySendSMS REST API v1
Table des matières
1. Introduction
2. Authentification
3. Installation et Configuration
4. API Send SMS
5. Exemples d'utilisation
6. Gestion des erreurs
7. Rate Limiting
8. Codes d'erreur complets
9. Bonnes pratiques
Introduction
L'API REST EasySendSMS v1 est une solution robuste pour intégrer des capacités SMS dans vos applications.
Elle permet d'envoyer des messages texte à des téléphones mobiles dans le monde entier avec quelques lignes
de code.
Pourquoi utiliser l'API Send SMS ?
Portée mondiale : Envoyez des SMS aux destinataires du monde entier
Messagerie en temps réel : Livraison instantanée pour les alertes et notifications
Scalabilité : De 1 message à des milliers, l'API s'adapte facilement
Personnalisation : Noms d'expéditeurs personnalisés, support Unicode
Livraison fiable : Taux de livraison élevés et infrastructure robuste
Informations techniques
URL de base : [Link]
Méthode : POST uniquement (GET non supporté)
Format : application/json
Documentation officielle : [Link]
Authentification
Obtenir votre clé API
1. Connectez-vous au tableau de bord EasySendSMS
2. Accédez à Account Settings → API Settings
3. Copiez votre clé API
Headers requis
Toutes les requêtes doivent inclure ces headers :
http
apikey: VOTRE_CLE_API
Content-Type: application/json
Accept: application/json
⚠️Important : Seule la méthode POST est supportée. GET n'est pas autorisé.
Installation et Configuration
Prérequis
Python 3.7+
Module requests
Installation
bash
pip install requests
Initialisation du client
python
from easysendsms_client import EasySendSMSClient, EasySendSMSError
# Méthode recommandée : avec context manager
with EasySendSMSClient(api_key="VOTRE_CLE_API") as client:
# Votre code ici
pass
# Méthode alternative
client = EasySendSMSClient(api_key="VOTRE_CLE_API", timeout=30)
# ... utiliser le client
[Link]()
API Send SMS
Endpoint
POST [Link]
Paramètres requis
Paramètre Type Description Contraintes
Numérique: max 15 caractères
from string Nom de l'expéditeur qui apparaîtra Alphanumérique: max 11 caractères
Préfixez avec "+" pour l'afficher sur le téléphone
Format: 19876543210 (sans + ou 00)
to string Numéro(s) mobile(s) du/des destinataire(s) Plusieurs numéros: séparés par des virgules
Maximum 30 numéros par requête
Texte brut: 153 caractères/partie
text string Message à envoyer Unicode: 67 caractères/partie
Maximum 5 parties
"0" : Texte brut (GSM 3.38)
type string Type de message
"1" : Unicode (autres langues, émojis)
Paramètre optionnel
Paramètre Type Description
scheduled string Date/heure programmée
Méthode Python
python
response = client.send_sms(
sender="MonApp", # Nom de l'expéditeur
to="237612345678", # Un numéro ou liste de numéros
text="Votre message", # Texte du message
message_type=0, # 0=texte brut, 1=unicode
scheduled=None # Optionnel: date programmée
)
Longueur des messages
Les messages SMS sont divisés en parties selon le type :
Type Caractères/partie Utilisation
Type 0 (Texte brut) 153 caractères Texte anglais standard, chiffres, ponctuation basique
Type 1 (Unicode) 67 caractères Accents français, émojis, caractères spéciaux, autres langues
Maximum : 5 parties par message
Exemple de calcul :
Message de 300 caractères en texte brut = 2 parties (153 + 147)
Message de 150 caractères avec émojis = 3 parties (67 + 67 + 16)
Exemples d'utilisation
1. Envoi simple
python
from easysendsms_client import EasySendSMSClient, EasySendSMSError
with EasySendSMSClient(api_key="VOTRE_CLE_API") as client:
try:
response = client.send_sms(
sender="MonApp",
to="237612345678", # Numéro camerounais
text="Bonjour ! Ceci est un message de test.",
message_type=0 # Texte brut
)
print(f"✓ SMS envoyé !")
print(f"Status: {response['status']}")
print(f"Message ID: {response['messageIds'][0]}")
except EasySendSMSError as e:
print(f"✗ Erreur: {e}")
Réponse de succès :
json
{
"status": "OK",
"scheduled": "Now",
"messageIds": [
"OK: 69991a73-a560-429f-9c5a-3251dc1522bb"
]
}
2. Envoi à plusieurs destinataires (même message)
python
with EasySendSMSClient(api_key="VOTRE_CLE_API") as client:
response = client.send_sms(
sender="MonApp",
to=["237612345678", "237698765432", "237687654321"], # Max 30 numéros
text="Message groupé pour tous !",
message_type=0
)
# Parser les résultats
stats = client.parse_message_ids(response['messageIds'])
print(f"Succès: {stats['success']}/{stats['total']}")
print(f"Échecs: {stats['failed']}/{stats['total']}")
Réponse de succès partiel (un numéro invalide) :
json
{
"status": "OK",
"scheduled": "Now",
"messageIds": [
"ERR: 4012",
"OK: 87b021d1-0f21-4c13-924a-65699dcde79e",
"OK: a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
]
}
3. Envoi avec Unicode (émojis, accents)
python
with EasySendSMSClient(api_key="VOTRE_CLE_API") as client:
response = client.send_sms(
sender="MonApp",
to="237612345678",
text="Félicitations ! 🎉 Vous avez gagné ! ✨🎁",
message_type=1 # Unicode OBLIGATOIRE pour émojis
)
print("✓ SMS Unicode envoyé")
⚠️Important : Les émojis et caractères accentués nécessitent message_type=1
4. Envoi programmé
python
with EasySendSMSClient(api_key="VOTRE_CLE_API") as client:
response = client.send_sms(
sender="MonApp",
to="237612345678",
text="Bonne année 2025 ! 🎊",
message_type=1,
scheduled="2024-12-31T19:35:00" # Format ISO 8601 UTC
)
print(f"✓ SMS programmé pour: {response['scheduled']}")
Générer une date programmée :
python
from datetime import datetime, timedelta
# Programmer pour demain 14h00 UTC
scheduled_time = ([Link]() + timedelta(days=1)).replace(
hour=14, minute=0, second=0
).strftime("%Y-%m-%dT%H:%M:%S")
response = client.send_sms(
sender="MonApp",
to="237612345678",
text="Rappel: Votre rendez-vous est demain !",
scheduled=scheduled_time
)
5. Vérification du solde
python
with EasySendSMSClient(api_key="VOTRE_CLE_API") as client:
balance = client.get_balance()
print(f"💰 Solde: {balance['balance']} {balance['currency']}")
# Alerte si solde faible
if float(balance['balance']) < 100:
print("⚠️Solde faible, rechargez votre compte !")
6. Envoi en masse personnalisé
Utilisez send_bulk_sms() pour envoyer des messages personnalisés à chaque destinataire :
python
recipients = [
{"to": "237612345678", "text": "Bonjour Alice, votre code: 123456"},
{"to": "237698765432", "text": "Bonjour Bob, votre rendez-vous: 14h"},
{"to": "237687654321", "text": "Bonjour Charlie, commande #4521 expédiée"}
]
with EasySendSMSClient(api_key="VOTRE_CLE_API") as client:
results = client.send_bulk_sms(
sender="MonApp",
recipients=recipients,
message_type=0
)
# Statistiques
success = sum(1 for r in results if r['status'] == 'success')
print(f"✓ Réussis: {success}/{len(results)}")
7. Envoi par lots optimisé
Utilisez send_batch_sms() pour envoyer le même message à plusieurs destinataires (plus efficace) :
python
# 100 destinataires avec le même message
recipients = [f"23761234{str(i).zfill(4)}" for i in range(100)]
with EasySendSMSClient(api_key="VOTRE_CLE_API") as client:
results = client.send_batch_sms(
sender="MonApp",
recipients=recipients,
text="Promotion ! -50% ce week-end !",
message_type=0,
batch_size=30 # Envoi par lots de 30 (max API)
)
success_batches = sum(1 for r in results if r['status'] == 'success')
print(f"✓ Lots réussis: {success_batches}/{len(results)}")
8. Gestion avancée avec retry
python
def send_with_retry(client, sender, to, text, max_retries=3):
"""Envoi avec retry automatique en cas de rate limit"""
for attempt in range(max_retries):
try:
return client.send_sms(sender=sender, to=to, text=text)
except EasySendSMSError as e:
if e.http_status == 429 and attempt < max_retries - 1:
wait_time = (attempt + 1) * 2 # Backoff exponentiel
print(f"⏳ Rate limit. Attente {wait_time}s...")
[Link](wait_time)
else:
raise
raise EasySendSMSError("Échec après plusieurs tentatives")
# Utilisation
with EasySendSMSClient(api_key="VOTRE_CLE_API") as client:
response = send_with_retry(
client,
sender="MonApp",
to="237612345678",
text="Message important"
)
Gestion des erreurs
Exception personnalisée
Le client utilise EasySendSMSError avec les attributs :
message : Message d'erreur
error_code : Code d'erreur API (4001-4017)
http_status : Code HTTP (400, 401, 403, etc.)
Exemple de gestion complète
python
from easysendsms_client import EasySendSMSError
try:
response = client.send_sms(
sender="MonApp",
to="237612345678",
text="Test"
)
print("✓ Succès !")
except EasySendSMSError as e:
# Gestion selon le code d'erreur
if e.error_code == 4001:
print("❌ Paramètre manquant")
elif e.error_code == 4003:
print("❌ Clé API invalide")
elif e.error_code == 4012:
print("❌ Numéro invalide")
elif e.error_code == 4015:
print("❌ Crédits insuffisants")
elif e.http_status == 429:
print("⏳ Rate limit atteint, attendez 1s")
[Link](1)
# Réessayer...
else:
print(f"❌ Erreur: {e}")
Réponse d'erreur
json
{
"error": 4012,
"description": "Invalid mobile number."
}
Rate Limiting
Limites par défaut
API Limite Action si dépassé
SMS API 30 requêtes/seconde par compte HTTP 429 - Attendre 1s
Balance API 2 requêtes/minute par compte/IP HTTP 429 - Attendre 60s
Limite étendue
Sur demande au support : 150 requêtes/seconde par IP
Respect automatique du rate limit
Le client gère automatiquement le rate limit avec send_bulk_sms() et send_batch_sms() :
python
# Délai automatique entre chaque envoi
results = client.send_bulk_sms(
sender="MonApp",
recipients=recipients,
delay_seconds=0.034 # ~30 req/sec (défaut)
)
Calcul du délai :
30 req/sec = 0.034s de délai
20 req/sec = 0.05s de délai
10 req/sec = 0.1s de délai
Codes d'erreur complets
Codes d'erreur API (4xxx)
Code Description HTTP Status Action
4001 Un ou plusieurs paramètres requis sont manquants 400 Vérifier les paramètres
4002 Aucune clé API trouvée dans la requête 401 Ajouter le header apikey
4003 Clé API invalide 401 Vérifier la clé API
4004 Adresse IP invalide 403 Contacter le support
4005 Clé API inactive 403 Activer la clé dans le dashboard
4006 Compte inactif 403 Activer le compte
4007 Compte démo expiré 403 Passer à un compte payant
4008 Erreur interne 500 NE PAS renvoyer - Contacter le support
4009 Service non disponible 503 NE PAS renvoyer - Réessayer plus tard
4010 Paramètre type invalide 400 Utiliser 0 ou 1
4011 Message invalide 400 Vérifier le contenu du message
4012 Numéro de téléphone invalide 400 Vérifier le format du numéro
4013 Trop de destinataires (>30) 400 Réduire à max 30 numéros
Code Description HTTP Status Action
4014 Nom d'expéditeur invalide 400 Max 11 alphanumérique / 15 numérique
4015 Crédits insuffisants 402 Recharger le compte
4016 Pays/réseau non disponible 400 Contacter le support
4017 Format datetime invalide ou heure passée 400 Utiliser ISO 8601 UTC futur
Codes HTTP
Code Signification Action
200 Succès Aucune
400 Requête invalide Vérifier les paramètres
401 Non autorisé Vérifier la clé API
403 Interdit Vérifier l'état du compte
405 Méthode non autorisée Utiliser POST uniquement
415 Type de média non supporté Utiliser application/json
429 Limite de taux dépassée Attendre et réessayer
500 Erreur serveur Contacter le support
503 Service indisponible Réessayer plus tard
Format des Message IDs
Les messageIds retournés indiquent le statut de chaque envoi :
OK: <uuid> : Message accepté et envoyé avec succès
ERR: <code> : Erreur pour ce numéro (code d'erreur spécifié)
Exemple :
json
{
"messageIds": [
"ERR: 4012", // Premier numéro invalide
"OK: 87b021d1-0f21-4c13-924a-65699dcde79e", // Deuxième OK
"OK: a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d" // Troisième OK
]
}
Parser les résultats
python
response = client.send_sms(
sender="MonApp",
to=["237612345678", "237698765432", "invalide"],
text="Test"
)
stats = client.parse_message_ids(response['messageIds'])
print(f"Succès: {stats['success']}/{stats['total']}")
print(f"Échecs: {stats['failed']}/{stats['total']}")
print(f"IDs réussis: {stats['successful_ids']}")
print(f"Codes d'erreur: {stats['failed_codes']}")
Bonnes pratiques
1. Toujours utiliser le context manager
python
# ✓ Recommandé
with EasySendSMSClient(api_key="...") as client:
client.send_sms(...)
# Fermeture automatique
# ✗ Éviter
client = EasySendSMSClient(api_key="...")
client.send_sms(...)
# Oubli de [Link]()
2. Gérer toutes les erreurs
python
try:
response = client.send_sms(...)
except EasySendSMSError as e:
# Logger l'erreur
[Link](f"Erreur SMS: {e} (code: {e.error_code})")
# Notifier l'admin si critique
if e.error_code in [4008, 4009, 4015]:
send_alert_to_admin(e)
3. Choisir la bonne méthode d'envoi
Cas d'usage Méthode recommandée
Message identique à plusieurs destinataires send_batch_sms()
Messages personnalisés pour chaque destinataire send_bulk_sms()
Envoi simple à 1 numéro send_sms()
4. Respecter les formats
python
# ✓ Format correct
to = "237612345678" # Sans + ou 00
# ✗ Format incorrect
to = "+237612345678" # Ne fonctionne pas
to = "00237612345678" # Ne fonctionne pas
5. Vérifier le solde régulièrement
python
def check_balance_before_send(client, threshold=100):
"""Vérifier le solde avant envoi en masse"""
balance = client.get_balance()
current_balance = float(balance['balance'])
if current_balance < threshold:
raise EasySendSMSError(
f"Solde insuffisant: {current_balance} < {threshold}"
)
return current_balance
# Utilisation
with EasySendSMSClient(api_key="...") as client:
check_balance_before_send(client)
# Continuer avec l'envoi en masse
6. Logger les envois
python
import logging
[Link](
level=[Link],
format='%(asctime)s - %(levelname)s - %(message)s'
)
logger = [Link](__name__)
with EasySendSMSClient(api_key="...") as client:
response = client.send_sms(...)
[Link](f"SMS envoyé à {to}: {response['messageIds'][0]}")
7. Utiliser des timeouts adaptés
python
# Pour des envois en masse
client = EasySendSMSClient(api_key="...", timeout=60)
# Pour des envois simples
client = EasySendSMSClient(api_key="...", timeout=30)
8. Nettoyer les numéros avant envoi
python
def clean_phone_number(phone: str) -> str:
"""Nettoie un numéro de téléphone"""
# Retirer espaces, tirets, parenthèses
phone = [Link](" ", "").replace("-", "")
phone = [Link]("(", "").replace(")", "")
# Retirer + et 00 au début
if [Link]("+"):
phone = phone[1:]
elif [Link]("00"):
phone = phone[2:]
return phone
# Utilisation
phone = clean_phone_number("+237 61 23 45 678")
# Résultat: "237612345678"
Exemple d'application complète
python
from easysendsms_client import EasySendSMSClient, EasySendSMSError
import logging
import time
# Configuration du logging
[Link](level=[Link])
logger = [Link](__name__)
class SMSService:
"""Service d'envoi SMS avec gestion complète"""
def __init__(self, api_key: str):
self.api_key = api_key
def send_verification_code(self, phone: str, code: str) -> bool:
"""Envoie un code de vérification"""
with EasySendSMSClient(api_key=self.api_key) as client:
try:
response = client.send_sms(
sender="MonApp",
to=phone,
text=f"Votre code de vérification est: {code}",
message_type=0
)
[Link](f"Code envoyé à {phone}: {response['messageIds'][0]}")
return True
except EasySendSMSError as e:
[Link](f"Échec envoi code à {phone}: {e}")
return False
def send_bulk_notifications(self, notifications: list) -> dict:
"""Envoie des notifications en masse avec statistiques"""
with EasySendSMSClient(api_key=self.api_key) as client:
# Vérifier le solde
try:
balance = client.get_balance()
[Link](f"Solde actuel: {balance['balance']} {balance['currency']}")
except EasySendSMSError as e:
[Link](f"Impossible de vérifier le solde: {e}")
# Envoi en masse
results = client.send_bulk_sms(
sender="MonApp",
recipients=notifications,
message_type=0
)
# Statistiques
stats = {
'total': len(results),
'success': sum(1 for r in results if r['status'] == 'success'),
'failed': sum(1 for r in results if r['status'] == 'error')
}
[Link](f"Envoi terminé: {stats['success']}/{stats['total']} réussis")
return stats
# Utilisation
if __name__ == "__main__":
service = SMSService(api_key="VOTRE_CLE_API")
# Envoi d'un code de vérification
service.send_verification_code("237612345678", "123456")
# Envoi en masse
notifications = [
{"to": "237612345678", "text": "Message pour Alice"},
{"to": "237698765432", "text": "Message pour Bob"}
]
stats = service.send_bulk_notifications(notifications)
print(f"Résultats: {stats}")
Support et ressources
Documentation officielle : [Link]
Tableau de bord : [Link]
Support : Via le tableau de bord
Status de l'API : Vérifier en cas de code 503
Exemple cURL
Pour référence, voici un exemple de requête cURL :
bash
curl -X POST \
-H "apikey: VOTRE_CLE_API" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"from": "MonApp",
"to": "12345678900,19876543210",
"text": "Hello, this is a test message!",
"type": "0"
}' \
"[Link]
Version du client : 1.0.0
Dernière mise à jour : 3 décembre 2024
Compatibilité API : EasySendSMS REST API v1