{
    "module": "Email Gateway B2B (Mail)",
    "base_url": "https://notif.compareb2b.com/public/email",
    "endpoints": [
        {
            "id": "send",
            "method": "POST",
            "path": "/send.php",
            "title": "Envoi unitaire transactionnel",
            "summary": "Expédie un courriel transactionnel individuel via SMTP natif, Google Workspace, Microsoft 365, Brevo ou SendGrid avec bascule automatique (Circuit Breaker).",
            "headers": {
                "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"
            },
            "payload": {
                "from": {
                    "type": "string | object",
                    "required": true,
                    "description": "Adresse de l'expéditeur (ex: \"contact@acme.com\" ou {\"email\": \"contact@acme.com\", \"name\": \"Acme Support\"})"
                },
                "to": {
                    "type": "string | array",
                    "required": true,
                    "description": "Destinataire unique (\"client@example.com\") ou liste de destinataires"
                },
                "subject": {
                    "type": "string",
                    "required": true,
                    "description": "Objet du message"
                },
                "html": {
                    "type": "string",
                    "required": false,
                    "description": "Contenu du courriel au format HTML"
                },
                "text": {
                    "type": "string",
                    "required": false,
                    "description": "Version texte brut (fallback si HTML non supporté)"
                },
                "cc": {
                    "type": "string | array",
                    "required": false,
                    "description": "Destinataire(s) en copie conforme"
                },
                "bcc": {
                    "type": "string | array",
                    "required": false,
                    "description": "Destinataire(s) en copie conforme cachée"
                },
                "reply_to": {
                    "type": "string",
                    "required": false,
                    "description": "Adresse de réponse personnalisée"
                },
                "provider_id": {
                    "type": "integer",
                    "required": false,
                    "description": "ID d'un fournisseur pour forcer son utilisation prioritaire (ex: 1=Google, 2=M365, 3=Brevo, 4=SendGrid)"
                },
                "tags": {
                    "type": "string",
                    "required": false,
                    "description": "Balise de classification analytique (ex: \"facture\", \"activation\")"
                }
            },
            "request_example": {
                "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"
            },
            "response_success": {
                "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
                    }
                ]
            },
            "response_error": {
                "success": false,
                "error": "Échec d'authentification : Clé API X-EMAIL-API-KEY invalide ou révoquée.",
                "code": 401
            }
        },
        {
            "id": "batch",
            "method": "POST",
            "path": "/batch.php",
            "title": "Envoi d'e-mails en masse (Bulk)",
            "summary": "Traite et expédie un lot de messages individualisés (jusqu'à 500 par requête) avec gestion du débit et suivi par UUID.",
            "headers": {
                "Content-Type": "application/json",
                "X-EMAIL-API-KEY": "mail_live_key_acme_2026_e73d1"
            },
            "payload": {
                "messages": {
                    "type": "array of objects",
                    "required": true,
                    "description": "Liste des messages à envoyer avec leurs propriétés individuelles (from, to, subject, html)"
                }
            },
            "request_example": {
                "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>"
                    }
                ]
            },
            "response_success": {
                "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"
                    }
                ]
            },
            "response_error": {
                "success": false,
                "error": "Le tableau messages ne peut pas être vide.",
                "code": 422
            }
        },
        {
            "id": "status",
            "method": "GET",
            "path": "/status.php",
            "title": "Suivi de statut & événements de livraison",
            "summary": "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.",
            "headers": {
                "X-EMAIL-API-KEY": "mail_live_key_acme_2026_e73d1"
            },
            "payload": {
                "uuid": {
                    "type": "string (query param)",
                    "required": true,
                    "description": "Identifiant unique UUID du message retourné lors de l'envoi"
                }
            },
            "request_example": {
                "query_params": "?uuid=f8a1c2d3-9e4b-4a5c-8d6e-0f1a2b3c4d5e"
            },
            "response_success": {
                "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"
            },
            "response_error": {
                "success": false,
                "error": "Paramètre uuid manquant ou introuvable.",
                "code": 404
            }
        },
        {
            "id": "domains",
            "method": "POST",
            "path": "/domains.php",
            "title": "Certification domaines expéditeurs (SPF / DKIM)",
            "summary": "Enregistre un nom de domaine expéditeur et valide ses enregistrements DNS SPF et clés DKIM pour maximiser la délivrabilité.",
            "headers": {
                "Content-Type": "application/json",
                "X-EMAIL-API-KEY": "mail_live_key_acme_2026_e73d1"
            },
            "payload": {
                "domain": {
                    "type": "string",
                    "required": true,
                    "description": "Nom de domaine à certifier (ex: \"acme-global.com\")"
                },
                "action": {
                    "type": "string",
                    "required": false,
                    "description": "\"verify\" (par défaut) pour contrôler les DNS ou \"register\" pour initialiser les clés"
                }
            },
            "request_example": {
                "domain": "acme-global.com",
                "action": "verify"
            },
            "response_success": {
                "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..."
                    }
                ]
            },
            "response_error": {
                "success": false,
                "error": "Le domaine spécifié n'a pas d'enregistrement SPF valide.",
                "code": 400
            }
        },
        {
            "id": "webhook_events",
            "method": "POST",
            "path": "/webhook_events.php",
            "title": "Réception webhooks de délivrabilité (DLR / Bounces)",
            "summary": "Point de terminaison appelé par les fournisseurs de messagerie (Brevo, SendGrid) pour notifier les ouvertures, clics, plaintes spam et rejets.",
            "headers": {
                "Content-Type": "application/json"
            },
            "payload": {
                "event": {
                    "type": "string",
                    "required": true,
                    "description": "Type d'événement : \"delivered\", \"opened\", \"clicked\", \"hard_bounce\", \"soft_bounce\", \"spam\""
                },
                "message_id": {
                    "type": "string",
                    "required": true,
                    "description": "ID externe du message fourni par le tiers"
                }
            },
            "request_example": {
                "event": "opened",
                "message_id": "SMTP_9a8b7c6d5e4f3a2b",
                "timestamp": 1774198200
            },
            "response_success": {
                "success": true,
                "message": "Événement traité avec succès."
            },
            "response_error": {
                "success": false,
                "error": "Format de payload webhook non reconnu."
            }
        }
    ]
}