Documentation interactive · Portail développeurs · Spécification OpenAPI · EN · FR · DE · IT · PT · ES
URL de base : https://api.mailpro.com/v2
L'API Email Mailpro™ v2 vous permet de gérer par programmation les listes de contacts, les modèles d'e-mail, les adresses d'expéditeur et les campagnes — et d'envoyer des e-mails de masse comme transactionnels.
Chaque endpoint accepte trois méthodes d'authentification. Utilisez celle qui convient à votre stack.
POST /token, sans scopes.> Le Bearer JWT legacy et IdClient+ApiKey continuent de fonctionner sans changement et ne sont pas > soumis aux scopes. Seuls les tokens d'accès OAuth 2.0 sont soumis aux contrôles de scope par endpoint > indiqués sur chaque opération ci-dessous.
Mailpro exploite un seul serveur d'autorisation OAuth 2.0 pour toutes ses API, sur une surface unique, indépendante de la version : https://api.mailpro.com/oauth/. Il n'existe pas d'endpoint OAuth par version — vous obtenez un token via /oauth/token et le même token fonctionne sur cette API Email v2, sur CRM v3 et sur SMS. Les endpoints qu'il peut appeler dépendent des scopes du token, pas de l'URL de base de l'API. Émetteur (claim iss) : https://api.mailpro.com/oauth/.
| Endpoint | URL |
|---|---|
| Autorisation | GET https://api.mailpro.com/oauth/authorize |
| Token / renouvellement | POST https://api.mailpro.com/oauth/token |
| JWKS | GET https://api.mailpro.com/oauth/.well-known/jwks |
| Découverte | GET https://api.mailpro.com/oauth/.well-known/openid-configuration |
Grants : authorization_code + PKCE (S256, obligatoire), client_credentials, refresh_token (rotation). Durée du token d'accès : 20 min ; token de rafraîchissement : 30 jours (glissants, à usage unique) ; code d'autorisation : 60 s.
Démarrage rapide — obtenir un token et appeler cette API (remplacez les valeurs ; ne commitez jamais un vrai secret) :
curl -X POST https://api.mailpro.com/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "scope=email:send email:read"Appelez ensuite cette API avec Authorization: Bearer ACCESS_TOKEN. Le même token fonctionne sur les API CRM v3 et SMS. Un token auquel il manque le scope exigé par un endpoint reçoit 403 insufficient_scope. Parcours complet et catalogue des scopes : voir la documentation de l'API CRM v3 › Authentification. Scopes utiles pour l'e-mail : email:send, email:read, email:templates:read, email:templates:write, contacts:read, contacts:write, account:read.
Authorization: Bearer <access_token>Obtenez un token via POST /token (encodé en formulaire, OAuth2 password grant) :
POST https://api.mailpro.com/v2/token
Content-Type: application/x-www-form-urlencoded
grant_type=password&username=YOUR_USERNAME&password=YOUR_API_KEYLe même token est également valide sur l'API CRM v3 et l'API SMS — authentifiez-vous une seule fois, appelez n'importe quelle API. Les tokens sont valides 30 jours par défaut ; utilisez grant_type=refresh_token pour les renouveler sans devoir vous réauthentifier. Sans scopes — préférez OAuth 2.0 pour les intégrations installables.
Deux identifiants :
| Paramètre | Type | Description |
|---|---|---|
IdClient | entier | Votre identifiant client numérique Mailpro, accessible dans Paramètres → Accès API |
ApiKey | chaîne | Votre clé API, accessible dans Paramètres → Accès API |
Transmettez-les à l'un de ces emplacements — choisissez-en un :
IdClient: 12345 et ApiKey: a1b2c3d4-…. Les URL sont journalisées par les serveurs web, CDN et proxys, donc une clé placée dans la query string peut fuiter dans les journaux d'accès. Les en-têtes ne sont pas journalisés.?IdClient=12345&ApiKey=…. Conservé pour la rétrocompatibilité avec les intégrations existantes. Migrez vers les en-têtes dès que possible.IdClient=12345&ApiKey=… en application/x-www-form-urlencoded.Si vous fournissez les identifiants à plusieurs endroits, l'en-tête l'emporte.
Pour les tokens émis par OAuth, chaque groupe d'endpoints exige un scope (l'authentification legacy en est dispensée). Chaque opération indique son scope sous Authorization. Résumé :
| Endpoints | Scope requis |
|---|---|
/send/* (campagnes, transactionnel, planification, test — sauf /send/{IdSend}/status) | email:send |
/stats/* (sauf /stats/del), /history/list, /send/{IdSend}/status | email:read |
/message/*, /senderEmail/* (lecture) | email:templates:read |
/message/*, /senderEmail/* (add/edit/del), /stats/del | email:templates:write |
/list/list, /email/list | contacts:read |
/list/{add,edit,del}, /email/{add,addSingle,edit,del}, /import/upload | contacts:write |
/account/* | account:read |
Un refus de scope renvoie 403 avec { "error": "insufficient_scope", "required_scope": "…" }.
Tous les endpoints prennent en charge json (par défaut) et xml. Précisez le format dans l'URL :
/email/list.json/email/list.xmlMême règle sur les trois API Mailpro (Email v2, CRM v3, SMS) : 5 000 éléments par page, par défaut comme au maximum.
numberOfRecords — éléments par page. Absent, 0 ou au-delà de 5 000 = 5 000.pageNumber — numéro de page à partir de 1 (par défaut 1).bodyHTML=true) renvoient 10 éléments par page./email/list ajoute X-Total-Count (le total réel) et X-Truncated: true quand il reste des contacts au-delà de la page.Paramètres inconnus : ils sont ignorés, jamais refusés. Quand une requête porte un paramètre que l'API ne reconnaît pas, la réponse contient X-Ignored-Parameters (les noms) et X-Documentation (un lien vers cette page), pour qu'une faute de frappe ne passe pas inaperçue.
| HTTP | Signification |
|---|---|
| 400 | Requête incorrecte — paramètre obligatoire manquant ou invalide |
| 401 | Non autorisé — IdClient ou ApiKey invalide |
| 403 | Interdit — limite du compte atteinte (par exemple, nombre maximal de listes) |
| 404 | Introuvable — la ressource demandée n'existe pas |
| 500 | Erreur interne du serveur |
Erreurs liées aux règles métier :
"Not enough credit available." → 403 — votre compte n'a plus de crédits e-mail disponibles"Email address unsubscribed." → 400 — le destinataire s'est désabonnéChaque e-mail unitaire envoyé (POST /send/sendmail, l'API CRM v3, le relais SMTP ou une automation) reçoit un identifiant. Il peut être suivi jusqu'à ce que le serveur du destinataire l'accepte ou le refuse. Les campagnes ne sont pas concernées : utilisez les statistiques.
POST /send/sendmail.{format} contient l'identifiant de l'envoi.email.delivered et email.bounced envoient le statut final à votre serveur dès qu'il est connu, sans aucune interrogation.GET /send/{IdSend}/status.{format} rend le statut du moment (tableau ci-dessous).status | Signification | Final ? |
|---|---|---|
queued | Accepté, en attente d'expédition. | non |
scheduled | Planifié pour plus tard (DatePlanned). | non |
sent | Remis par nos serveurs, pas encore de réponse du serveur du destinataire. | non |
delivered | Accepté par le serveur du destinataire (DiagCode = sa réponse SMTP). | oui |
bounced | Refusé. BounceType : hard = adresse invalide ou refus définitif ; soft = refus après nouvelles tentatives (boîte pleine, serveur injoignable…). | oui |
not_found | Identifiant inconnu ou qui n'appartient pas à votre compte. | oui |
Interroger sans boucler
delivered apparaît environ 5 minutes après la remise.Retry-After (le nombre de secondes à attendre), et l'appel ne compte pas dans votre quota.scheduled : inutile d'interroger avant DatePlanned.Les statuts sont conservés 365 jours.
Mailpro™ peut notifier votre serveur en temps réel lorsque certains événements se produisent sur votre compte (un e-mail est délivré, une campagne se termine, un contact rebondit, etc.). Façon Stripe — votre URL reçoit un POST signé en HMAC-SHA256 dès que l'événement est déclenché.
Chaque événement envoyé à votre webhook compte pour 1 requête dans votre quota de requêtes API.
POST /webhooks. La réponse contient un secret affiché une seule fois (façon Stripe / GitHub) — conservez-le.secret (extraits ci-dessous).> ⏱ Délai d'activation — après création, mise à jour ou suppression d'un webhook, la > modification met jusqu'à 10 minutes à se propager sur l'ensemble des serveurs > de l'API Mailpro. Pendant cette fenêtre, les événements peuvent ne pas encore correspondre à votre nouvel abonnement > (ou peuvent toujours correspondre à un abonnement qui vient d'être retiré). C'est le temps nécessaire pour > rafraîchir le cache d'abonnements en mémoire sur chaque instance de l'API.
Tous les événements partagent une enveloppe commune :
{
"id": "evt_8f3a9b2c4d1e5f6789abcdef01234567",
"type": "email.delivered",
"created": 1748194800,
"apiVersion": "v2",
"account": { "id": 12345, "name": "ACME Corp" },
"data": { "messageId": "...", "email": "[email protected]", "...": "..." }
}| Champ | Format | Description |
|---|---|---|
id | evt_ + 32 hex | Identifiant unique de l'événement — à utiliser comme clé d'idempotence de votre côté. |
type | <domain>.<verb> | Type d'événement canonique. |
created | Secondes Unix UTC | Inclus dans la signature HMAC. |
apiVersion | "v2" | L'API Mailpro qui a publié l'événement. |
account.id | int | Votre identifiant client Mailpro (= IdClient). |
account.name | string | Le nom de votre compte (pratique pour le débogage côté client). |
data | object | Charge utile de l'événement — sa structure dépend du type (voir le catalogue ci-dessous). |
| Événement | Déclencheur | Structure de data |
|---|---|---|
ping | Test via POST /webhooks/{id}/test | { message } |
email.processed | Envoi accepté par le pipeline | { messageId, email, campaignId, processedAt } |
email.delivered | Un email unitaire a été accepté par le serveur destinataire — API v2/v3, SMTP ou Automation (pas les campagnes). Émis depuis le flux de livraison PowerMTA. | { messageId, email, idSending, sendingType, diagCode, deliveredAt } |
email.opened | Pixel de tracking déclenché | { messageId, email, campaignId, openedAt, ip, userAgent } |
email.clicked | Clic sur un lien tracké | { messageId, email, campaignId, clickedAt, url, ip, userAgent } |
email.bounced | Rebond dur ou souple | { messageId, email, campaignId, bouncedAt, bounceType, reason } |
email.spam_report | Plainte FBL | { messageId, email, campaignId, reportedAt } |
email.unsubscribed | Lien de désinscription cliqué | { messageId, email, campaignId, unsubscribedAt } |
email.dropped | Refusé avant envoi | { messageId, email, campaignId, droppedAt, reason } |
campaign.started | Le dispatch commence | { campaignId, name, totalRecipients, startedAt } |
campaign.finished | Tous les destinataires traités | { campaignId, name, totalSent, totalFailed, finishedAt } |
credits.low | Solde de crédits e-mail sous votre seuil d'alerte | { remaining, threshold } |
Abonnez-vous à tous les événements de cette API en passant ["*"] dans le tableau events.
Chaque POST embarque un en-tête X-Mailpro-Signature :
X-Mailpro-Signature: t=1748194800,v1=7f9ac2b6e4d1c8a3...
X-Mailpro-Event-Id: evt_8f3a9b2c4d1e5f6789abcdef01234567
X-Mailpro-Event-Type: email.delivered
X-Mailpro-Attempt: 1Pour vérifier :
t et v1 de l'en-tête.|now - t| > 300 (fenêtre de 5 minutes de protection contre le rejeu).expected = hex(HMAC_SHA256(secret, t + "." + raw_body)).v1 à expected (crypto.timingSafeEqual, hash_equals, CryptographicOperations.FixedTimeEquals) — jamais avec ==.const crypto = require('crypto');
function verifyMailproSignature(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
if (Math.abs(Date.now() / 1000 - parseInt(parts.t)) > 300) return false;
const expected = crypto
.createHmac('sha256', secret)
.update(parts.t + '.' + rawBody)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(parts.v1, 'hex'),
Buffer.from(expected, 'hex'));
}function verifyMailproSignature(string $rawBody, string $header, string $secret): bool {
parse_str(str_replace(',', '&', $header), $p);
if (abs(time() - (int)$p['t']) > 300) return false;
$expected = hash_hmac('sha256', $p['t'] . '.' . $rawBody, $secret);
return hash_equals($expected, $p['v1']);
}import hmac, hashlib, time
def verify_mailpro_signature(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split('=') for p in header.split(','))
t = int(parts['t'])
if abs(time.time() - t) > 300:
return False
expected = hmac.new(
secret.encode(),
f"{t}.".encode() + raw_body,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, parts['v1'])using System.Security.Cryptography;
using System.Text;
static bool VerifyMailproSignature(string rawBody, string header, string secret) {
var parts = header.Split(',')
.Select(p => p.Split('='))
.ToDictionary(a => a[0], a => a[1]);
var t = long.Parse(parts["t"]);
if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - t) > 300) return false;
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes($"{t}.{rawBody}"));
var expected = Convert.ToHexString(hash).ToLowerInvariant();
return CryptographicOperations.FixedTimeEquals(
Encoding.UTF8.GetBytes(expected),
Encoding.UTF8.GetBytes(parts["v1"]));
}| Tentative | Délai avant la prochaine tentative |
|---|---|
| 1 → 2 | 10 secondes |
| 2 → 3 | 1 minute |
| 3 → 4 | 5 minutes |
| 4 → 5 | 30 minutes |
| 5 → 6 | 2 heures |
| 6 → 7 | 6 heures |
| 7 | abandonnée (livraison marquée failed) |
Après 10 échecs consécutifs sur le même webhook, celui-ci est automatiquement désactivé (isActive: false) et vous recevez un e-mail de notification. Réactivez-le avec PUT /webhooks/{id} une fois votre endpoint corrigé.
Nous considérons votre webhook comme réussi uniquement si vous renvoyez un statut compris dans 200–299. Tout 3xx/4xx/5xx ou un délai d'attente dépassé (> 10 s) compte comme un échec et déclenche des réessais. Si votre endpoint est définitivement hors service, renvoyez explicitement 410 Gone — les réessais ont toujours lieu, mais le motif d'échec est plus clair dans votre journal de livraison.
| Limite | Valeur |
|---|---|
| Webhooks par compte | 20 |
| Événements souscrits par webhook | 50 |
| Taille maximale de la charge utile | 256 Ko |
| Délai HTTP par tentative | 10 secondes |
| Rétention de l'historique de livraison | 30 jours |
Obtenez un jeton JWT Bearer pour authentifier tous les autres appels d’API. L’endpoint v2 /token est une redirection 307 vers l’émetteur canonique /v3/token — votre client HTTP suit la redirection de manière transparente (la méthode POST et le corps sont préservés).
/tokenObtenir un jeton d’accès (redirection 307 vers /v3/token)
Obtient un jeton JWT Bearer à partir des identifiants client Mailpro. Transmettez l’access_token renvoyé comme Authorization: Bearer <token> dans toutes les requêtes suivantes. Le même jeton est également valable sur l’API CRM v3 et l’API SMS.
> ⚙ Détail d’implémentation — POST /v2/token est une redirection 307 > Temporary Redirect vers POST /v3/token (configurée au niveau de la couche > de réécriture IIS web.config). HTTP 307 préserve à la fois la méthode > (POST) et le corps de la requête, si bien que tout client HTTP conforme > aux standards suit la redirection de manière transparente — vous continuez à > poster sur /v2/token et récupérez un JWT valide. Il n’y a aucune logique > d’émission de jeton dupliquée ; l’API Email v2 n’émet jamais de jetons elle-même.
| Type de grant | Cas d’usage |
|---|---|
password | Intégration standard — nom d’utilisateur + clé API |
refresh_token | Renouveler un jeton d’accès expirant sans se réauthentifier |
client_credentials | Serveur à serveur avec uniquement l’identifiant client |
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’application mobile. Voir 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)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
grant_type | string: password, refresh_token, client_credentials | oui | |
username | string | Votre nom d’utilisateur Mailpro (e-mail). Requis pour le grant password. | |
password | string | Votre clé API Mailpro (format GUID). Requise pour le grant password. | |
refresh_token | string | Jeton de rafraîchissement précédent. Requis pour le grant refresh_token. | |
client_id | string | Votre identifiant client Mailpro (entier). Requis pour le grant client_credentials. |
Réponses
| Code | Description |
|---|---|
200 | Jeton émis avec succès. Renvoyé par POST /v3/token après le suivi
transparent du 307 — votre client HTTP voit un 200 normal avec la même
forme de corps qu’il recevrait directement depuis l’endpoint de jeton
v3.
|
307 | Redirection temporaire (Temporary Redirect) vers POST /v3/token, émise par la règle
de réécriture IIS dans web.config. Les clients HTTP conformes aux standards suivent
automatiquement cette redirection et préservent la méthode POST d’origine ainsi que le
corps de formulaire. Visible uniquement par les clients qui désactivent explicitement
le suivi des redirections (par ex. curl --max-redirs 0).
|
400 | Identifiants invalides ou type de grant non pris en charge |
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."
}Consultez le solde de crédits e-mail, le quota mensuel d’API et l’état de votre abonnement.
/account/credits.{format}Obtenir le solde de crédits e-mail
Renvoie le solde de crédits e-mail restants pour votre compte Mailpro. Chaque e-mail envoyé consomme un crédit. Les crédits n’expirent pas avec l’abonnement, mais ne sont utilisables que tant que l’abonnement est actif.
Scope OAuth : account:read
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Réponses
| Code | Description |
|---|---|
200 | Solde de crédits renvoyé avec succès |
401 | Identifiants invalides |
Exemple 200
{
"Credits": 48500
}/account/subscriptionEndDate.{format}Obtenir la date de fin d’abonnement
Renvoie la date d’expiration de l’abonnement Mailpro en cours. Après la date d’expiration, les envois sont bloqués jusqu’au renouvellement de l’abonnement.
Scope OAuth : account:read
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Réponses
| Code | Description |
|---|---|
200 | Date de fin d’abonnement renvoyée avec succès |
401 | Identifiants invalides |
Exemple 200
{
"SubscriptionEndDate": "2027-01-15T00:00:00"
}/account/limits.{format}Obtenir le quota mensuel d’API
Renvoie le quota mensuel de requêtes API pour le client authentifié.
Calcul du quota : la limite est calibrée à partir des crédits e-mail de l’abonnement (typiquement crédits_abonnement × 5). Pour un forfait de 10 000 e-mails/mois, cela donne un budget mensuel de 50 000 requêtes. Réinitialisé à la date anniversaire de l’abonnement (et non le 1er du mois calendaire).
Ce qui consomme du quota :
v2, v3 ou sms.Ce qui est GRATUIT (ne consomme pas de quota) :
/health.401, 403 ou 429.Le quota est partagé entre les 3 API Mailpro (v2, v3, sms) — un client = un budget mensuel pour l’ensemble de la plateforme.
Scope OAuth : account:read
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Réponses
| Code | Description |
|---|---|
200 | Instantané du quota |
401 | Identifiants invalides |
404 | Aucun enregistrement de quota trouvé (compte récemment créé ; la ligne sera créée à la première requête authentifiée). |
Exemple 200
{
"MonthlyLimit": 50000,
"Remaining": 32847,
"Used": 17153,
"IsFree": false,
"RemainedSendsForFree": 0
}Gérez les listes (listes de contacts). Une liste regroupe des contacts pour les campagnes en masse. Maximum 1 000 listes par compte (même limite sur les trois API Mailpro et dans l'app). Type 0 = liste standard. Type 1 = liste noire (utilisée pour la gestion des désabonnements).
/list/list.{format}Lister toutes les listes
Renvoie toutes les listes du compte, triées par date de création (les plus récentes en premier), sauf si sortByName=true est défini. Utilisez type=0 pour les listes classiques ou type=1 pour les listes noires.
> Alias hérité : /addressbook/list.{format} — même endpoint, conservé pour rétrocompatibilité. > Les nouvelles intégrations doivent utiliser /list/*.
Scope OAuth : contacts:read
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
titleFilter | query | string | Filtrer par titre (correspondance partielle, insensible à la casse) | |
type | query | integer: 0, 1 | 0 = listes standard uniquement, 1 = listes noires uniquement. Omettre pour toutes les renvoyer. | |
numberOfRecords | query | integer | Éléments par page — 5 000 par défaut et au maximum (voir Pagination). | |
pageNumber | query | integer | Numéro de page (à partir de 1). Par défaut : 1. | |
sortByName | query | boolean | Passer à true pour trier les résultats par ordre alphabétique du titre |
Réponses
| Code | Description |
|---|---|
200 | Listes renvoyées avec succès.
> La réponse contient également un champ dupliqué hérité AddressBookList (contenu identique)
> et chaque élément possède un AddressBookID dupliqué hérité (identique à ListID). Les nouvelles
> intégrations doivent les ignorer.
|
401 | Identifiants invalides |
Exemple 200
{
"Lists": [
{
"ListID": 101,
"Title": "Newsletter — France",
"Type": 0,
"NumberEmails": 4521,
"CreationDate": "2025-01-15T10:30:00"
},
{
"ListID": 102,
"Title": "Unsubscribers",
"Type": 1,
"NumberEmails": 312,
"CreationDate": "2025-01-15T10:31:00"
}
]
}/list/add.{format}Créer une liste
Crée une nouvelle liste (liste de contacts). La liste démarre vide — ajoutez des contacts avec /email/add ou /email/addSingle. 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.
> Alias hérité : /addressbook/add.{format} — même endpoint, conservé pour rétrocompatibilité.
Scope OAuth : contacts:write
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Corps de la requête (application/x-www-form-urlencoded)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
Title | string | oui | Nom d’affichage de la nouvelle liste |
Type | integer: 0, 1 | 0 = liste standard (par défaut), 1 = liste noire |
Réponses
| Code | Description |
|---|---|
200 | Liste créée avec succès.
> Un champ dupliqué hérité AddressBookList est également renvoyé (contenu identique).
|
400 | Title manquant |
401 | Identifiants invalides |
422 | Limite de listes (1 000) atteinte |
Exemple 200
{
"Lists": [
{
"ListID": 103,
"Title": "Spring Campaign 2026",
"Type": 0,
"NumberEmails": 0,
"CreationDate": "2026-04-14T12:00:00"
}
]
}/list/edit.{format}Renommer une liste
Met à jour le titre d’une liste existante. Les contacts qu’elle contient ne sont pas affectés.
> Alias hérité : /addressbook/edit.{format} — même endpoint, conservé pour rétrocompatibilité. > Le nom de paramètre AddressBookID est également accepté comme alias hérité de ListID.
Scope OAuth : contacts:write
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Corps de la requête (application/x-www-form-urlencoded)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
ListID | integer | oui | Identifiant de la liste à renommer (issu de /list/list). L’alias hérité AddressBookID est aussi accepté. |
Title | string | oui | Nouveau titre de la liste |
Réponses
| Code | Description |
|---|---|
200 | Liste renommée avec succès |
400 | ListID ou Title manquant |
401 | Identifiants invalides |
404 | Liste introuvable |
/list/del.{format}Supprimer une liste
Supprime définitivement une liste ainsi que tous les contacts qu’elle contient. Cette action est irréversible.
> Alias hérité : /addressbook/del.{format} — même endpoint, conservé pour rétrocompatibilité. > Le nom de paramètre AddressBookID est également accepté comme alias hérité de ListID.
Scope OAuth : contacts:write
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Corps de la requête (application/x-www-form-urlencoded)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
ListID | integer | oui | Identifiant de la liste à supprimer. L’alias hérité AddressBookID est aussi accepté. |
Réponses
| Code | Description |
|---|---|
200 | Liste supprimée avec succès |
400 | ListID manquant |
401 | Identifiants invalides |
404 | Liste introuvable |
Exemple 200
{
"Result": "OK"
}Gérez les contacts e-mail individuels. Les contacts appartiennent à une ou plusieurs listes. Utilisez l’import en masse (/email/add) pour les gros lots, ou l’ajout de contact unique (/email/addSingle) pour les inscriptions individuelles avec valeurs de champs personnalisés.
/email/list.{format}Lister les contacts
Renvoie une liste paginée des contacts e-mail du compte. Filtrez par liste ou par motif d’e-mail. Les résultats sont triés par ordre alphabétique lorsque sortByName=true, sinon par ordre d’insertion.
Scope OAuth : contacts:read
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
emailFilter | query | string | Filtrer par adresse e-mail (correspondance partielle, insensible à la casse) | |
listId | query | integer | Renvoyer uniquement les contacts de cette liste. L’alias hérité addressBookId est également accepté. | |
numberOfRecords | query | integer | Éléments par page — 5 000 par défaut et au maximum (voir Pagination). | |
pageNumber | query | integer | Numéro de page (à partir de 1). Par défaut : 1. | |
sortByName | query | boolean | Passer à true pour trier les résultats par ordre alphabétique de l’adresse e-mail |
Réponses
| Code | Description |
|---|---|
200 | Liste de contacts renvoyée avec succès |
401 | Identifiants invalides |
Exemple 200
{
"Emails": [
{
"IdEmail": 10001,
"Email": "[email protected]",
"Field1": "Alice",
"Field2": "Dupont"
}
]
}/email/add.{format}Importer des contacts (en masse)
Importe une ou plusieurs adresses e-mail dans une liste en une seule requête. Fournissez les adresses dans EmailList, séparées par des points-virgules.
Exemple : [email protected];[email protected];[email protected]
Cet endpoint importe uniquement les adresses e-mail. Pour également définir des valeurs de champs personnalisés, utilisez plutôt /email/addSingle pour chaque contact.
Les adresses précédemment désabonnées sont silencieusement ignorées sauf si Force=1 est défini.
Sélection de la liste : fournissez ListId (ou son alias hérité AddressBookId). Au moins l’un des deux est requis.
Scope OAuth : contacts:write
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Corps de la requête (application/x-www-form-urlencoded)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
ListId | integer | Identifiant de la liste de destination. L’alias hérité AddressBookId est aussi accepté. | |
EmailList | string | oui | Adresses e-mail à importer, séparées par des points-virgules |
Force | integer: 0, 1 | Passez à 1 pour réimporter des adresses précédemment désabonnées.
Valeur par défaut : 0 (les adresses désabonnées sont ignorées).
|
Réponses
| Code | Description |
|---|---|
200 | Contacts importés avec succès |
400 | EmailList manquant |
401 | Identifiants invalides |
Exemple 200
{
"Result": "3 contacts imported"
}/email/addSingle.{format}Ajouter un contact unique
Ajoute un contact à une liste avec des valeurs de champs personnalisés optionnelles.
Field1 à Field25 correspondent aux définitions des colonnes personnalisées de votre liste. La correspondance dépend de l’ordre dans lequel les colonnes ont été définies — consultez les paramètres de votre liste dans l’interface Mailpro pour savoir à quel numéro de champ correspond chaque colonne (par ex. Field1 = Prénom, Field2 = Nom, Field3 = Ville…).
Sélection de la liste : fournissez ListId (ou son alias hérité AddressBookId).
Scope OAuth : contacts:write
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Corps de la requête (application/x-www-form-urlencoded)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
ListId | integer | Identifiant de la liste de destination. L’alias hérité AddressBookId est aussi accepté. | |
Email | string | oui | Adresse e-mail du nouveau contact |
Force | integer: 0, 1 | Passez à 1 pour réajouter une adresse précédemment désabonnée | |
Field1 | string | Valeur du champ personnalisé 1 (la correspondance avec la colonne dépend de votre liste) | |
Field2 | string | Valeur du champ personnalisé 2 | |
Field3 | string | Valeur du champ personnalisé 3 | |
Field4 | string | Valeur du champ personnalisé 4 | |
Field5 | string | Valeur du champ personnalisé 5 |
Réponses
| Code | Description |
|---|---|
200 | Contact ajouté avec succès |
400 | Email manquant |
401 | Identifiants invalides |
Exemple 200
{
"EmailId": 10002,
"Email": "[email protected]",
"Field1": "Alice",
"Field2": "Dupont",
"ListID": 101
}/email/edit.{format}Mettre à jour un contact
Met à jour l’adresse e-mail et/ou les valeurs des champs personnalisés d’un contact existant. Identifiez le contact via EmailId (issu de /email/list). Les paramètres EmailId et Email sont tous deux requis.
Scope OAuth : contacts:write
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Corps de la requête (application/x-www-form-urlencoded)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
EmailId | integer | oui | Identifiant du contact à mettre à jour (issu de /email/list) |
Email | string | oui | Nouvelle adresse e-mail du contact |
Field1 | string | Nouvelle valeur du champ personnalisé 1 | |
Field2 | string | Nouvelle valeur du champ personnalisé 2 | |
Field3 | string | Nouvelle valeur du champ personnalisé 3 |
Réponses
| Code | Description |
|---|---|
200 | Contact mis à jour avec succès |
400 | EmailId ou Email manquant |
401 | Identifiants invalides |
404 | Contact introuvable |
/email/del.{format}Supprimer un contact
Supprime définitivement un contact à partir de son identifiant unique.
Scope OAuth : contacts:write
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Corps de la requête (application/x-www-form-urlencoded)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
EmailId | integer | oui | Identifiant du contact à supprimer (issu de /email/list) |
Réponses
| Code | Description |
|---|---|
200 | Contact supprimé avec succès |
400 | EmailId manquant |
401 | Identifiants invalides |
404 | Contact introuvable |
Gérez les modèles d’e-mails HTML. Un modèle de message stocke l’objet, le corps HTML et la configuration du lien de désabonnement. Les modèles sont réutilisés d’une campagne à l’autre.
/message/list.{format}Lister les modèles de messages
Renvoie les modèles d’e-mails HTML enregistrés sur le compte. Par défaut, le corps HTML n’est pas inclus dans la réponse, pour limiter la taille des charges utiles. Passez bodyHTML=true pour l’inclure (limite automatiquement les résultats à 10 par page).
Scope OAuth : email:templates:read
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
subjectFilter | query | string | Filtrer par objet (correspondance partielle, insensible à la casse) | |
numberOfRecords | query | integer | Éléments par page — 5 000 par défaut et au maximum (voir Pagination). | |
pageNumber | query | integer | Numéro de page (à partir de 1). Par défaut : 1. | |
bodyHTML | query | boolean | Passer à true pour inclure le corps HTML complet dans chaque résultat.
Lorsque true, les résultats sont automatiquement limités à 10 par page, quelle que soit la valeur de numberOfRecords.
|
Réponses
| Code | Description |
|---|---|
200 | Modèles de messages renvoyés avec succès |
401 | Identifiants invalides |
Exemple 200
{
"MessageList": [
{
"IDMessage": 501,
"Subject": "Spring Newsletter — April 2026",
"Language": "EN",
"LinkAlign": "center",
"LinkUp": 0,
"UpdateDate": "2026-03-10T14:22:00"
}
]
}/message/add.{format}Créer un modèle de message
Crée un nouveau modèle d’e-mail HTML. Le modèle stocke l’objet, le corps HTML et la configuration du lien de désabonnement. Une fois créé, utilisez l’IDMessage renvoyé lors du lancement d’une campagne.
Scope OAuth : email:templates:write
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Corps de la requête (application/x-www-form-urlencoded)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
Subject | string | oui | Ligne d’objet de l’e-mail (255 caractères maximum) |
BodyHTML | string | oui | Contenu HTML complet du corps de l’e-mail |
Language | string | oui | Code de langue pour la localisation du lien de désabonnement (par ex. EN, FR, DE) |
LinkAlign | string: left, center, right | oui | Alignement horizontal du lien de désabonnement |
LinkUp | integer: 0, 1 | oui | Position du lien de désabonnement — 0 = en bas de l’e-mail, 1 = en haut |
Réponses
| Code | Description |
|---|---|
200 | Modèle de message créé avec succès |
400 | Champ requis manquant |
401 | Identifiants invalides |
Exemple 200
{
"IDMessage": 502,
"Subject": "Spring Newsletter — April 2026",
"Language": "EN",
"LinkAlign": "center",
"LinkUp": 0
}/message/edit.{format}Mettre à jour un modèle de message
Met à jour le contenu et les métadonnées d’un modèle de message existant.
Scope OAuth : email:templates:write
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Corps de la requête (application/x-www-form-urlencoded)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
MessageId | integer | oui | Identifiant du modèle de message à mettre à jour (issu de /message/list) |
Subject | string | oui | Nouvelle ligne d’objet de l’e-mail |
BodyHTML | string | oui | Nouveau contenu HTML du corps de l’e-mail |
Language | string | oui | Code de langue pour la localisation du lien de désabonnement |
LinkAlign | string: left, center, right | oui | |
LinkUp | integer: 0, 1 | oui |
Réponses
| Code | Description |
|---|---|
200 | Modèle de message mis à jour avec succès |
400 | Champ requis manquant |
401 | Identifiants invalides |
404 | Modèle de message introuvable |
/message/del.{format}Supprimer un modèle de message
Supprime définitivement un modèle de message à partir de son identifiant unique. Les modèles utilisés par des campagnes planifiées en attente ne peuvent pas être supprimés.
Scope OAuth : email:templates:write
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Corps de la requête (application/x-www-form-urlencoded)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
MessageId | integer | oui | Identifiant du modèle de message à supprimer (issu de /message/list) |
Réponses
| Code | Description |
|---|---|
200 | Modèle de message supprimé avec succès |
400 | MessageId manquant |
401 | Identifiants invalides |
404 | Modèle de message introuvable |
Envoyez des campagnes e-mail en masse à une liste et gérez les envois planifiés. Une campagne s’appuie sur un modèle de message et une adresse expéditrice.
/send/list.{format}Lister les campagnes planifiées
Renvoie la liste des campagnes e-mail planifiées et récemment traitées. Les résultats sont triés par date d’envoi planifiée (les plus récentes en premier).
Scope OAuth : email:send
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
subjectMessageFilter | query | string | Filtrer par objet de campagne (correspondance partielle, insensible à la casse) | |
numberOfRecords | query | integer | Éléments par page — 5 000 par défaut et au maximum (voir Pagination). | |
pageNumber | query | integer | Numéro de page (à partir de 1). Par défaut : 1. |
Réponses
| Code | Description |
|---|---|
200 | Liste des campagnes renvoyée avec succès |
401 | Identifiants invalides |
Exemple 200
{
"sends": [
{
"IDSend": 3001,
"ListID": 101,
"SenderEmail": "[email protected]",
"SenderName": "Your Company Newsletter",
"DatePlanned": "2026-04-20T09:00:00",
"SubjectMessage": "Spring Newsletter — April 2026",
"NumberCredit": 4521
}
]
}/send/campaign.{format}Lancer une campagne
Planifie ou envoie immédiatement une campagne e-mail vers une liste à l’aide d’un modèle de message enregistré et d’une adresse expéditrice.
Requis :
IDMessage — le modèle à envoyer (issu de /message/list)IDEmailExp — l’adresse expéditrice à utiliser (issue de /senderEmail/list)ListId — la liste de destinataires (issue de /list/list). L’alias hérité IDAddressBook est aussi accepté.Planification : définissez DatePlanned à une date/heure ISO 8601 future pour planifier l’envoi. Omettez DatePlanned pour envoyer immédiatement.
Suivi statistiques : passez Campaign=1 et fournissez un TitleCampaign pour activer le suivi des ouvertures/clics/rebonds dans la section Statistiques.
Scope OAuth : email:send
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Corps de la requête (application/x-www-form-urlencoded)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
ListId | integer | Identifiant de la liste de destinataires (issue de /list/list). L’alias hérité IDAddressBook est aussi accepté. | |
IDMessage | integer | oui | Identifiant du modèle de message à envoyer (issu de /message/list) |
IDEmailExp | integer | oui | Identifiant de l’adresse e-mail expéditrice à utiliser (issue de /senderEmail/list) |
IDUnsubscribeList | integer | Liste utilisée pour recueillir les contacts désabonnés (liste noire).
L’alias hérité IDUnsubscribeAddressBook est aussi accepté.
| |
DatePlanned | string (date-time) | Date/heure d’envoi planifiées (ISO 8601). Omettre pour envoyer immédiatement. | |
Campaign | integer: 0, 1 | Passez à 1 pour suivre cet envoi comme campagne nommée dans les statistiques | |
TitleCampaign | string | Titre de campagne affiché dans les statistiques (requis lorsque Campaign=1) |
Réponses
| Code | Description |
|---|---|
200 | Campagne planifiée ou envoyée avec succès.
> La réponse renvoie également les alias hérités AddressBookID et UnsubscribeAddressBookID
> (identiques à ListID / UnsubscribeListID). Les nouvelles intégrations doivent les ignorer.
|
400 | IDMessage ou IDEmailExp manquant |
401 | Identifiants invalides |
403 | Crédits e-mail insuffisants |
404 | Liste, message ou expéditeur introuvable |
Exemple 200
{
"send": {
"IDSend": 3002,
"ListID": 101,
"UnsubscribeListID": 102,
"IDCampaign": 8001,
"SenderName": "Your Company Newsletter",
"SenderEmail": "[email protected]",
"DatePlanned": "2026-04-20T09:00:00",
"SubjectMessage": "Spring Newsletter — April 2026",
"NumberCredit": 4521
}
}/send/del.{format}Annuler ou supprimer une campagne
Annule un envoi de campagne planifié en attente, ou supprime un envoi terminé. Seuls les envois planifiés dans le futur peuvent être annulés — les envois en cours ne peuvent pas être arrêtés.
Scope OAuth : email:send
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Corps de la requête (application/x-www-form-urlencoded)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
IdSend | integer | oui | Identifiant de l’envoi de campagne à annuler ou supprimer (issu de /send/list) |
Réponses
| Code | Description |
|---|---|
200 | Campagne annulée ou supprimée avec succès |
400 | IdSend manquant |
401 | Identifiants invalides |
404 | Campagne introuvable |
Exemple 200
{
"Result": "Campaign Deleted"
}/send/scheduled.{format}Lister mes campagnes e-mail planifiées
Renvoie les campagnes e-mail et les envois unitaires planifiés à une date future et qui n’ont pas encore été distribués. Utile avant un appel à /cancel ou /reschedule. Les enregistrements sont triés par DatePlanned croissant.
Scope OAuth : email:send
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
numberOfRecords | query | integer | Éléments par page — 5 000 par défaut et au maximum (voir Pagination). | |
pageNumber | query | integer | Numéro de page (à partir de 1). Par défaut : 1. |
Réponses
| Code | Description |
|---|---|
200 | Liste des campagnes/envois planifiés.
> Chaque enregistrement inclut également les alias hérités AddressBookID et
> UnsubscribeAddressBookID (identiques à ListID / UnsubscribeListID).
|
401 | Identifiants invalides |
Exemple 200
{
"sends": [
{
"IDSend": 5001,
"ListID": 101,
"UnsubscribeListID": 102,
"IDCampaign": 8001,
"SenderName": "Your Company Newsletter",
"SenderEmail": "[email protected]",
"DatePlanned": "2026-05-01T09:00:00",
"SubjectMessage": "Spring Sale 2026",
"NumberCredit": 4521
}
]
}/send/{IdSend}/cancel.{format}Annuler une campagne/un envoi planifié
Annule un envoi e-mail planifié (campagne ou unitaire) qui n’a pas encore été distribué. Si l’envoi est déjà parti (ou s’il n’existe pas / appartient à un autre client), renvoie 409 Conflict.
Scope OAuth : email:send
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
IdSend | path | integer | oui |
Réponses
| Code | Description |
|---|---|
200 | Envoi annulé |
401 | Identifiants invalides |
409 | Déjà distribué ou introuvable |
Exemple 200
{
"Result": "OK",
"Cancelled": 5001
}/send/{IdSend}/reschedule.{format}Replanifier une campagne/un envoi planifié
Met à jour la DatePlanned d’un envoi e-mail planifié. La nouvelle date doit être dans le futur et dans un délai de 90 jours.
Scope OAuth : email:send
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
IdSend | path | integer | oui |
Corps de la requête (application/x-www-form-urlencoded)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
PlanDate | string (date-time) | oui |
Réponses
| Code | Description |
|---|---|
200 | Envoi replanifié |
400 | PlanDate manquante ou invalide |
401 | Identifiants invalides |
409 | Déjà distribué, introuvable ou nouvelle date hors plage (doit être future et dans un délai de 90 jours) |
Exemple 200
{
"Result": "OK",
"IdSend": 5001,
"NewPlanDate": "2026-12-31T14:30:00"
}/send/sendingTest.{format}Envoyer un e-mail de test
Envoie un aperçu d’un modèle de message à un destinataire spécifié pour relecture avant le lancement de la véritable campagne. L’expéditeur, le modèle et le destinataire de test sont tous identifiés par leurs identifiants.
Scope OAuth : email:send
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Corps de la requête (application/x-www-form-urlencoded)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
MessageId | integer | oui | Identifiant du modèle de message à prévisualiser (issu de /message/list) |
IDEmailExpFrom | integer | oui | Identifiant de l’adresse expéditrice à utiliser (issue de /senderEmail/list) |
IDEmailExpTo | integer | oui | Identifiant de l’adresse expéditrice destinataire — l’e-mail de test est envoyé à cette adresse |
Réponses
| Code | Description |
|---|---|
200 | E-mail de test envoyé avec succès |
400 | Champ requis manquant |
401 | Identifiants invalides |
Exemple 200
{
"SendingTest": {
"IdSendingTest": 7001,
"ToEmail": "[email protected]",
"FromEmail": "[email protected]",
"SenderName": "Your Company Newsletter"
}
}Envoyez des e-mails transactionnels ponctuels à des destinataires individuels. Contrairement aux campagnes, les e-mails transactionnels ne nécessitent pas de liste — vous transmettez directement l’adresse du destinataire et le corps HTML.
/send/mail/scheduled.{format}Lister les e-mails unitaires programmés
Renvoie les e-mails unitaires envoyés avec /send/sendmail et une date future, pas encore partis. Les campagnes sont listées par /send/scheduled.
Scope OAuth : email:send
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Réponses
| Code | Description |
|---|---|
200 | E-mails programmés renvoyés |
401 | Identifiants invalides |
Exemple 200
{
"scheduledMails": [
{
"IdSingleSend": 880123,
"Email": "[email protected]",
"Subject": "Your invoice",
"DatePlanned": "2026-12-01T09:00:00"
}
]
}/send/mail/{IdSingleSend}/cancel.{format}Annuler un e-mail unitaire programmé
Annule l'e-mail tant qu'il n'est pas parti.
Scope OAuth : email:send
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
IdSingleSend | path | integer (int64) | oui | IdSingleSend renvoyé par /send/sendmail |
Réponses
| Code | Description |
|---|---|
200 | E-mail annulé |
401 | Identifiants invalides |
409 | Envoi introuvable, ou déjà parti |
Exemple 200
{
"Result": "OK",
"Cancelled": 880123
}/send/mail/{IdSingleSend}/reschedule.{format}Reprogrammer un e-mail unitaire programmé
Change la date d'envoi. La nouvelle date doit être future et à moins de 90 jours. PATCH est aussi accepté.
Scope OAuth : email:send
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
IdSingleSend | path | integer (int64) | oui | IdSingleSend renvoyé par /send/sendmail |
Corps de la requête (application/x-www-form-urlencoded)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
PlanDate | string (date-time) | oui | Nouvelle date d'envoi (ISO 8601) |
Réponses
| Code | Description |
|---|---|
200 | E-mail reprogrammé |
400 | Date manquante ou invalide |
401 | Identifiants invalides |
409 | Envoi introuvable, déjà parti, ou date hors limites |
Exemple 200
{
"Result": "OK",
"IdSingleSend": 880123,
"NewPlanDate": "2026-12-15T09:00:00"
}/send/sendmail.{format}Envoyer un e-mail transactionnel
Envoie un e-mail transactionnel ponctuel à un ou plusieurs destinataires. Contrairement aux campagnes, cet endpoint ne nécessite pas de liste — l’adresse du destinataire et le corps HTML sont transmis directement.
Requis :
IDEmailExp — l’identifiant de l’adresse expéditrice (issu de /senderEmail/list)EmailData — destinataire au format email,field1,field2,...,field25 (séparés par des virgules)BodyHTML — le corps HTMLSubject — la ligne d’objetFormat EmailData : [email protected],Alice,Dupont,Paris La première valeur est l’adresse e-mail ; les valeurs 2 à 26 correspondent à Field1–Field25 pour les variables de personnalisation de votre modèle HTML.
Plusieurs destinataires : séparez plusieurs entrées EmailData par des points-virgules : [email protected],Alice;[email protected],Bob
Planification : définissez DatePlanned à une date/heure ISO 8601 future, ou omettez-la pour envoyer immédiatement.
Scope OAuth : email:send
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Corps de la requête (multipart/form-data)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
IDEmailExp | integer | oui | Identifiant de l’adresse e-mail expéditrice à utiliser (issue de /senderEmail/list) |
EmailData | string | oui | Destinataire au format email,champ1,champ2,...,champ25 (séparés par des virgules).
La première valeur est l'adresse email ; les suivantes sont des champs de
personnalisation mappés sur Field1–Field25 dans votre modèle HTML.
La partie locale de l'email (avant le @) accepte les lettres, les chiffres et
. _ - + — y compris le sous-adressage RFC 5322 (user+tag@domain, ex. Gmail,
Fastmail, Proton). Les autres caractères spéciaux autorisés par la RFC 5322
(ex. ! # $ % & ' * / = ? ^ { | } ~) et les parties locales entre guillemets ne
sont pas acceptés.
|
BodyHTML | string | oui | Contenu HTML complet du corps de l’e-mail |
Subject | string | oui | Ligne d’objet de l’e-mail (255 caractères maximum) |
attachments | array of string (binary) | Pièces jointes optionnelles — envoyez la requête en multipart/form-data et ajoutez une partie fichier par pièce jointe (n'importe quel nom de champ). Jusqu'à 5 fichiers, 10 Mo par fichier, 15 Mo au total. Types acceptés : PDF, Word, Excel, PowerPoint, images (JPG, PNG, GIF, WebP), ZIP, CSV, TXT — les fichiers exécutables et scripts sont refusés. Facturation : l'envoi garde son crédit habituel, plus 1 crédit par 512 Ko de pièces jointes au-delà des 512 premiers Ko (les pièces jointes ≤ 512 Ko n'ajoutent rien). Tous les autres champs de cet endpoint (ReplyTo, ActivateStatistics, CustomHeaders, …) fonctionnent exactement comme dans la variante form-urlencoded. | |
KeepInMyFiles | boolean | false (par défaut) : les pièces jointes ne servent qu'à cet envoi — elles sont stockées hors de
votre compte, ne comptent pas dans votre quota de stockage et sont supprimées automatiquement après
35 jours. true : les pièces jointes sont aussi conservées dans les fichiers de votre compte (dossier
Secure/Files/Sending/api) et comptent dans votre quota de stockage.
|
Réponses
| Code | Description |
|---|---|
200 | E-mail transactionnel envoyé ou planifié avec succès |
400 | Champ requis manquant ou format d’e-mail invalide |
401 | Identifiants invalides |
403 | Crédits e-mail insuffisants |
404 | Expéditeur introuvable ou adresse e-mail désabonnée |
Exemple 200
{
"SingleSend": {
"IdSingleSend": 8001,
"IdEmailExp": 201,
"DatePlanned": "2026-04-15T14:30:00",
"Subject": "Your order #12345 is confirmed",
"Email": "[email protected]",
"Field1": "Alice",
"Field2": "Dupont",
"UnsubscriptionLink": false,
"ActivateStatistics": true
}
}/send/{IdSend}/status.{format}Obtenir le statut de livraison d'un e-mail transactionnel
Renvoie le statut de livraison actuel d'un e-mail transactionnel envoyé via /send/sendmail. Transmettez l'IdSingleSend renvoyé par cet appel.
Valeurs possibles : delivered (accepté par le serveur du destinataire, voir DiagCode), bounced (refusé — BounceType: 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é, DatePlanned 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.
Scope OAuth : email:read
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
IdSend | path | integer | oui | L'IdSingleSend renvoyé par /send/sendmail. |
Réponses
| Code | Description |
|---|---|
200 | Statut de livraison actuel |
401 | Identifiants invalides |
404 | Aucun envoi transactionnel trouvé avec cet id pour ce client |
Exemple 200
{
"status": {
"IdSingleSend": 8001,
"Email": "[email protected]",
"Status": "delivered",
"DatePlanned": "2026-04-15T14:30:00",
"StatusDate": "2026-04-15T14:30:07",
"DiagCode": "2.0.0 (success)",
"BounceType": null
}
}Listez et gérez les adresses e-mail expéditrices validées. Seules les adresses vérifiées peuvent être utilisées comme adresse From dans les campagnes.
/senderEmail/list.{format}Lister les adresses expéditrices validées
Renvoie la liste des adresses d'expéditeur configurées pour le compte. Seules les adresses avec IsValid: true peuvent être utilisées pour envoyer des campagnes. Les nouvelles adresses s'ajoutent avec /senderEmail/add et deviennent valides une fois le lien de l'e-mail de validation cliqué.
Scope OAuth : email:templates:read
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
emailFilter | query | string | Filtrer par adresse e-mail (correspondance partielle, insensible à la casse) | |
numberOfRecords | query | integer | Éléments par page — 5 000 par défaut et au maximum (voir Pagination). | |
pageNumber | query | integer | Numéro de page (à partir de 1). Par défaut : 1. | |
sortByName | query | boolean | Passer à true pour trier les résultats par ordre alphabétique du nom d’expéditeur |
Réponses
| Code | Description |
|---|---|
200 | Adresses expéditrices renvoyées avec succès |
401 | Identifiants invalides |
Exemple 200
{
"ExpEmailList": [
{
"IDEmailExp": 201,
"Email": "[email protected]",
"SenderName": "Your Company Newsletter",
"IsValid": true,
"CreationDate": "2025-06-01T09:00:00"
},
{
"IDEmailExp": 202,
"Email": "[email protected]",
"SenderName": "Your Company Support",
"IsValid": true,
"CreationDate": "2025-06-01T09:05:00"
}
]
}/senderEmail/add.{format}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
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Corps de la requête (application/x-www-form-urlencoded)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
Email | string | oui | Adresse de l'expéditeur |
SenderName | string | oui | Nom affiché aux destinataires |
Réponses
| Code | Description |
|---|---|
200 | Adresse ajoutée. DomainHasMx vaut false quand le domaine n'a pas d'enregistrement MX. |
400 | Email ou SenderName manquant |
401 | Identifiants invalides |
422 | Adresse refusée : invalide, déjà parmi les expéditeurs du compte, domaine de messagerie public, nom interdit, ou limite de 25 atteinte. Le message donne la raison. |
503 | Indisponible pour le moment, réessayez |
Exemple 200
{
"Result": "OK",
"ConfirmationSent": true,
"DomainHasMx": true
}/senderEmail/{IdSenderEmail}/resendValidation.{format}Renvoyer l'e-mail de validation
Pour une adresse encore en attente de validation.
Scope OAuth : email:templates:write
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
IdSenderEmail | path | integer | oui | ID de l'expéditeur, de /senderEmail/list |
Réponses
| Code | Description |
|---|---|
200 | E-mail renvoyé |
401 | Identifiants invalides |
404 | Expéditeur introuvable |
409 | Cet expéditeur est déjà validé |
503 | Indisponible pour le moment, réessayez |
Exemple 200
{
"Result": "OK",
"ConfirmationSent": true
}/senderEmail/{IdSenderEmail}/authentication.{format}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 : DkimSettingsUrl ouvre le bon écran.
Scope OAuth : email:templates:read
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
IdSenderEmail | path | integer | oui | ID de l'expéditeur, de /senderEmail/list |
Réponses
| Code | Description |
|---|---|
200 | État du domaine. Spf.RecommendedRecord est construit à partir de votre enregistrement actuel : publiez-le seulement si Spf.ChangeNeeded vaut true. |
401 | Identifiants invalides |
404 | Expéditeur introuvable |
503 | Indisponible pour le moment, réessayez |
Exemple 200
{
"Domain": "example.com",
"Spf": {
"Valid": true,
"Record": "v=spf1 include:spf.mailpro.com -all",
"RecommendedRecord": "v=spf1 include:spf.mailpro.com -all",
"ChangeNeeded": 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"
},
"DkimSettingsUrl": "https://app.mailpro.com/dkim/list?d=example.com"
}/senderEmail/del.{format}Retirer une adresse expéditrice
Retire une adresse e-mail expéditrice validée du compte. Les adresses expéditrices utilisées par des campagnes planifiées ne peuvent pas être supprimées.
Scope OAuth : email:templates:write
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Corps de la requête (application/x-www-form-urlencoded)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
idEmailExp | integer | oui | Identifiant de l’adresse expéditrice à retirer (issu de /senderEmail/list) |
Réponses
| Code | Description |
|---|---|
200 | Adresse expéditrice retirée avec succès |
400 | idEmailExp manquant |
401 | Identifiants invalides |
Exemple 200
{
"Result": "EmailSender Deleted"
}Accédez aux indicateurs de performance par campagne : ouvertures, clics, rebonds, etc. Des ventilations détaillées par heure, par jour, par pays, par OS et par client de messagerie sont disponibles.
/stats/list.{format}Lister les statistiques de campagnes
Renvoie les indicateurs de performance globaux de toutes les campagnes : nombre d’envois, taux d’ouverture, taux de clic, nombre de rebonds. Filtrez par plage de dates ou par titre de campagne. Les résultats sont triés par date d’envoi (les plus récents en premier).
Scope OAuth : email:read
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
titleCampaignFilter | query | string | Filtrer par titre de campagne (correspondance partielle, insensible à la casse) | |
numberOfRecords | query | integer | Éléments par page — 5 000 par défaut et au maximum (voir Pagination). | |
pageNumber | query | integer | Numéro de page (à partir de 1). Par défaut : 1. | |
dateStart | query | string (date-time) | Début de la plage de dates du filtre (ISO 8601) | |
dateEnd | query | string (date-time) | Fin de la plage de dates du filtre (ISO 8601) |
Réponses
| Code | Description |
|---|---|
200 | Statistiques de campagnes renvoyées avec succès |
401 | Identifiants invalides |
Exemple 200
{
"Campaigns": [
{
"IdCampaign": 8001,
"DateCampaign": "2026-04-20T09:00:01",
"TitleCampaign": "Spring Newsletter April 2026",
"NumberEmailSend": 4521,
"NumberEmailOpen": 1823,
"NumberEmailClick": 342,
"BadMail": 12,
"NumberUnsubscribers": 8,
"NumberComplaints": 1,
"SpamTrap": 0,
"DeliverabilityScore": 98
}
]
}/stats/byHour.{format}Statistiques par heure
Renvoie la ventilation horaire des ouvertures et des clics pour une campagne donnée. Utile pour identifier l’heure d’envoi optimale.
Scope OAuth : email:read
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
idCampaign | query | integer | oui | Identifiant de la campagne (issu de /stats/list) |
Réponses
| Code | Description |
|---|---|
200 | Statistiques horaires renvoyées avec succès |
401 | Identifiants invalides |
Exemple 200
{
"ByHour": [
{
"Hour": 9,
"Opens": 823,
"Clicks": 142
},
{
"Hour": 10,
"Opens": 512,
"Clicks": 98
}
]
}/stats/byDay.{format}Statistiques par jour
Renvoie la ventilation journalière des ouvertures et des clics pour une campagne donnée.
Scope OAuth : email:read
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
idCampaign | query | integer | oui | Identifiant de la campagne (issu de /stats/list) |
Réponses
| Code | Description |
|---|---|
200 | Statistiques journalières renvoyées avec succès |
401 | Identifiants invalides |
/stats/del.{format}Supprimer les statistiques d’une campagne
Supprime définitivement tous les enregistrements statistiques d’une campagne donnée.
Scope OAuth : email:templates:write
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Corps de la requête (application/x-www-form-urlencoded)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
IdCampaign | integer | oui | Identifiant de la campagne dont supprimer les statistiques (issu de /stats/list) |
Réponses
| Code | Description |
|---|---|
200 | Statistiques de campagne supprimées avec succès |
400 | IdCampaign manquant |
401 | Identifiants invalides |
404 | Campagne introuvable |
Exemple 200
{
"Result": "Statistic Deleted"
}/stats/country.{format}Ventilation par géolocalisation
Renvoie la ventilation par géolocalisation des ouvertures de campagne — combien d’ouvertures proviennent de chaque pays.
Scope OAuth : email:read
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
idCampaign | query | integer | oui |
Réponses
| Code | Description |
|---|---|
200 | Ventilation par pays renvoyée |
401 | Identifiants invalides |
/stats/open.{format}Journal des événements d’ouverture
Renvoie le journal des événements d’ouverture par destinataire pour une campagne (une ligne par ouverture). Utilisez emailFilter pour rechercher un destinataire spécifique (correspondance partielle, insensible à la casse).
Scope OAuth : email:read
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
idCampaign | query | integer | oui | |
emailFilter | query | string | ||
numberOfRecords | query | integer | Éléments par page — 5 000 par défaut et au maximum (voir Pagination). | |
pageNumber | query | integer | Numéro de page (à partir de 1). Par défaut : 1. |
Réponses
| Code | Description |
|---|---|
200 | Événements d’ouverture renvoyés |
401 | Identifiants invalides |
/stats/click.{format}Journal des événements de clic
Renvoie le journal des événements de clic par destinataire pour une campagne — en précisant le lien cliqué et le moment du clic.
Scope OAuth : email:read
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
idCampaign | query | integer | oui | |
emailFilter | query | string | ||
numberOfRecords | query | integer | Éléments par page — 5 000 par défaut et au maximum (voir Pagination). | |
pageNumber | query | integer | Numéro de page (à partir de 1). Par défaut : 1. |
Réponses
| Code | Description |
|---|---|
200 | Événements de clic renvoyés |
401 | Identifiants invalides |
/stats/system.{format}Ventilation par système d’exploitation
Renvoie la ventilation des ouvertures par système d’exploitation (Windows, macOS, iOS, Android, Linux, etc.) pour une campagne donnée.
Scope OAuth : email:read
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
idCampaign | query | integer | oui |
Réponses
| Code | Description |
|---|---|
200 | Ventilation par OS renvoyée |
401 | Identifiants invalides |
/stats/emailSoftware.{format}Ventilation par client de messagerie
Renvoie la ventilation des ouvertures par client de messagerie (Gmail, Outlook, Apple Mail, Thunderbird, etc.) pour une campagne donnée.
Scope OAuth : email:read
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
idCampaign | query | integer | oui |
Réponses
| Code | Description |
|---|---|
200 | Ventilation par client de messagerie renvoyée |
401 | Identifiants invalides |
/stats/bounce.{format}Journal des rebonds
Renvoie la liste des destinataires en rebond (rebonds durs, rebonds doux, plaintes pour spam) d'une campagne, avec la raison de l'échec pour chaque adresse.
Scope OAuth : email:read
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
idCampaign | query | integer | oui | |
emailFilter | query | string | ||
numberOfRecords | query | integer | Éléments par page — 5 000 par défaut et au maximum (voir Pagination). | |
pageNumber | query | integer | Numéro de page (à partir de 1). Par défaut : 1. |
Réponses
| Code | Description |
|---|---|
200 | Événements de rebond renvoyés |
401 | Identifiants invalides |
Exemple 200
{
"ListBadMail": [
{
"Email": "[email protected]",
"Date": "2026-04-20T09:05:12",
"Error": "550 5.1.1 recipient rejected",
"AddressbookId": 1813318
}
]
}Parcourez le journal complet de tous les envois d’e-mails passés.
/history/list.{format}Lister l’historique des envois
Renvoie un journal paginé de tous les envois d’e-mails passés. Filtrez par identifiant de campagne ou par objet. Passez bodyHTML=true pour inclure le corps HTML (limite automatiquement à 10 par page).
Scope OAuth : email:read
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
subjectMessageFilter | query | string | Filtrer par objet de campagne (correspondance partielle, insensible à la casse) | |
idCampaign | query | integer | Renvoyer l’historique d’une campagne spécifique uniquement | |
numberOfRecords | query | integer | Éléments par page — 5 000 par défaut et au maximum (voir Pagination). | |
pageNumber | query | integer | Numéro de page (à partir de 1). Par défaut : 1. | |
bodyHTML | query | boolean | Passer à true pour inclure le corps HTML complet.
Limite automatiquement les résultats à 10 par page.
|
Réponses
| Code | Description |
|---|---|
200 | Historique renvoyé avec succès |
401 | Identifiants invalides |
Exemple 200
{
"HistoricList": [
{
"IDHistoric": 9001,
"SubjectMessage": "Spring Newsletter — April 2026",
"DateSend": "2026-04-20T09:00:01",
"NumberSend": 4521,
"NumberOpen": 1823,
"NumberClick": 342
}
]
}Téléversez un fichier CSV ou XLSX pour importer des contacts e-mail dans une liste en masse. Le fichier est placé en file d’attente pour un traitement asynchrone — suivez la fin de traitement via l’ImportJobId renvoyé ou via le callback WebhookUrl optionnel.
/import/upload.{format}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 e-mail dans une liste. Le fichier est stocké et placé en file d’attente pour un traitement asynchrone — l’endpoint renvoie immédiatement un ImportJobId.
Type de requête : multipart/form-data
Champs de formulaire requis :
IdClient (entier) — votre identifiant client MailproApiKey (chaîne) — votre clé APIListId (entier) — identifiant de la liste cible. L’alias hérité AddressBookId est aussi accepté.file (binaire) — le fichier CSV ou XLSX à téléverserOptionnel :
WebhookUrl (chaîne) — URL HTTPS appelée lorsque le traitement est terminé. Reçoit une charge utile JSON avec le statut final (success/failed) et le nombre de lignes importées/ignorées/invalides.Format du fichier :
Email — insensible à la casse)Scope OAuth : contacts:write
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Corps de la requête (multipart/form-data)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
ListId | integer | oui | Identifiant de la liste de destination. L’alias hérité AddressBookId est aussi accepté. |
file | string (binary) | oui | Fichier CSV ou XLSX (UTF-8, 50 Mo maximum) |
WebhookUrl | string (uri) | URL de callback invoquée lorsque le traitement est terminé |
Réponses
| Code | Description |
|---|---|
200 | Fichier accepté et mis en file d’attente |
400 | Aucun fichier téléversé ou ListId manquant |
401 | Identifiants invalides |
500 | Erreur de serveur ou de stockage |
Exemple 200
{
"Result": "OK",
"ImportJobId": 13,
"InternalName": "230575-20260420140221-contacts.csv"
}Abonnez votre serveur aux notifications d’événements en temps réel. Mailpro envoie en POST une charge utile JSON signée HMAC à votre URL dès que l’événement souscrit se produit. Consultez la section « Webhooks » de l’introduction pour le catalogue complet des événements, l’enveloppe de la charge utile, les extraits de vérification de signature et la politique de réessai.
/webhooksLister les webhooks
Renvoie l’ensemble des webhooks configurés sur le compte authentifié.
Réponses
| Code | Description |
|---|---|
200 | Tableau des webhooks |
401 | Identifiants invalides |
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": [
"email.delivered",
"email.bounced"
]
}
],
"total": 1
}/webhooksCréer un webhook
Crée un nouvel abonnement webhook. La réponse contient un secret qui n’est affiché qu’une seule fois — stockez-le immédiatement, côté serveur. Utilisez-le pour vérifier la signature HMAC de chaque charge utile entrante.
Limites : 20 webhooks maximum par compte, 50 événements maximum par webhook.
Corps de la requête (application/json)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
url | string (uri) | oui | Endpoint HTTPS (HTTP refusé en production) |
events | array of string | oui | Liste des types d’événements à souscrire (voir le catalogue ci-dessus). Utilisez ["*"] pour vous abonner à tous les événements de cette API. |
description | string |
Exemple
{
"url": "https://example.com/hooks/mailpro",
"events": [
"email.delivered",
"email.bounced"
],
"description": "Intégration Slack"
}Réponses
| Code | Description |
|---|---|
201 | Webhook créé — le secret n’est renvoyé qu’ici |
400 | URL, liste d’événements invalide ou limite dépassée |
401 | Identifiants invalides |
Exemple 201
{
"id": 42,
"url": "https://example.com/hooks/mailpro",
"events": [
"email.delivered",
"email.bounced"
],
"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"
}/webhooks/{id}Récupérer un webhook
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
id | path | integer (int64) | oui |
Réponses
| Code | Description |
|---|---|
200 | Le webhook |
404 | Webhook introuvable |
/webhooks/{id}Mettre à jour un webhook
Mise à jour partielle — seuls les champs transmis sont modifiés.
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
id | path | integer (int64) | oui |
Corps de la requête (application/json)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
url | string (uri) | ||
events | array of string | ||
description | string | ||
isActive | boolean | Passez à true pour réactiver un webhook désactivé automatiquement, une fois votre endpoint corrigé. |
Réponses
| Code | Description |
|---|---|
200 | Webhook mis à jour |
400 | Charge utile invalide |
404 | Webhook introuvable |
/webhooks/{id}Supprimer un webhook
Supprime définitivement le webhook et l’intégralité de son historique de livraisons.
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
id | path | integer (int64) | oui |
Réponses
| Code | Description |
|---|---|
204 | Supprimé |
404 | Webhook introuvable |
/webhooks/{id}/testEnvoyer 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 de corps eventType) à destination de 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
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
id | path | integer (int64) | oui |
Corps de la requête (application/json)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
eventType | string |
Exemple
{
"eventType": "ping"
}Réponses
| Code | Description |
|---|---|
202 | Événement mis en file d’attente pour distribution |
404 | Webhook introuvable |
Exemple 202
{
"deliveryId": 1234,
"eventId": "evt_8f3a9b2c4d1e5f6789abcdef01234567",
"eventType": "ping"
}/webhooks/{id}/rotate-secretFaire pivoter 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. Chaque livraison ultérieure sera signée avec le nouveau secret.
Utilisez cette opération si vous soupçonnez que votre secret a été compromis.
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
id | path | integer (int64) | oui |
Réponses
| Code | Description |
|---|---|
200 | Nouveau secret (visible une seule fois) |
404 | Webhook introuvable |
Exemple 200
{
"secret": "whsec_XyzA9876BcdE5432FghI1098JklM7654NopQ"
}/webhooks/{id}/deliveriesLister les tentatives de livraison
Renvoie l’historique des tentatives de distribution pour ce webhook (rétention 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
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
id | path | integer (int64) | oui | |
limit | query | integer | ||
cursor | query | integer (int64) | Curseur de pagination (= dernier identifiant de livraison vu). Renvoie les livraisons avec id < cursor. |
Réponses
| Code | Description |
|---|---|
200 | Tableau des tentatives de livraison (les plus récentes en premier) |
404 | Webhook introuvable |
/webhooks/{id}/deliveries/{deliveryId}/replayRejouer 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 ayant échoué après correction de votre endpoint. Une NOUVELLE ligne Webhook_Delivery est créée (l’originale est préservée pour audit). Le rejouage suit la politique de réessai standard (même calendrier de backoff, même règle de désactivation automatique après 10 échecs).
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
id | path | integer (int64) | oui | |
deliveryId | path | integer (int64) | oui |
Réponses
| Code | Description |
|---|---|
202 | Rejouage mis en file d’attente |
404 | Webhook ou livraison introuvable |
Bounces et désinscrits du compte : lister, ajouter, retirer.
/suppression/bounces.{format}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
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
type | query | string: hard, soft | hard ou soft | |
source | query | string | Origine du bounce : list, contact, api ou smtp | |
email | query | string | Adresse exacte | |
dateFrom | query | string (date-time) | À partir de cette date | |
dateTo | query | string (date-time) | Jusqu'à cette date | |
numberOfRecords | query | integer | ||
pageNumber | query | integer |
Réponses
| Code | Description |
|---|---|
200 | Bounces renvoyés |
400 | type doit valoir hard ou soft |
401 | Identifiants invalides |
Exemple 200
{
"bounces": [
{
"Id": 5521,
"Source": "contact",
"BounceType": "hard",
"Email": "[email protected]",
"Date": "2026-10-12T08:30:00",
"DiagCode": "550 5.1.1 User unknown",
"IdList": 101
}
]
}/suppression/bounces/{Id}/del.{format}Retirer un bounce
Source et Type sont obligatoires, tels que renvoyés par /suppression/bounces : un Id seul n'est pas unique.
Scope OAuth : contacts:write
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Id | path | integer (int64) | oui | Id du bounce |
Corps de la requête (application/x-www-form-urlencoded)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
Source | string | oui | list, contact, api ou smtp |
Type | string: hard, soft | oui | hard ou soft |
Réponses
| Code | Description |
|---|---|
200 | Bounce retiré |
400 | Source ou Type manquant |
401 | Identifiants invalides |
404 | Bounce introuvable |
Exemple 200
{
"Result": "OK",
"Id": 5521,
"Restored": false
}/suppression/bounces/{Id}/restore.{format}Remettre en liste un contact en hard bounce
Uniquement pour un hard bounce de source contact.
Scope OAuth : contacts:write
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Id | path | integer (int64) | oui | Id du bounce |
Réponses
| Code | Description |
|---|---|
200 | Contact remis en liste |
401 | Identifiants invalides |
404 | Hard bounce de contact introuvable, ou adresse plus active |
Exemple 200
{
"Result": "OK",
"Id": 5521,
"Restored": true
}/suppression/unsubscribers.{format}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
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
source | query | string | Origine de la désinscription : contact, list, smtp, api ou api3 | |
email | query | string | Adresse exacte | |
dateFrom | query | string (date-time) | À partir de cette date | |
dateTo | query | string (date-time) | Jusqu'à cette date | |
numberOfRecords | query | integer | ||
pageNumber | query | integer |
Réponses
| Code | Description |
|---|---|
200 | Désinscrits renvoyés |
401 | Identifiants invalides |
Exemple 200
{
"unsubscribers": [
{
"Id": 9012,
"Source": "api",
"Email": "[email protected]",
"Date": "2026-10-20T16:05:00",
"ListName": null,
"Comment": "Asked by phone"
}
]
}/suppression/unsubscribers/add.{format}Ajouter un désinscrit
Sans ListId, l'adresse est désinscrite pour tout le compte. Avec, de cette liste de désinscription seulement.
Scope OAuth : contacts:write
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Corps de la requête (application/x-www-form-urlencoded)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
Email | string | oui | Adresse à désinscrire |
Comment | string | Commentaire libre | |
ListId | integer (int64) | Liste de désinscription du compte (facultatif) |
Réponses
| Code | Description |
|---|---|
200 | C'est fait. AlreadyUnsubscribed vaut true quand l'adresse l'était déjà. |
400 | Une adresse valide est obligatoire |
401 | Identifiants invalides |
404 | ListId n'est pas une liste de désinscription de ce compte |
Exemple 200
{
"Result": "OK",
"AlreadyUnsubscribed": false
}/suppression/unsubscribers/{Id}/del.{format}Retirer un désinscrit
Source est obligatoire, tel que renvoyé par /suppression/unsubscribers : un Id seul n'est pas unique.
Scope OAuth : contacts:write
Paramètres
| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
format | path | string: json, xml | oui | Format de réponse |
Id | path | integer (int64) | oui | Id du désinscrit |
Corps de la requête (application/x-www-form-urlencoded)
| Nom | Type | Obligatoire | Description |
|---|---|---|---|
Source | string | oui | contact, list, smtp, api ou api3 |
Réponses
| Code | Description |
|---|---|
200 | Désinscrit retiré |
400 | Source est obligatoire |
401 | Identifiants invalides |
404 | Désinscrit introuvable |
Exemple 200
{
"Result": "OK",
"Removed": 9012
}