API SMS Mailpro™ : Référence

POST /token

Obtenir un jeton d’accès (redirection 307 vers /v3/token)

Obtient un jeton Bearer JWT à l’aide des identifiants client Mailpro. Transmettez l’access_token retourné en tant que Authorization: Bearer <token> dans toutes les requêtes suivantes. Le même jeton est également valable sur l’API CRM v3 et l’API Email v2.

> ⚙ Détail d’implémentation — POST /sms/token est une 307 Temporary > Redirect vers POST /v3/token (configurée au niveau de la couche de > réécriture web.config d’IIS). La 307 HTTP préserve à la fois la > méthode (POST) et le corps de la requête, si bien que tout > client HTTP respectant le standard suit la redirection de manière > transparente — vous continuez à poster sur /sms/token et récupérez un > JWT valide en retour. Il n’existe aucune logique d’émission de jetons > dupliquée ; l’API SMS n’émet jamais de jetons par elle-même.

Types de grants pris en charge

Durée de vie des jetons

• Jeton d’accès : 30 jours
• Refresh token : 90 jours

Utilisez grant_type=refresh_token pour renouveler le jeton d’accès sans vous réauthentifier. Stockez les jetons côté serveur (Vault, variables d’environnement) ; ne les intégrez jamais dans du JS navigateur ni dans des binaires d’applications mobiles. Consultez la doc /token de l’API CRM v3 pour la note de sécurité complète.

Corps de la requête (application/x-www-form-urlencoded)

Réponses

Exemple 200

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 31535999,
  "userName": "12345",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "application": null
}

Exemple 400

{
  "error": "invalid_grant",
  "error_description": "The username or password is incorrect."
}

GET /account/limits.{format}

Récupérer le quota d’API mensuel

Retourne le quota de requêtes API mensuel du client authentifié.

Calcul du quota : la limite est calibrée à partir des crédits d’abonnement email (en général subscription_credits × 5). Pour un plan à 10 000 emails/mois, cela donne un budget mensuel de 50 000 requêtes. Réinitialisation à la date anniversaire de l’abonnement (et non le 1er du mois calendaire).

Ce qui consomme des crédits :

• Chaque requête API authentifiée vers les endpoints v2, v3 ou sms.
• Chaque évènement webhook envoyé à un endpoint abonné.

Ce qui est GRATUIT (ne consomme pas de crédits) :

• Les endpoints /health.
• Les requêtes échouant avec 401, 403 ou 429.
• Les évènements webhook pour les clients sans abonnement correspondant.

Le quota est partagé entre les 3 API Mailpro (v2, v3, sms) — un client = un budget mensuel pour toute la plateforme. Les envois SMS consomment en plus le solde de crédits SMS dédié (GET /credit/get.{format}).

Scope OAuth : account:read

Paramètres

Réponses

Exemple 200

{
  "monthlyLimit": 50000,
  "remaining": 32847,
  "used": 17153,
  "isFree": false,
  "remainedSendsForFree": null
}

POST /send/add.{format}

Envoyer un SMS en masse à une liste de contacts

Envoie un SMS à tous les numéros de téléphone d’une liste de contacts. Prend en charge la planification : positionnez scheduled_time sur une date future pour un envoi différé, ou omettez-le pour un envoi immédiat.

Consommation de crédits : les crédits sont déduits au moment de l’envoi. Les messages longs (>160 caractères GSM-7) sont scindés en plusieurs parties, chacune coûtant des crédits supplémentaires.

La réponse retourne { "Error": "Insufficient Credit", "Code": 202 } si le compte ne dispose pas de crédits suffisants.

Scope OAuth : sms:send

Paramètres

Corps de la requête (application/x-www-form-urlencoded)

Réponses

Exemple 200

{
  "Id": 6001,
  "Message": "Flash sale today only — 30% off all orders. Shop now at mailpro.com/shop",
  "ScheduledTime": "2026-04-20T10:00:00",
  "To": [
    "42"
  ]
}

Exemple 202

{
  "Error": "Insufficient Credit",
  "Code": 202
}

Exemple 400

{
  "Error": "Malformed Input",
  "Code": 103
}

GET /send/add_single.{format}

Envoyer un SMS unique (GET)

Envoie un SMS unique à un destinataire via une requête GET. Utile pour les intégrations simples lorsque POST n’est pas disponible. Les identifiants et le message sont transmis en paramètres de requête.

Note : évitez d’utiliser GET pour des messages sensibles — les paramètres de requête apparaissent dans les journaux serveur. Préférez POST /send/add_single.

Scope OAuth : sms:send

Paramètres

Réponses

Exemple 200

{
  "Id": 5001,
  "Message": "Your appointment is confirmed for tomorrow at 10:00.",
  "ScheduledTime": "2026-04-15T09:00:00",
  "To": "0041791234567",
  "Charge": "1"
}

POST /send/add_single.{format}

Envoyer un SMS unique

Envoie un SMS unique à un numéro de téléphone destinataire. Prend en charge la planification via scheduled_time.

Consommation de crédits : les crédits sont déduits au moment de l’envoi. Le champ Charge de la réponse indique combien de crédits ont été consommés.

La réponse retourne { "Error": "Insufficient Credit", "Code": 202 } si le compte ne dispose pas de crédits suffisants.

Scope OAuth : sms:send

Paramètres

Corps de la requête (application/x-www-form-urlencoded)

Réponses

Exemple 200

{
  "Id": 5001,
  "Message": "Your verification code is 8472. Valid for 10 minutes.",
  "ScheduledTime": "2026-04-15T14:30:00",
  "To": "0041791234567",
  "Charge": "1"
}

Exemple 202

{
  "Error": "Insufficient Credit",
  "Code": 202
}

Exemple 400

{
  "Error": "Malformed Input",
  "Code": 103
}

GET /send/list.{format}

Lister les campagnes SMS

Retourne la liste des campagnes SMS (envois en masse) du compte. Pagination via les en-têtes NumberOfRecords et PageNumber.

Utilisez type_to pour filtrer par type d’envoi :

• 0 (par défaut) — envois en masse à une liste
• 1 — envois individuels uniques

Scope OAuth : sms:send

Paramètres

Réponses

Exemple 200

[
  {
    "Id": 5001,
    "Message": "Your verification code is 8472",
    "ScheduledTime": "2026-04-15T09:00:00",
    "To": "41791234567"
  }
]

POST /send/del.{format}

Annuler ou supprimer un envoi SMS

Annule un envoi SMS planifié en attente, ou supprime un envoi terminé de l’historique. Seuls les envois planifiés à venir peuvent être annulés. Les envois en cours ne peuvent pas être arrêtés.

Scope OAuth : sms:send

Paramètres

Corps de la requête (application/x-www-form-urlencoded)

Réponses

Exemple 200

{
  "Result": "OK"
}

Exemple 500

{
  "Error": "Delete failed",
  "Code": 500
}

GET /send/scheduled.{format}

Lister mes envois SMS planifiés

Retourne les envois SMS (unitaires ou en campagne) planifiés pour une date future et qui n’ont pas encore été expédiés. Utile avant d’appeler /cancel ou /reschedule.

Les enregistrements sont triés par scheduled_time croissant.

Scope OAuth : sms:send

Paramètres

Réponses

Exemple 200

[
  {
    "Id": 9001,
    "Message": "Black Friday: 30% off until midnight.",
    "ScheduledTime": "2026-11-27T12:00:00",
    "To": "+33671234567"
  }
]

POST /send/{id_send}/cancel.{format}

Annuler un envoi SMS planifié

Annule un SMS planifié qui n’a pas encore été expédié. Si l’envoi a déjà été traité (ou s’il n’existe pas / appartient à un autre client), retourne 409 Conflict.

Scope OAuth : sms:send

Paramètres

Corps de la requête (application/x-www-form-urlencoded)

Réponses

Exemple 200

{
  "Result": "OK",
  "Cancelled": 9001
}

Exemple 409

{
  "error": "conflict",
  "message": "Send not found, not owned by client, or already dispatched."
}

PATCH /send/{id_send}/reschedule.{format}

Replanifier un envoi SMS planifié

Met à jour la date prévue d’un SMS planifié qui n’a pas encore été expédié. La nouvelle date doit être dans le futur et dans un délai de 90 jours.

Nom du champ de date : l’API accepte scheduled_time (champ principal), ainsi que les alias historiques PlanDate, date_planned et DatePlanned. Fournissez n’importe lequel d’entre eux — le premier non null est utilisé.

Scope OAuth : sms:send

Paramètres

Corps de la requête (application/x-www-form-urlencoded)

Réponses

Exemple 200

{
  "Result": "OK",
  "Id": 9001,
  "NewScheduledTime": "2026-12-31T14:30:00"
}

Exemple 409

{
  "error": "conflict",
  "message": "Reschedule failed — send not found, already dispatched, or new date out of range."
}

GET /list/list.{format}

Lister les listes de contacts téléphoniques

Retourne toutes les listes de contacts SMS du compte. Utilisez les valeurs Id retournées lors de l’envoi de campagnes SMS en masse ou de l’ajout de numéros de téléphone.

Scope OAuth : sms:contacts:read

Paramètres

Réponses

Exemple 200

{
  "Items": [
    {
      "AddressBookId": 42,
      "Name": "Newsletter subscribers",
      "TotalNumberPhones": 1547
    },
    {
      "AddressBookId": 43,
      "Name": "Loyalty program",
      "TotalNumberPhones": 823
    }
  ]
}

POST /list/add.{format}

Créer une liste de contacts

Crée une nouvelle liste de contacts SMS portant le nom indiqué. La liste démarre vide — ajoutez des numéros de téléphone avec POST /phone/add. Maximum 1 000 listes par compte (même limite sur les trois API Mailpro et dans l'app). Renvoie HTTP 422 si la limite est atteinte.

Paramètres

Corps de la requête (application/x-www-form-urlencoded)

Réponses

Exemple 200

{
  "Id": 44,
  "Name": "Spring campaign 2026",
  "NumberPhones": 0
}

Exemple 400

{
  "Error": "Malformed Input",
  "Code": 103
}

POST /list/edit.{format}

Renommer une liste de contacts

Met à jour le nom d’affichage d’une liste de contacts SMS existante. Les numéros de téléphone de la liste ne sont pas affectés.

Scope OAuth : sms:contacts:write

Paramètres

Corps de la requête (application/x-www-form-urlencoded)

Réponses

POST /list/del.{format}

Supprimer une liste de contacts

Supprime définitivement une liste de contacts SMS ainsi que tous les numéros de téléphone qu’elle contient. Cette action est irréversible.

Scope OAuth : sms:contacts:write

Paramètres

Corps de la requête (application/x-www-form-urlencoded)

Réponses

GET /phone/list.{format}

Lister les numéros de téléphone d’une liste de contacts

Retourne une liste paginée des numéros de téléphone d’une liste de contacts donnée. Utilisez address_book_id pour indiquer la liste à récupérer. Pagination : NumberOfRecords et PageNumber (5 000 par page par défaut, page 1).

Scope OAuth : sms:contacts:read

Paramètres

Réponses

Exemple 200

{
  "Items": [
    {
      "Id": 1001,
      "Number": "41791234567",
      "FirstName": "Alice",
      "LastName": "Dupont"
    },
    {
      "Id": 1002,
      "Number": "33612345678",
      "FirstName": "Bob",
      "LastName": "Martin"
    }
  ]
}

POST /phone/add.{format}

Ajouter un ou plusieurs numéros de téléphone à une liste

Ajoute un ou plusieurs numéros de téléphone à une liste de contacts.

Numéro unique : utilisez le champ number.

Import en masse : utilisez le champ phone_list avec les numéros séparés par des points-virgules : +41791234567;+33612345678;0049301234567

Les numéros de téléphone acceptent les formats +, 00 ou nu — consultez Format des numéros de téléphone dans la description de l’API pour la liste complète des entrées acceptées / rejetées. Les numéros en doublon sont ignorés silencieusement, sauf si force=1 est positionné.

Scope OAuth : sms:contacts:write

Paramètres

Corps de la requête (application/x-www-form-urlencoded)

Réponses

Exemple 200

{
  "Id": 1003,
  "Number": "0041791234567",
  "FirstName": "Alice",
  "LastName": "Dupont"
}

POST /phone/edit.{format}

Mettre à jour une entrée de numéro de téléphone

Met à jour le numéro de téléphone et/ou les coordonnées d’un contact d’une entrée existante. Utilisez number_id (issu de /phone/list) pour identifier l’entrée à mettre à jour. Seuls les champs fournis dans la requête sont mis à jour.

Scope OAuth : sms:contacts:write

Paramètres

Corps de la requête (application/x-www-form-urlencoded)

Réponses

POST /phone/del.{format}

Retirer un numéro de téléphone d’une liste

Retire définitivement une entrée numéro de téléphone précise de sa liste de contacts. Utilisez number_id (issu de /phone/list) pour identifier l’entrée.

Scope OAuth : sms:contacts:write

Paramètres

Corps de la requête (application/x-www-form-urlencoded)

Réponses

GET /credit/get.{format}

Récupérer le solde de crédits SMS

Retourne le solde de crédits SMS courant pour votre compte. Les crédits SMS sont consommés au moment de l’envoi. Un SMS standard (≤ 160 caractères GSM-7) coûte 1 crédit. Les messages plus longs ou les messages avec des caractères spéciaux peuvent en coûter davantage.

> Note : ceci retourne votre solde de crédits d’envoi SMS, et non votre > quota de requêtes API. Pour le quota d’API, voir GET /account/limits.{format}.

Scope OAuth : sms:read

Paramètres

Réponses

Exemple 200

{
  "TotalCredits": 5000
}

GET /history/list.{format}

Lister l’historique des envois SMS

Retourne un journal paginé de toutes les campagnes SMS passées envoyées depuis ce compte. Les résultats sont triés par date décroissante (les plus récents en premier). Pagination : NumberOfRecords et PageNumber (en-têtes ou query, 5 000 par page par défaut).

Scope OAuth : sms:read

Paramètres

Réponses

Exemple 200

{
  "Items": [
    {
      "Id": 583294,
      "DateSent": "2026-07-17T18:56:39.813",
      "Message": "Your verification code is 8472",
      "Charge": 3,
      "Parts": 1
    }
  ]
}

POST /import/upload.{format}

Téléverser un fichier de numéros de téléphone (CSV / XLSX) pour un import en masse

Téléversez un fichier CSV ou XLSX pour importer des numéros de téléphone dans une liste de contacts. Le fichier est stocké et mis en file d’attente pour un traitement asynchrone — l’endpoint retourne immédiatement un ImportJobId.

Type de requête : multipart/form-data

Champs de formulaire obligatoires :

• id_client (entier) — votre identifiant client Mailpro
• api_key (chaîne) — votre clé d’API
• id_list (entier) — ID de la liste de contacts cible
• file (binaire) — le fichier CSV ou XLSX à téléverser

Optionnel :

• webhook_url (chaîne) — URL HTTPS appelée à la fin du traitement. Reçoit une charge utile JSON contenant le statut final (succès / échec) ainsi que le décompte des lignes importées / ignorées / invalides.

Format du fichier :

• Encodage UTF-8
• Première ligne = en-têtes (l’une doit être Phone ou PhoneNumber — insensible à la casse)
• Numéros au format international (E.164), par exemple +41791234567
• Taille maximale du fichier : 50 Mo

Scope OAuth : sms:contacts:write

Paramètres

Corps de la requête (multipart/form-data)

Réponses

Exemple 200

{
  "Result": "OK",
  "ImportJobId": 15,
  "InternalName": "230575-20260420142616-phones.csv"
}

GET /webhooks

Lister les webhooks

Retourne tous les webhooks configurés sur le compte authentifié.

Réponses

Exemple 200

{
  "items": [
    {
      "id": 14,
      "url": "https://example.com/hooks/mailpro",
      "description": "Intégration Slack",
      "is_active": true,
      "created_at": "2026-07-01T21:09:52.43",
      "updated_at": "2026-07-21T18:56:08.02",
      "last_delivery_at": "2026-07-21T18:56:07.653",
      "last_delivery_status": 200,
      "consecutive_failures": 0,
      "events": [
        "sms.delivered",
        "sms.failed"
      ]
    }
  ],
  "total": 1
}

POST /webhooks

Créer un webhook

Crée un nouvel abonnement webhook. La réponse contient un secret affiché une seule fois — stockez-le immédiatement, côté serveur. Utilisez-le pour vérifier la signature HMAC de chaque charge utile entrante.

Limites : max. 20 webhooks par compte, max. 50 évènements par webhook.

Corps de la requête (application/json)

Exemple

{
  "url": "https://example.com/hooks/mailpro",
  "events": [
    "sms.delivered",
    "sms.failed"
  ],
  "description": "Intégration Slack"
}

Réponses

Exemple 201

{
  "id": 42,
  "url": "https://example.com/hooks/mailpro",
  "events": [
    "sms.delivered",
    "sms.failed"
  ],
  "description": "Intégration Slack",
  "isActive": true,
  "consecutiveFailures": 0,
  "autoDisabledAt": null,
  "autoDisabledReason": null,
  "createdAt": "2026-05-25T10:00:00Z",
  "updatedAt": "2026-05-25T10:00:00Z",
  "secret": "whsec_AbcD1234EfgH5678IjkL9012MnoP3456QrsT"
}

GET /webhooks/{id}

Récupérer un webhook

Paramètres

Réponses

PUT /webhooks/{id}

Mettre à jour un webhook

Mise à jour partielle — seuls les champs transmis sont modifiés.

Paramètres

Corps de la requête (application/json)

Réponses

DELETE /webhooks/{id}

Supprimer un webhook

Supprime définitivement le webhook ainsi que l’intégralité de son historique de livraisons.

Paramètres

Réponses

POST /webhooks/{id}/test

Envoyer un évènement de test

Met en file d’attente un évènement ping immédiat (ou tout autre type d’évènement via le champ eventType du corps) vers votre endpoint. Utile pour vérifier l’accessibilité et la vérification de signature avant de s’appuyer sur de vrais évènements.

Paramètres

Corps de la requête (application/json)

Exemple

{
  "eventType": "ping"
}

Réponses

Exemple 202

{
  "deliveryId": 1234,
  "eventId": "evt_8f3a9b2c4d1e5f6789abcdef01234567",
  "eventType": "ping"
}

POST /webhooks/{id}/rotate-secret

Faire pivoter le secret HMAC

Génère un nouveau secret HMAC et invalide immédiatement l’ancien. Le nouveau secret est retourné une seule fois dans la réponse — stockez-le. Toute livraison à partir de ce moment sera signée avec le nouveau secret.

Utilisez ceci si vous soupçonnez que votre secret a été compromis.

Paramètres

Réponses

Exemple 200

{
  "secret": "whsec_XyzA9876BcdE5432FghI1098JklM7654NopQ"
}

GET /webhooks/{id}/deliveries

Lister les tentatives de livraison

Retourne l’historique des tentatives d’expédition pour ce webhook (rétention de 30 jours). Utile pour le débogage — quels évènements ont été envoyés, codes de statut reçus, nombre de réessais, messages d’erreur.

Paramètres

Réponses

POST /webhooks/{id}/deliveries/{deliveryId}/replay

Rejouer une livraison

Met en file d’attente une nouvelle tentative de livraison avec la même charge utile que l’originale. Utile pour redéclencher une livraison en échec après avoir corrigé votre endpoint. Une NOUVELLE ligne Webhook_Delivery est créée (l’originale est préservée à des fins d’audit). Le rejeu suit la politique de réessai standard (même planning de backoff, même règle de désactivation automatique après 10 échecs).

Paramètres

Réponses