SMS transactionnels
Envoyer un SMS d'un seul segment et suivre son acheminement.
POST /api/v1/sms_messages
Enregistre un SMS d'un seul segment. La réponse est rendue avant l'envoi :
le status évolue ensuite de façon asynchrone, lisez-le avec le GET ci-dessous.
Le service est activé sur demande, pour les organisations Pro et Entreprise.
Tant qu'il ne l'est pas, l'appel répond 403 sms_service_disabled, y compris
en sandbox.
Headers
| Header | Requis | Valeur |
|---|---|---|
X-Api-Key | ✓ | Votre clé API. |
Content-Type | ✓ | application/json |
Body
| Champ | Type | Requis | Description |
|---|---|---|---|
to | string | ✓ | Numéro au format E.164. Refusé s'il est reconnu comme non mobile (fixe, numéro vert...). Un type inconnu est accepté. |
body | string | ✓ | Texte d'un seul segment : alphabet GSM-7, 160 septets au plus. € [ ] { } \ ^ ~ | comptent double. |
sender | string | ✓ | Un des expéditeurs déclarés pour votre organisation. Comparé sans tenir compte de la casse, jamais remplacé par Signlift. |
reference | string | Clé d'idempotence, chaîne de 100 caractères au plus, unique pour toute la vie de l'application. Voir Idempotence. | |
resend | boolean | true quand ce message renvoie un SMS que le destinataire n'a pas reçu. Voir Renvoi. |
Un champ qui n'est pas une chaîne (nombre, tableau, objet) est lu comme absent.
Exemple
curl https://app.signlift.eu/api/v1/sms_messages \
-H "X-Api-Key: $SIGNLIFT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+33612345678",
"body": "Votre colis arrive demain entre 9h et 12h.",
"sender": "Signlift",
"reference": "order-1042"
}'Réponse 202
{
"id": "sms_k3Jx9aPq2LmN7vRt5BwYc8Zd",
"status": "queued",
"to": "+33612345678",
"sender": "Signlift",
"country": "FR",
"unit_price": 0.08,
"currency": "EUR",
"reference": "order-1042",
"resend": false,
"environment": "production",
"created_at": "2026-11-12T08:30:00Z"
}idest un identifiant opaque : conservez-le pour suivre le message.senderrenvoie le nom tel qu'il est déclaré, quelle que soit la casse envoyée.countryest déduit du numéro.unit_priceest le prix facturé du SMS danscurrency, remise éventuelle de l'organisation comprise, figé à la création : une évolution ultérieure des tarifs ou de la remise ne touche pas les messages déjà enregistrés. Il peut valoir0quand les SMS sont offerts. Pour une organisation Entreprise, dont les prix sont fixés par contrat,unit_priceetcurrencyvalentnull.- En sandbox,
statusvautsimulateddès la réponse etenvironmentvautsandbox.
Réponse 200
Rejouer l'appel avec la même reference et les mêmes to, body, sender
et resend renvoie le message existant avec un 200, sans nouvel envoi.
Idempotence
La reference est unique par application. Deux clés d'une même application
partagent donc leurs références ; deux applications distinctes, non.
| Appel | Résultat |
|---|---|
Même reference, mêmes to, body, sender et resend | 200, message existant, aucun envoi |
Même reference, autre to, body, sender ou resend | 409 reference_conflict |
Deux appels simultanés avec la même reference | Un seul message ; l'autre appel reçoit 200 (ou 409 si son contenu diffère) |
La comparaison du contenu porte sur les valeurs telles que vous les envoyez :
rejouer avec un sender dont la casse diffère donne 409, même si les deux
désignent le même expéditeur.
Un rejeu passe même si le plafond mensuel est atteint, même si l'expéditeur a
été supprimé depuis. Il ne passe pas si le service a été désactivé :
sms_service_disabled est contrôlé avant tout.
GET /api/v1/sms_messages/{id}
Lit un message et son état d'acheminement. La lecture reste possible après une désactivation du service, pour suivre les accusés de réception des messages déjà enregistrés.
Exemple
curl https://app.signlift.eu/api/v1/sms_messages/sms_k3Jx9aPq2LmN7vRt5BwYc8Zd \
-H "X-Api-Key: $SIGNLIFT_API_KEY"Réponse 200
{
"id": "sms_k3Jx9aPq2LmN7vRt5BwYc8Zd",
"status": "delivered",
"to": "+33612345678",
"sender": "Signlift",
"country": "FR",
"unit_price": 0.08,
"currency": "EUR",
"reference": "order-1042",
"resend": false,
"environment": "production",
"created_at": "2026-11-12T08:30:00Z",
"provider": "twilio",
"sent_at": "2026-11-12T08:30:04Z",
"delivered_at": "2026-11-12T08:30:09Z",
"failure_reason": null
}Les champs de la création, plus :
| Champ | Type | Description |
|---|---|---|
provider | string ou null | sms_mode ou twilio : l'opérateur qui a pris le message. null tant qu'aucun ne l'a pris. |
sent_at | string ou null | Date d'acceptation par l'opérateur. |
delivered_at | string ou null | Date de l'accusé de livraison. |
failure_reason | string ou null | Cause d'un échec. Voir Statuts. |
Périmètre de lecture
Une clé lit les messages de son organisation et de son environnement, créés par l'API. Une autre clé de la même organisation et du même environnement lit donc les mêmes messages.
Tout le reste répond 404 not_found : un message d'une autre organisation,
de l'autre environnement, un identifiant inconnu, ou un identifiant de SMS de
code de signature (ceux-ci ne sont jamais visibles par l'API).
Purge des données personnelles
| Donnée | Effacée |
|---|---|
| Le texte | 7 jours après sent_at (à défaut, après la création) |
| Le numéro | 30 jours après la création |
La purge est une tâche quotidienne, à 00:35 UTC : l'effacement peut intervenir
jusqu'à un jour après ces délais. Après la purge du numéro, to vaut null.
L'API ne renvoie jamais le texte (body), ni avant ni après la purge :
conservez-le de votre côté si vous en avez besoin.
Statuts et causes d'échec
status | Signification | Facturé |
|---|---|---|
queued | Enregistré, pas encore pris en charge. | non |
sending | Pris en charge, issue pas encore connue. | non |
sent | Accepté par un opérateur. | oui |
delivered | Accusé de livraison reçu. | oui |
undelivered | Accepté par un opérateur puis non livré. | oui |
failed | Aucun opérateur ne l'a pris, ou l'issue est restée inconnue. failure_reason en donne la cause. | non |
simulated | Sandbox : aucun appel à un opérateur. | non |
failure_reason prend l'une de ces valeurs :
failure_reason | Posée sur | Signification |
|---|---|---|
expired | failed | Non pris en charge environ 15 minutes après la création. |
outcome_unknown | failed | Pris en charge, mais aucune issue environ 1 heure après. |
no_provider | failed | Aucun opérateur disponible pour ce message. |
invalid_recipient | failed ou undelivered | Numéro refusé ou désabonné. |
sender_unavailable | failed | Expéditeur utilisable par aucun opérateur pour ce pays. |
unsupported_destination | failed | Destination non desservie. |
provider_unavailable | failed | Opérateurs indisponibles. |
insufficient_credit | failed | Crédit insuffisant chez l'opérateur. |
undeliverable | undelivered | Non livré par l'opérateur. |
unknown_failure | undelivered | Cause non précisée. |
failure_reason n'est donc pas réservé à failed : un message undelivered
en porte aussi une.
Les délais de expired et outcome_unknown sont approximatifs : la tâche qui
les pose tourne toutes les 5 minutes.
Signlift ne renvoie jamais automatiquement un message dont l'issue est
inconnue. Le renvoyer, avec une nouvelle reference, est votre décision.
Renvoi
Quand le destinataire dit ne pas avoir reçu un SMS (un bouton « Renvoyer »,
par exemple), envoyez un nouveau message avec resend: true (booléen JSON).
Vous n'avez rien à conserver du premier envoi : Signlift le retrouve.
Un SMS non reçu vient souvent d'un problème sur le chemin qu'il a emprunté :
opérateur intermédiaire, filtrage, réseau du destinataire. Un nouvel envoi sans
resend reprend le même chemin et peut échouer de la même façon ; avec
resend: true, il passe par un autre opérateur.
Le renvoi peut porter un autre body, par exemple un nouveau code : Signlift
retrouve le SMS précédent par son destinataire, pas par son texte.
Utilisez-le aussi quand votre suivi montre undelivered : l'opérateur a refusé
le message, un autre a ses chances. Pour un failed dont l'issue est inconnue,
le premier SMS a peut-être été reçu : renvoyer reste votre décision.
Au moment de l'envoi, Signlift prend le dernier SMS d'API de votre
organisation vers ce to, dans l'environnement de la clé et les 30 minutes
précédentes, qu'un opérateur a pris en charge, et envoie d'abord par l'autre
opérateur. Deux renvois successifs alternent donc d'opérateur.
La réponse porte resend: true quand un SMS précédent vers ce numéro existe
dans les 30 minutes, et false sinon : le message part alors comme un premier
envoi. resend: true ne garantit pas un autre opérateur. Le renvoi repart par
le même quand :
- le pays ou l'expéditeur n'est desservi que par un opérateur ;
- le SMS précédent n'a encore été pris en charge par aucun opérateur, ou son issue reste inconnue.
En sandbox, resend est accepté mais sans effet : aucun opérateur n'est
appelé.
Un renvoi est facturé et compte dans le plafond mensuel comme tout message. Signlift ne limite pas leur nombre : temporisez le bouton de votre côté.
Ordre des contrôles
Un appel POST est contrôlé dans cet ordre, et la première règle violée
détermine l'erreur :
- service activé (
403 sms_service_disabled) ; - type et longueur de la
reference, type deresend(422 validation_error) ; - rejeu de la
reference(200, ou409 reference_conflict) ; - expéditeur (
unknown_sender) ; - numéro (
invalid_recipient), puis numéro marqué injoignable (invalid_recipient) ; - texte (
invalid_body) ; - destination avec un prix (
unsupported_destination), puis routage (unsupported_destination,sender_unavailable,503 sms_temporarily_unavailable) ; - plafond mensuel, en production seulement (
403 sms_quota_exceeded).
Un numéro que tous les opérateurs ont signalé injoignable (refusé, désabonné) est
refusé en invalid_recipient pendant 7 jours.
Erreurs
| HTTP | Code | Cas |
|---|---|---|
| 403 | sms_service_disabled | Service non activé, ou plan non éligible. |
| 403 | sms_quota_exceeded | Plafond mensuel atteint. Pas de Retry-After : il se lève au mois suivant ou si Signlift relève le plafond. |
| 409 | reference_conflict | reference déjà utilisée avec un autre to, body, sender ou resend. |
| 422 | invalid_recipient | Numéro invalide, non mobile, ou marqué injoignable. |
| 422 | unsupported_destination | Pays exclu (États-Unis, Canada, Porto Rico, Guam, îles Vierges américaines, Samoa américaines, Mariannes du Nord, îles mineures éloignées des États-Unis), sans prix ou non desservi. |
| 422 | invalid_body | Texte vide ou de plus de 160 septets, ou caractères hors GSM-7 (listés dans le message). |
| 422 | unknown_sender | Expéditeur absent de la liste de l'organisation. |
| 422 | sender_unavailable | Expéditeur utilisable par aucun opérateur du pays. |
| 422 | validation_error | reference qui n'est pas une chaîne, ou de plus de 100 caractères ; resend qui n'est pas un booléen JSON. |
| 503 | sms_temporarily_unavailable | Aucun opérateur ne peut prendre un message vers ce numéro pour l'instant. Rien n'est enregistré : rejouez le même appel après le délai de l'en-tête Retry-After, en secondes. |
Les erreurs communes à toute l'API (401, 402, 429) sont décrites dans la
vue d'ensemble. Le GET
répond en plus 404 not_found, comme décrit plus haut.
Les appels en erreur, comme les appels réussis, sont comptés dans le rate-limit de l'organisation.