✉️
API Passerelle Email B2B (Mail)
Référentiel complet des Endpoints, Rôles et Payloads
POST https://notif.compareb2b.com/public/email/send.php
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êteValeur / 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)

ChampTypeObligatoire ?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

{
    "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)

{
    "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
}
POST https://notif.compareb2b.com/public/email/batch.php
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êteValeur / Exemple
Content-Type application/json
X-EMAIL-API-KEY mail_live_key_acme_2026_e73d1

Structure du Payload (Corps JSON)

ChampTypeObligatoire ?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

{
    "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)

{
    "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
}
GET https://notif.compareb2b.com/public/email/status.php
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êteValeur / Exemple
X-EMAIL-API-KEY mail_live_key_acme_2026_e73d1

Structure du Payload (Paramètres d'URL)

ChampTypeObligatoire ?Description
uuid string (query param) OUI Identifiant unique UUID du message retourné lors de l'envoi

Exemple de Requête JSON

{
    "query_params": "?uuid=f8a1c2d3-9e4b-4a5c-8d6e-0f1a2b3c4d5e"
}

Réponse Succès (HTTP 200)

{
    "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
}
POST https://notif.compareb2b.com/public/email/domains.php
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êteValeur / Exemple
Content-Type application/json
X-EMAIL-API-KEY mail_live_key_acme_2026_e73d1

Structure du Payload (Corps JSON)

ChampTypeObligatoire ?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

{
    "domain": "acme-global.com",
    "action": "verify"
}

Réponse Succès (HTTP 200)

{
    "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
}
POST https://notif.compareb2b.com/public/email/webhook_events.php
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êteValeur / Exemple
Content-Type application/json

Structure du Payload (Corps JSON)

ChampTypeObligatoire ?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

{
    "event": "opened",
    "message_id": "SMTP_9a8b7c6d5e4f3a2b",
    "timestamp": 1774198200
}

Réponse Succès (HTTP 200)

{
    "success": true,
    "message": "Événement traité avec succès."
}

Réponse Erreur Type

{
    "success": false,
    "error": "Format de payload webhook non reconnu."
}