✉️
API Passerelle Email B2B (Mail)
Référentiel complet des Endpoints, Rôles et Payloads
Envoi unitaire transactionnel
Expédie un courriel transactionnel individuel via SMTP natif, Google Workspace, Microsoft 365, Brevo ou SendGrid avec bascule automatique (Circuit Breaker).
En-têtes HTTP Requis
En-tête Valeur / Exemple
Content-Type
application/json
X-EMAIL-API-KEY
mail_live_key_acme_2026_e73d1 (ou Authorization: Bearer <clé>)
X-EMAIL-SIGNATURE
(Optionnel) Signature HMAC-SHA256 du body brut
Structure du Payload (Corps JSON)
Champ Type Obligatoire ? Description
from
string | object
OUI
Adresse de l'expéditeur (ex: "contact@acme.com" ou {"email": "contact@acme.com", "name": "Acme Support"})
to
string | array
OUI
Destinataire unique ("client@example.com") ou liste de destinataires
subject
string
OUI
Objet du message
html
string
Optionnel
Contenu du courriel au format HTML
text
string
Optionnel
Version texte brut (fallback si HTML non supporté)
cc
string | array
Optionnel
Destinataire(s) en copie conforme
bcc
string | array
Optionnel
Destinataire(s) en copie conforme cachée
reply_to
string
Optionnel
Adresse de réponse personnalisée
provider_id
integer
Optionnel
ID d'un fournisseur pour forcer son utilisation prioritaire (ex: 1=Google, 2=M365, 3=Brevo, 4=SendGrid)
tags
string
Optionnel
Balise de classification analytique (ex: "facture", "activation")
Exemple de Requête JSON
📋 Copier
{
"from": {
"email": "notifications@acme-global.com",
"name": "Acme Platform"
},
"to": "client@example.com",
"cc": "manager@acme-global.com",
"reply_to": "support@acme-global.com",
"subject": "Confirmation de votre commande #82914",
"html": "<h2>Merci pour votre commande !</h2><p>Votre facture est jointe.</p>",
"text": "Merci pour votre commande ! Votre facture est prête.",
"tags": "order-confirmation"
}
Réponse Succès (HTTP 200)
📋 Copier
{
"success": true,
"message_uuid": "f8a1c2d3-9e4b-4a5c-8d6e-0f1a2b3c4d5e",
"status": "sent",
"recipients_count": 1,
"provider_used": "Google Workspace Relay (SMTP TLS)",
"provider_protocol": "smtp",
"provider_message_id": "SMTP_9a8b7c6d5e4f3a2b",
"attempts_count": 1,
"cascade_attempts": [
{
"attempt": 1,
"provider": "Google Workspace Relay (SMTP TLS)",
"protocol": "smtp",
"success": true,
"latency_ms": 218,
"error": null
}
]
}
Réponse Erreur Type
{
"success": false,
"error": "Échec d'authentification : Clé API X-EMAIL-API-KEY invalide ou révoquée.",
"code": 401
}
Envoi d'e-mails en masse (Bulk)
Traite et expédie un lot de messages individualisés (jusqu'à 500 par requête) avec gestion du débit et suivi par UUID.
En-têtes HTTP Requis
En-tête Valeur / Exemple
Content-Type
application/json
X-EMAIL-API-KEY
mail_live_key_acme_2026_e73d1
Structure du Payload (Corps JSON)
Champ Type Obligatoire ? Description
messages
array of objects
OUI
Liste des messages à envoyer avec leurs propriétés individuelles (from, to, subject, html)
Exemple de Requête JSON
📋 Copier
{
"messages": [
{
"from": "newsletter@acme-global.com",
"to": "user1@example.com",
"subject": "Offre Spéciale Flash 1",
"html": "<p>Bonjour, voici votre réduction de 10%...</p>"
},
{
"from": "newsletter@acme-global.com",
"to": "user2@example.com",
"subject": "Offre Spéciale Flash 2",
"html": "<p>Bonjour, voici votre réduction exclusive...</p>"
}
]
}
Réponse Succès (HTTP 200)
📋 Copier
{
"success": true,
"batch_id": "batch_mail_7781a9f0",
"total_requested": 2,
"sent_count": 2,
"failed_count": 0,
"results": [
{
"uuid": "uuid_msg_1",
"to": "user1@example.com",
"status": "sent"
},
{
"uuid": "uuid_msg_2",
"to": "user2@example.com",
"status": "sent"
}
]
}
Réponse Erreur Type
{
"success": false,
"error": "Le tableau messages ne peut pas être vide.",
"code": 422
}
Suivi de statut & événements de livraison
Récupère le statut en temps réel d'un message (envoyé, délivré, ouvert, cliqué, rebond) ainsi que la trace de bascule failover.
En-têtes HTTP Requis
En-tête Valeur / Exemple
X-EMAIL-API-KEY
mail_live_key_acme_2026_e73d1
Structure du Payload (Paramètres d'URL)
Champ Type Obligatoire ? Description
uuid
string (query param)
OUI
Identifiant unique UUID du message retourné lors de l'envoi
Exemple de Requête JSON
📋 Copier
{
"query_params": "?uuid=f8a1c2d3-9e4b-4a5c-8d6e-0f1a2b3c4d5e"
}
Réponse Succès (HTTP 200)
📋 Copier
{
"success": true,
"message_uuid": "f8a1c2d3-9e4b-4a5c-8d6e-0f1a2b3c4d5e",
"status": "delivered",
"subject": "Confirmation de votre commande #82914",
"recipient": "client@example.com",
"created_at": "2026-09-22 01:10:00",
"delivered_at": "2026-09-22 01:10:04",
"opened_at": "2026-09-22 01:15:22",
"clicked_at": null,
"bounced": false,
"provider_used": "Google Workspace Relay"
}
Réponse Erreur Type
{
"success": false,
"error": "Paramètre uuid manquant ou introuvable.",
"code": 404
}
Certification domaines expéditeurs (SPF / DKIM)
Enregistre un nom de domaine expéditeur et valide ses enregistrements DNS SPF et clés DKIM pour maximiser la délivrabilité.
En-têtes HTTP Requis
En-tête Valeur / Exemple
Content-Type
application/json
X-EMAIL-API-KEY
mail_live_key_acme_2026_e73d1
Structure du Payload (Corps JSON)
Champ Type Obligatoire ? Description
domain
string
OUI
Nom de domaine à certifier (ex: "acme-global.com")
action
string
Optionnel
"verify" (par défaut) pour contrôler les DNS ou "register" pour initialiser les clés
Exemple de Requête JSON
📋 Copier
{
"domain": "acme-global.com",
"action": "verify"
}
Réponse Succès (HTTP 200)
📋 Copier
{
"success": true,
"domain": "acme-global.com",
"is_certified": true,
"spf_status": "valid",
"dkim_status": "valid",
"dns_records": [
{
"type": "TXT",
"host": "@",
"value": "v=spf1 include:_spf.acme-relay.com ~all"
},
{
"type": "TXT",
"host": "default._domainkey",
"value": "v=DKIM1; k=rsa; p=MIGfMA0GCS..."
}
]
}
Réponse Erreur Type
{
"success": false,
"error": "Le domaine spécifié n'a pas d'enregistrement SPF valide.",
"code": 400
}
Réception webhooks de délivrabilité (DLR / Bounces)
Point de terminaison appelé par les fournisseurs de messagerie (Brevo, SendGrid) pour notifier les ouvertures, clics, plaintes spam et rejets.
En-têtes HTTP Requis
En-tête Valeur / Exemple
Content-Type
application/json
Structure du Payload (Corps JSON)
Champ Type Obligatoire ? Description
event
string
OUI
Type d'événement : "delivered", "opened", "clicked", "hard_bounce", "soft_bounce", "spam"
message_id
string
OUI
ID externe du message fourni par le tiers
Exemple de Requête JSON
📋 Copier
{
"event": "opened",
"message_id": "SMTP_9a8b7c6d5e4f3a2b",
"timestamp": 1774198200
}
Réponse Succès (HTTP 200)
📋 Copier
{
"success": true,
"message": "Événement traité avec succès."
}
Réponse Erreur Type
{
"success": false,
"error": "Format de payload webhook non reconnu."
}