API CRM Mailpro™ v3 : Référence

POST /token

Obtenir un jeton d’accès

Obtient un jeton Bearer JWT à partir des identifiants client. Transmettez l’access_token renvoyé sous la forme Authorization: Bearer <token> dans toutes les requêtes suivantes.

Grant types 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 obtenir un nouveau jeton d’accès sans vous ré-authentifier — votre SDK devrait le faire automatiquement lorsque le jeton d’accès approche de son expiration (stratégie habituelle : rafraîchir lorsqu’il reste moins de 24 h).

Stocker les jetons en toute sécurité

Même avec une durée de vie de 30 jours, quiconque obtient un access_token peut se faire passer pour votre compte jusqu’à son expiration. Stockez les jetons dans un gestionnaire de secrets côté serveur (Vault, AWS Secrets Manager, Azure Key Vault, variables d’environnement sur un hôte durci). N’incorporez jamais un jeton dans :

• du JavaScript côté client ni dans un bundle navigateur
• des applications mobiles distribuées aux utilisateurs (le binaire peut être inspecté)
• des dépôts Git publics ou des journaux de build CI

Si un jeton est divulgué, révoquez-le depuis les paramètres de votre compte Mailpro et demandez-en un nouveau.

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/Me

Obtenir les détails du compte

Renvoie les informations de profil et les paramètres du compte Mailpro authentifié.

Réponses

GET /Account/Credits

Obtenir le solde de crédits

Renvoie le solde de crédits e-mail et SMS restant pour le compte.

Réponses

Exemple 200

{
  "email_credits": 48500,
  "sms_credits": 1200
}

GET /Account/SubscriptionEndDate

Obtenir la date de fin d’abonnement

Renvoie la date d’expiration de l’abonnement Mailpro en cours.

Réponses

GET /Account/Limits

Obtenir le quota d’API mensuel

Renvoie le quota mensuel de requêtes API pour le client authentifié.

Calcul du quota : la limite est calibrée à partir des crédits d’abonnement e-mail (typiquement subscription_credits × 5). Pour un forfait de 10 000 e-mails/mois, cela donne un budget de 50 000 requêtes mensuelles. La correspondance exacte est définie par la tâche de facturation lors de la souscription à l’abonnement et réinitialisée à la date anniversaire de l’abonnement (et non au 1er du mois calendaire).

Ce qui consomme des crédits :

• Toute requête API authentifiée vers les endpoints v2, v3 ou sms (chaque appel = 1 crédit, quel que soit le résultat — les codes 2xx et la plupart des erreurs métier 4xx sont décomptés).
• Chaque événement webhook dispatché vers un endpoint souscrit (ex. contact.created envoyé à votre webhook souscrit = 1 crédit en plus de l’appel API qui l’a déclenché).

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

• Les endpoints /health (supervision).
• Les requêtes qui échouent avec 401 (échec d’authentification), 403 (interdit) ou 429 (limitation de débit).
• Les événements webhook pour les clients sans souscription correspondante (court-circuit en cache — aucun impact sur le quota).

Réponses

POST /Contact

Créer un contact

Crée un nouveau contact CRM avec champs personnalisés, affectations à des listes et tags facultatifs.

Obligatoire :

• email — doit être unique au sein du compte
• lists — au moins une affectation à une liste est obligatoire

Les numéros de téléphone acceptent les formats +41…, 0041… ou 41… avec ou sans séparateurs (12 chiffres max sur Contact — voir Format des numéros de téléphone dans la description de l’API).

Les champs personnalisés sont identifiés par leur id (issu de GET /Field). Les valeurs sont validées par rapport au type du champ.

Scope OAuth : contacts:write

Corps de la requête (application/json)

Exemple

{
  "email": "[email protected]",
  "phone_number": "+41791234567",
  "lists": [
    {
      "id": 101
    }
  ],
  "tags": [
    {
      "id": 5
    }
  ],
  "custom_fields": [
    {
      "id": 1,
      "value": "Alice"
    },
    {
      "id": 2,
      "value": "Dupont"
    }
  ]
}

Réponses

Exemple 406

{
  "Message": "Contact cannot be created. A contact already exist with the same Email"
}

POST /Contact/Multiple

Importer des contacts (en masse)

Crée jusqu’à 1 000 contacts en une seule requête pour un import en masse efficace. La réponse inclut la liste des contacts créés avec succès et la liste des erreurs pour les contacts n’ayant pas pu être créés (ex. e-mail en doublon, données invalides).

Remarque : les listes et tags utilisés lors d’imports en masse ne doivent pas être liés à des workflows d’automatisation actifs. Si c’est le cas, l’import entier est rejeté avec un HTTP 406.

Scope OAuth : contacts:write

Corps de la requête (application/json)

Exemple

[
  {
    "email": "[email protected]",
    "lists": [
      {
        "id": 101
      }
    ],
    "custom_fields": [
      {
        "id": 1,
        "value": "Alice"
      }
    ]
  },
  {
    "email": "[email protected]",
    "lists": [
      {
        "id": 101
      }
    ],
    "custom_fields": [
      {
        "id": 1,
        "value": "Bob"
      }
    ]
  }
]

Réponses

Exemple 200

{
  "Added": [
    {
      "Email": "[email protected]",
      "Id": "550e8400-e29b-41d4-a716-446655440000"
    },
    {
      "Email": "[email protected]",
      "Id": "660e8400-e29b-41d4-a716-446655440001"
    }
  ],
  "Errors": []
}

GET /Contact/{id}

Obtenir un contact

Renvoie les détails d’un contact spécifique. Utilisez includeTags=true pour renvoyer également les tags affectés au contact. Utilisez includeLists=true pour renvoyer également les listes auxquelles le contact appartient.

Scope OAuth : contacts:read

Paramètres

Réponses

Exemple 200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "phone_number": "41791234567",
  "custom_fields": [
    {
      "id": 1,
      "value": "Alice"
    },
    {
      "id": 2,
      "value": "Dupont"
    }
  ],
  "tags": [
    {
      "id": 5
    }
  ],
  "lists": [
    {
      "id": 101
    }
  ]
}

PUT /Contact/{id}

Mettre à jour un contact

Met à jour l’e-mail, le numéro de téléphone, les champs personnalisés, les affectations aux listes et les tags d’un contact. Le corps de la requête remplace les données actuelles du contact — incluez toutes les listes et tous les tags auxquels vous souhaitez que le contact reste affecté.

Obligatoire dans le corps : email et au moins une entrée lists.

Scope OAuth : contacts:write

Paramètres

Corps de la requête (application/json)

Réponses

Exemple 200

{
  "Result": "Successful operation"
}

DELETE /Contact/{id}

Supprimer un contact

Supprime définitivement un contact du CRM.

Scope OAuth : contacts:write

Paramètres

Réponses

GET /Contact/{id}/Activity

Activité d'un contact sur 90 jours

E-mails reçus, ouverts et cliqués, messagerie préférée et dernières campagnes du contact.

Scope OAuth : contacts:read

Paramètres

Réponses

Exemple 200

{
  "period_days": 90,
  "email_received": 12,
  "email_opened": 7,
  "email_clicked": 2,
  "favorite_email_client": "Gmail",
  "last_campaigns": [
    {
      "id": 5001,
      "name": "Spring Sale 2026",
      "date": "2026-10-01T09:00:00"
    }
  ]
}

PUT /Contact/{id}/Tag/{tagid}

Ajouter un tag à un contact

Affecte un tag à un contact. Si le tag est déjà affecté, l’opération est sans effet.

Scope OAuth : contacts:write

Paramètres

Réponses

DELETE /Contact/{id}/Tag/{tagid}

Retirer un tag d’un contact

Supprime l’affectation d’un tag à un contact.

Scope OAuth : contacts:write

Paramètres

Réponses

PUT /Contact/{id}/List/{listid}

Ajouter un contact à une liste

Ajoute un contact à une liste spécifique. Renvoie HTTP 404 si le contact s’est précédemment désinscrit de cette liste.

Scope OAuth : contacts:write

Paramètres

Réponses

DELETE /Contact/{id}/List/{listid}

Retirer un contact d’une liste

Retire un contact d’une liste spécifique. Le contact lui-même n’est pas supprimé.

Scope OAuth : contacts:write

Paramètres

Réponses

GET /List

Lister les listes de contacts

Renvoie toutes les listes de contacts du compte. Filtrez par nom ou par date de création. Triez par ordre alphabétique avec sortByName=true. Incluez le nombre total de contacts par liste avec includeTotalContacts=true.

Scope OAuth : contacts:read

Paramètres

Réponses

Exemple 200

[
  {
    "id": 101,
    "name": "Newsletter subscribers",
    "total_contacts": 4521,
    "date_creation": "2025-01-15T10:30:00"
  }
]

POST /List

Créer une liste de contacts

Crée une nouvelle liste de contacts. Maximum 1 000 listes par compte.

Scope OAuth : contacts:write

Corps de la requête (application/json)

Exemple

{
  "name": "Spring Campaign 2026"
}

Réponses

Exemple 200

{
  "id": 102,
  "name": "Spring Campaign 2026",
  "date_creation": "2026-04-14T12:00:00"
}

GET /List/{id}

Obtenir une liste de contacts

Renvoie les détails d’une liste de contacts spécifique.

Scope OAuth : contacts:read

Paramètres

Réponses

PUT /List/{id}

Mettre à jour une liste de contacts

Renomme une liste de contacts existante.

Scope OAuth : contacts:write

Paramètres

Corps de la requête (application/json)

Exemple

{
  "name": "Newsletter subscribers — Europe"
}

Réponses

DELETE /List/{id}

Supprimer une liste de contacts

Supprime définitivement une liste de contacts. Les contacts eux-mêmes ne sont pas supprimés — seule leur appartenance à cette liste est retirée. Les listes utilisées par des workflows d’automatisation actifs ne peuvent pas être supprimées.

Scope OAuth : contacts:write

Paramètres

Réponses

GET /List/{id}/Contact

Lister les contacts d’une liste

Renvoie les contacts appartenant à une liste spécifique. Filtrez par e-mail ou date d’ajout. Incluez les tags et appartenances aux listes via les indicateurs correspondants.

Scope OAuth : contacts:read

Paramètres

Réponses

GET /List/{listId}/Unsubscribers

Lister les désinscrits

Renvoie les contacts qui se sont désinscrits d’une liste spécifique.

Scope OAuth : contacts:read

Paramètres

Réponses

GET /Tag

Lister les tags

Renvoie tous les tags du compte.

Scope OAuth : contacts:read

Paramètres

Réponses

Exemple 200

[
  {
    "id": 5,
    "name": "VIP customers"
  },
  {
    "id": 6,
    "name": "Newsletter openers"
  }
]

POST /Tag

Créer un tag

Crée un nouveau tag. Maximum 1 000 tags par compte.

Scope OAuth : contacts:write

Corps de la requête (application/json)

Exemple

{
  "name": "VIP customers"
}

Réponses

GET /Tag/{id}

Obtenir un tag

Renvoie un tag spécifique par son identifiant.

Scope OAuth : contacts:read

Paramètres

Réponses

PUT /Tag/{id}

Mettre à jour un tag

Renomme un tag existant.

Scope OAuth : contacts:write

Paramètres

Corps de la requête (application/json)

Exemple

{
  "name": "VIP customers — updated"
}

Réponses

DELETE /Tag/{id}

Supprimer un tag

Supprime définitivement un tag. Le tag est retiré de tous les contacts. Les tags utilisés par des workflows d’automatisation actifs ne peuvent pas être supprimés.

Scope OAuth : contacts:write

Paramètres

Réponses

GET /Tag/{id}/Contact

Lister les contacts portant un tag

Renvoie les contacts auxquels un tag spécifique a été affecté.

Scope OAuth : contacts:read

Paramètres

Réponses

GET /Field

Lister les champs personnalisés

Renvoie tous les champs personnalisés de contact définis pour le compte. Utilisez les valeurs id renvoyées lors de la création ou de la mise à jour de contacts.

Paramètres

Réponses

Exemple 200

[
  {
    "id": 1,
    "name": "first_name",
    "personalisation_key": "first_name",
    "field_type": "text"
  },
  {
    "id": 2,
    "name": "last_name",
    "personalisation_key": "last_name",
    "field_type": "text"
  }
]

POST /Field

Créer un champ personnalisé

Crée un nouveau champ personnalisé de contact. Maximum 50 champs par compte. Utilisez l’id renvoyé lors de l’affectation de valeurs aux contacts.

Corps de la requête (application/json)

Exemple

{
  "name": "First name",
  "id_field_type": 1,
  "personalize_key": "first_name"
}

Réponses

GET /Field/Types

Lister les types de champs

Renvoie les identifiants de types de champs disponibles à utiliser lors de la création d’un champ personnalisé. Types courants : 1 = texte, 2 = nombre, 3 = date.

Réponses

GET /Field/{id}

Obtenir un champ personnalisé

Renvoie la définition et les métadonnées d’un champ personnalisé spécifique.

Paramètres

Réponses

PUT /Field/{id}

Mettre à jour un champ personnalisé

Met à jour le nom ou la clé de personnalisation d’un champ personnalisé.

Paramètres

Corps de la requête (application/json)

Réponses

DELETE /Field/{id}

Supprimer un champ personnalisé

Supprime définitivement un champ personnalisé et retire sa valeur de tous les contacts. Cette action est irréversible.

Paramètres

Réponses

GET /Campaign

Lister les campagnes

Renvoie une liste paginée des campagnes e-mail du compte.

Paramètres

Réponses

Exemple 200

[
  {
    "id": 8001,
    "title": "Spring Newsletter April 2026",
    "date_planned": "2026-04-20T09:00:01",
    "count_open": 1823,
    "count_sent": 4521,
    "count_click": 342,
    "count_badmail": 12,
    "count_unsubscription": 8,
    "count_clicking_users": 289,
    "count_complaints": 1,
    "spam_trap": 0,
    "deliverability_score": 98
  }
]

GET /Campaign/{id}

Obtenir une campagne

Renvoie la configuration et un résumé des statistiques d’une campagne spécifique.

Paramètres

Réponses

PUT /Campaign/{id}

Mettre à jour une campagne

Met à jour le titre ou la date d’envoi d’une campagne planifiée. Les campagnes ne peuvent être modifiées que jusqu’à 5 minutes avant l’heure d’envoi planifiée.

Paramètres

Corps de la requête (application/json)

Réponses

DELETE /Campaign/{id}

Supprimer une campagne

Annule et supprime définitivement une campagne par son identifiant.

Paramètres

Réponses

GET /Campaign/Scheduled

Lister mes campagnes planifiées

Renvoie les campagnes dont la date_planned est dans le futur et qui n’ont pas encore été expédiées. Triées par date_planned croissante.

Paramètres

Réponses

Exemple 200

[
  {
    "id": 5001,
    "id_client": 12345,
    "subject": "Spring Sale 2026",
    "date_planned": "2026-05-01T09:00:00",
    "title": "Spring Sale",
    "id_campaign": 7001,
    "id_list": 101,
    "id_segment": null,
    "number_email": 1250
  }
]

POST /Campaign/{id}/Cancel

Annuler une campagne planifiée

Annule une campagne planifiée dans le futur. Renvoie 409 Conflict si la campagne a déjà été expédiée ou n’existe pas.

Paramètres

Réponses

Exemple 200

{
  "result": "ok",
  "cancelled": 5001
}

PATCH /Campaign/{id}/Reschedule

Replanifier une campagne planifiée

Met à jour la date d’envoi planifiée d’une campagne planifiée. La nouvelle date doit être dans le futur et dans les 90 jours.

Nom du champ du corps : l’API accepte date_planned (snake_case, principal) ainsi que les alias historiques PlanDate et scheduled_time. Fournissez l’un quelconque d’entre eux — le premier non null est utilisé.

Paramètres

Corps de la requête (application/json)

Réponses

Exemple 200

{
  "result": "ok",
  "id": 5001,
  "date_planned": "2026-12-31T14:30:00"
}

GET /Campaign/{id}/ByHour

Statistiques par heure

Renvoie la répartition horaire des ouvertures et des clics pour la campagne.

Paramètres

Réponses

GET /Campaign/{id}/ByDay

Statistiques par jour

Renvoie la répartition quotidienne des ouvertures et des clics pour la campagne.

Paramètres

Réponses

GET /Campaign/{id}/Openings

Lister les ouvertures d’e-mail

Renvoie une liste paginée des contacts ayant ouvert l’e-mail de la campagne.

Paramètres

Réponses

GET /Campaign/{id}/Clicks

Lister les clics sur les liens

Renvoie une liste paginée des contacts ayant cliqué sur un lien dans la campagne.

Paramètres

Réponses

GET /Campaign/{id}/HardBounces

Lister les hard bounces

Renvoie les adresses e-mail ayant fait l’objet d’un hard bounce lors de cette campagne.

Paramètres

Réponses

GET /Campaign/{id}/Links

Lister les liens suivis

Renvoie les données de performance des clics pour chaque lien suivi dans la campagne.

Paramètres

Réponses

GET /Campaign/{id}/OS

Statistiques par OS / appareil

Renvoie la répartition des ouvertures et des clics par système d’exploitation et type d’appareil.

Paramètres

Réponses

GET /Campaign/{id}/EmailClients

Statistiques par client de messagerie

Renvoie la répartition des ouvertures par client de messagerie (Gmail, Outlook, Apple Mail…).

Paramètres

Réponses

GET /Campaign/{id}/Countries

Statistiques par pays

Renvoie la répartition géographique des ouvertures et des clics.

Paramètres

Réponses

POST /Send/Mail

Envoyer un e-mail transactionnel

Envoie un e-mail transactionnel ponctuel à un destinataire unique.

Destinataire : fournissez email (adresse en ligne) OU id_contact (contact CRM) — pas les deux. Utiliser id_contact permet la personnalisation automatique avec les valeurs des champs personnalisés du contact.

Contenu : fournissez body_html (HTML en ligne) OU id_message (modèle enregistré) — pas les deux. Si les deux sont fournis, id_message est prioritaire.

Obligatoire : id_sender_email, subject, et l’un de (email ou id_contact), ainsi que l’un de (body_html ou id_message).

Corps de la requête (application/json)

Exemple

{
  "id_sender_email": 201,
  "email": "[email protected]",
  "subject": "Your order #12345 has shipped",
  "body_html": "<p>Hello {{first_name}}, your order is on its way!</p>",
  "reply_to": "[email protected]",
  "fields": [
    {
      "id": 1,
      "value": "Alice"
    }
  ],
  "attachments": [
    {
      "filename": "invoice.pdf",
      "content": "JVBERi0xLjQKJVBERi0xLjQK..."
    }
  ]
}

Réponses

Exemple 200

{
  "message": "Successful operation",
  "id_single_send": 8001
}

Exemple 404

{
  "Message": "Not enough credit available"
}

GET /Send/{id}/Status

Obtenir le statut de livraison d'un e-mail transactionnel

Renvoie le statut de livraison actuel d'un e-mail transactionnel envoyé via POST /Send/Mail. Transmettez l'id_single_send renvoyé par cet appel.

Valeurs possibles : delivered (accepté par le serveur du destinataire, voir diag_code), bounced (refusé — bounce_type: hard adresse invalide ou refus définitif, soft refus après nouvelles tentatives), sent (remis au serveur de messagerie, pas encore de réponse), scheduled (pas encore envoyé, date_planned dans le futur) et queued (en attente d'expédition). delivered et bounced sont finaux : arrêtez d'interroger. Chaque e-mail a un statut final au plus tard 48 heures après l'envoi ; interrogez toutes les 15 minutes au plus (chaque appel compte dans votre quota API) ou utilisez les webhooks email.delivered / email.bounced. Seul le client qui a envoyé l'e-mail peut lire son statut — tout autre id renvoie 404.

Paramètres

Réponses

Exemple 200

{
  "id_single_send": 8001,
  "email": "[email protected]",
  "status": "delivered",
  "date_planned": "2026-04-15T14:30:00",
  "status_date": "2026-04-15T14:30:07",
  "diag_code": "2.0.0 (success)",
  "bounce_type": null
}

POST /Send/Campaign

Envoyer une campagne e-mail

Envoie une campagne e-mail en masse à une ou plusieurs listes de contacts.

Obligatoire :

• id_message — le modèle à envoyer (issu de GET /Message)
• id_sender_email — l’adresse expéditrice (issue de GET /SenderEmail)
• lists — au moins une liste de contacts cible
• campaign_title — libellé pour le suivi statistique

Segment : filtrez facultativement les destinataires par un segment enregistré (id_segment). Le segment filtre les contacts au sein des listes spécifiées.

Planification : définissez date_planned à une date/heure ISO 8601 future. Les campagnes peuvent être modifiées ou annulées jusqu’à 5 minutes avant l’heure planifiée.

Corps de la requête (application/json)

Exemple

{
  "id_message": 501,
  "id_sender_email": 201,
  "lists": [
    {
      "id": 101
    }
  ],
  "campaign_title": "Spring Newsletter April 2026",
  "date_planned": "2026-04-20T09:00:00"
}

Réponses

Exemple 200

{
  "Message": "Successful operation. Campaigns can be edited or deleted until 5 minutes prior to send.",
  "IdCampaign": 8001
}

GET /Send

Lister les envois planifiés

Renvoie la liste des campagnes e-mail en attente d’envoi (planifiées, pas encore traitées).

Paramètres

Réponses

DELETE /Send/{id}

Annuler un envoi planifié

Annule et supprime un envoi d’e-mail planifié qui n’a pas encore été traité. Ne peut pas annuler des envois en cours de traitement.

Paramètres

Réponses

GET /Send/Mail/Scheduled

Lister les e-mails unitaires programmés

Renvoie les e-mails unitaires envoyés avec POST /Send/Mail et une date future, pas encore partis. Les campagnes sont listées par GET /Campaign/Scheduled.

Scope OAuth : email:send

Réponses

Exemple 200

[
  {
    "id_single_send": 880123,
    "email": "[email protected]",
    "subject": "Your invoice",
    "date_planned": "2026-12-01T09:00:00"
  }
]

POST /Send/Mail/{id}/Cancel

Annuler un e-mail unitaire programmé

Annule l'e-mail tant qu'il n'est pas parti.

Scope OAuth : email:send

Paramètres

Réponses

Exemple 200

{
  "result": "ok",
  "cancelled": 880123
}

PATCH /Send/Mail/{id}/Reschedule

Reprogrammer un e-mail unitaire programmé

Change la date d'envoi. La nouvelle date doit être future et à moins de 90 jours. POST est aussi accepté.

Scope OAuth : email:send

Paramètres

Corps de la requête (application/json)

Réponses

Exemple 200

{
  "result": "ok",
  "id": 880123,
  "date_planned": "2026-12-15T09:00:00"
}

GET /SenderEmail

Lister les adresses expéditrices

Renvoie les adresses e-mail expéditrices validées configurées pour le compte.

Paramètres

Réponses

Exemple 200

[
  {
    "id": 201,
    "email": "[email protected]",
    "sender_name": "Your Company Newsletter",
    "is_validated": true
  }
]

POST /SenderEmail

Ajouter une adresse d'expéditeur

Ajoute l'adresse avec les mêmes contrôles que l'application et lui envoie un e-mail de validation. Elle est utilisable une fois le lien de cet e-mail cliqué. Un compte peut avoir jusqu'à 25 expéditeurs, validés ou en attente.

Scope OAuth : email:templates:write

Corps de la requête (application/json)

Réponses

Exemple 200

{
  "result": "ok",
  "confirmation_sent": true,
  "domain_has_mx": true
}

POST /SenderEmail/{id}/ResendValidation

Renvoyer l'e-mail de validation

Pour une adresse encore en attente de validation.

Scope OAuth : email:templates:write

Paramètres

Réponses

Exemple 200

{
  "result": "ok",
  "confirmation_sent": true
}

GET /SenderEmail/{id}/Authentication

Contrôler le domaine d'un expéditeur (SPF, DKIM, DMARC, MX)

Contrôle le domaine en direct dans le DNS et renvoie les enregistrements à publier. Lecture seule. Le DKIM s'active dans l'application : dkim_settings_url ouvre le bon écran.

Scope OAuth : email:templates:read

Paramètres

Réponses

Exemple 200

{
  "domain": "example.com",
  "spf": {
    "valid": true,
    "record": "v=spf1 include:spf.mailpro.com -all",
    "recommended_record": "v=spf1 include:spf.mailpro.com -all",
    "change_needed": false
  },
  "dkim": {
    "valid": true,
    "records": [
      {
        "host": "key._domainkey.example.com",
        "value": "v=DKIM1;k=rsa;p=MIIBIjANBgkq...",
        "validated": true
      }
    ]
  },
  "dmarc": {
    "valid": true,
    "record": "v=DMARC1; p=quarantine"
  },
  "mx": {
    "valid": true,
    "record": "mail.example.com"
  },
  "dkim_settings_url": "https://app.mailpro.com/dkim/list?d=example.com"
}

GET /History/Email

Lister l’historique des envois d’e-mails

Renvoie l’historique des envois d’e-mails passés pour le compte.

Paramètres

Réponses

GET /History/SMS

Lister l’historique des envois de SMS

Renvoie l’historique des envois de SMS passés pour le compte.

Paramètres

Réponses

GET /Segment

Lister les segments

Renvoie tous les segments dynamiques enregistrés pour le compte.

Scope OAuth : contacts:read

Paramètres

Réponses

GET /Segment/{id}/Contact

Lister les contacts d'un segment

Avec id_list, renvoie seulement les contacts de cette liste qui entrent dans le segment : ceux que toucherait une campagne liste + segment. Le total est dans l'en-tête X-Total-Count.

Scope OAuth : contacts:read

Paramètres

Réponses

GET /Segment/{id}/Count

Compter les contacts d'un segment

Le nombre seul, pour connaître la taille d'un envoi à l'avance. Avec id_list, compte seulement les contacts de cette liste qui entrent dans le segment.

Scope OAuth : contacts:read

Paramètres

Réponses

Exemple 200

{
  "total": 1250
}

GET /Segment/{id}/contact/{contactId}/check

Vérifier si un contact correspond à un segment

Vérifie si un contact spécifique (par GUID) correspond actuellement aux règles d’un segment donné. Utile pour déclencher de la logique d’automatisation à la demande.

Scope OAuth : contacts:read

Paramètres

Réponses

POST /Sms/SingleSMS

Envoyer un SMS unique

Envoie un SMS unique vers un numéro de téléphone directement. Utilisez-le pour les messages transactionnels (OTP, confirmations de commande, alertes). Le numéro de téléphone accepte les formats +41…, 0041… ou 41… avec ou sans séparateurs — voir Format des numéros de téléphone dans la description de l’API pour les entrées acceptées / rejetées.

Corps de la requête (application/json)

Exemple

{
  "phone_number": "+41791234567",
  "message": "Your verification code is 9473. Valid for 10 minutes."
}

Réponses

POST /Sms/Campaign

Envoyer une campagne SMS

Envoie un message SMS au champ phone_number de tous les contacts d’une ou plusieurs listes. Les contacts sans numéro de téléphone sont ignorés.

Corps de la requête (application/json)

Exemple

{
  "lists": [
    {
      "id": 101
    }
  ],
  "message": "Flash sale today — 20% off. Shop at mailpro.com",
  "date_planned": "2026-04-20T10:00:00"
}

Réponses

GET /Sms

Lister l’historique des SMS

Renvoie l’historique des envois de SMS (à la fois unitaires et par campagne) pour le compte.

Paramètres

Réponses

DELETE /Sms/{id}

Annuler un SMS planifié

Annule un envoi de SMS planifié en attente.

Paramètres

Réponses

GET /Sms/Scheduled

Lister les envois de SMS planifiés

Renvoie les envois de SMS avec une date_planned future (pas encore expédiés), triés par date croissante.

Paramètres

Réponses

POST /Sms/{id}/Cancel

Annuler un SMS planifié

Annule un envoi de SMS planifié uniquement s’il n’a pas encore été expédié.

Paramètres

Réponses

PATCH /Sms/{id}/Reschedule

Replanifier un SMS planifié

Met à jour la date d’envoi planifiée d’un SMS planifié. La nouvelle date doit être dans le futur et dans les 90 jours. Échoue si le SMS a déjà été expédié.

Nom du champ du corps : l’API accepte date_planned (snake_case, principal) ainsi que les alias historiques PlanDate et scheduled_time. Fournissez l’un quelconque d’entre eux.

Paramètres

Corps de la requête (application/json)

Réponses

GET /FolderList

Lister les dossiers de listes

Renvoie les dossiers utilisés pour organiser les listes de contacts.

Paramètres

Réponses

GET /FolderList/{id}

Obtenir un dossier de listes unique

Renvoie les détails d’un dossier de listes par son identifiant.

Paramètres

Réponses

GET /FolderMessage

Lister les dossiers de messages

Renvoie les dossiers utilisés pour organiser les modèles de messages e-mail.

Paramètres

Réponses

POST /Import/Upload

Téléverser un fichier de contacts (CSV / XLSX) pour import en masse

Téléversez un fichier CSV ou XLSX pour importer des contacts dans une liste. Le fichier est stocké et mis en file d’attente pour un traitement asynchrone — le endpoint renvoie immédiatement un import_job_id.

Type de requête : multipart/form-data

Champs de formulaire obligatoires :

• id_list (entier) — identifiant de la liste cible
• file (binaire) — le fichier CSV ou XLSX à téléverser
• json_match_fields (chaîne, JSON) — quelle colonne du fichier va dans quel champ du contact. email_position = colonne de l’e-mail, numérotée à partir de 0 (obligatoire), phone_position = colonne du numéro de mobile ou -1, fields = identifiants des autres champs (voir GET /Field), fields_position = colonne de chacun d’eux, update_fields = mettre à jour les contacts existants. Correspondance absente ou invalide : réponse 400, aucun import n’est créé.

Facultatif :

• webhook_url (chaîne) — URL HTTPS appelée à la fin du traitement. Reçoit un payload JSON contenant le statut final (succès / échec) et les nombres de lignes importées / ignorées / invalides.

Format de fichier :

• Encodé en UTF-8
• La première ligne peut contenir les en-têtes (détection automatique : une première ligne sans aucune adresse e-mail est ignorée)
• Les colonnes sont associées aux champs par json_match_fields
• Taille de fichier maximale : 50 Mo

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

Réponses

Exemple 200

{
  "result": "OK",
  "import_job_id": 14,
  "internal_name": "230575-20260420142615-contacts.csv"
}

GET /Webhook

Lister les webhooks

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

Réponses

POST /Webhook

Créer un webhook

Crée une nouvelle souscription webhook. La réponse contient un secret qui est affiché une seule fois — stockez-le immédiatement, côté serveur. Utilisez-le pour vérifier la signature HMAC de chaque payload entrant.

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

Corps de la requête (application/json)

Exemple

{
  "url": "https://example.com/hooks/mailpro",
  "events": [
    "email.delivered",
    "email.bounced",
    "contact.created"
  ],
  "description": "Intégration Slack"
}

Réponses

Exemple 201

{
  "id": 42,
  "url": "https://example.com/hooks/mailpro",
  "events": [
    "email.delivered",
    "email.bounced",
    "contact.created"
  ],
  "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 /Webhook/{id}

Obtenir un webhook

Paramètres

Réponses

PUT /Webhook/{id}

Mettre à jour un webhook

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

Paramètres

Corps de la requête (application/json)

Réponses

DELETE /Webhook/{id}

Supprimer un webhook

Supprime définitivement le webhook et tout son historique de livraisons.

Paramètres

Réponses

POST /Webhook/{id}/test

Envoyer un événement de test

Met en file d’attente un événement ping immédiat (ou n’importe quel 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 des événements réels.

Paramètres

Corps de la requête (application/json)

Exemple

{
  "eventType": "ping"
}

Réponses

Exemple 202

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

POST /Webhook/{id}/rotate-secret

Faire tourner le secret HMAC

Génère un nouveau secret HMAC et invalide immédiatement l’ancien. Le nouveau secret est renvoyé 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 suspectez que votre secret a été compromis.

Paramètres

Réponses

Exemple 200

{
  "secret": "whsec_XyzA9876BcdE5432FghI1098JklM7654NopQ"
}

GET /Webhook/{id}/deliveries

Lister les tentatives de livraison

Renvoie 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, nombres de tentatives, messages d’erreur.

Paramètres

Réponses

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

Rejouer une livraison

Met en file d’attente une nouvelle tentative de livraison avec le même payload que l’original. Utile pour redéclencher une livraison ayant échoué après avoir corrigé votre endpoint. Une NOUVELLE ligne Webhook_Delivery est créée (l’original est conservé pour audit). Le rejeu suit la politique de relance standard (10 s → 1 min → 5 min → 30 min → 2 h → 6 h → 24 h, puis abandon).

Paramètres

Réponses

GET /Suppression/Bounces

Lister les bounces du compte

Les plus récents d'abord. Le total est dans l'en-tête X-Total-Count.

Scope OAuth : email:read

Paramètres

Réponses

Exemple 200

[
  {
    "id": 5521,
    "source": "contact",
    "type": "hard",
    "email": "[email protected]",
    "date": "2026-10-12T08:30:00",
    "diag_code": "550 5.1.1 User unknown",
    "id_list": 101
  }
]

DELETE /Suppression/Bounces/{id}

Retirer un bounce

source et type sont obligatoires, tels que renvoyés par GET /Suppression/Bounces : un id seul n'est pas unique.

Scope OAuth : contacts:write

Paramètres

Réponses

Exemple 200

{
  "result": "ok",
  "id": 5521,
  "restored": false
}

POST /Suppression/Bounces/{id}/Restore

Remettre en liste un contact en hard bounce

Uniquement pour un hard bounce de source contact.

Scope OAuth : contacts:write

Paramètres

Réponses

Exemple 200

{
  "result": "ok",
  "id": 5521,
  "restored": true
}

GET /Suppression/Unsubscribers

Lister les désinscrits du compte

Les plus récents d'abord. Le total est dans l'en-tête X-Total-Count.

Scope OAuth : contacts:read

Paramètres

Réponses

Exemple 200

[
  {
    "id": 9012,
    "source": "api3",
    "email": "[email protected]",
    "date": "2026-10-20T16:05:00",
    "list_name": null,
    "comment": "Asked by phone"
  }
]

POST /Suppression/Unsubscribers

Ajouter un désinscrit

Sans id_list, l'adresse est désinscrite pour tout le compte. Avec, de cette liste de désinscription seulement.

Scope OAuth : contacts:write

Corps de la requête (application/json)

Réponses

Exemple 200

{
  "result": "ok",
  "already_unsubscribed": false
}

DELETE /Suppression/Unsubscribers/{id}

Retirer un désinscrit

source est obligatoire, tel que renvoyé par GET /Suppression/Unsubscribers : un id seul n'est pas unique.

Scope OAuth : contacts:write

Paramètres

Réponses

Exemple 200

{
  "result": "ok",
  "removed": 9012
}