Twilio SendGrid : Guide technique complet pour l'email transactionnel

⚡TL;DR

• 📢 SendGrid utilise un Return-Path personnalisable (sous-domaine de votre domaine), permettant l'alignement SPF en mode relaxed pour DMARC dès le plan de base.
• La Web API v3 est la méthode recommandée : 10 000 requêtes/seconde, jusqu'à 1 000 destinataires par appel, Dynamic Templates avec Handlebars.
• Domain Authentication avec Automated Security génère 3 CNAME : Return-Path + 2 sélecteurs DKIM (rotation automatique, clés 2048 bits).
• IP dédiée recommandée à partir de 50 000 emails/mois, avec warm-up automatique sur 41 jours et coût de 30$/mois par IP supplémentaire.
• Plan Free supprimé en mai 2025 : migration obligatoire vers Essentials 50K à 19,95$/mois minimum.

Introduction

SendGrid s'est imposé comme l'une des plateformes d'email transactionnel les plus robustes du marché, traitant plus de 190 milliards d'emails mensuels en 2024. Acquis par Twilio en 2019 pour environ 3 milliards de dollars, le service combine une API REST puissante, un relais SMTP universel et des fonctionnalités d'authentification avancées qui le distinguent de la concurrence.

La force de SendGrid réside dans trois piliers techniques majeurs : une Web API v3 capable de gérer 10 000 requêtes/seconde, une Domain Authentication qui permet l'alignement SPF DMARC dès le plan de base, et un système de rotation automatique des clés DKIM 2048 bits sans interruption de service.

Ce guide s'adresse aux développeurs, DevOps, et architectes système qui cherchent à intégrer SendGrid pour l'email transactionnel avec une compréhension complète de l'infrastructure : configuration DNS, choix API vs SMTP, gestion des IP dédiées, limites techniques, et webhooks d'événements.

Web API v3 vs SMTP Relay : architecture et choix d'intégration

SendGrid propose deux méthodes d'intégration pour l'email transactionnel, toutes deux disponibles dès les plans payants.

Comparatif technique

Critère	Web API v3	SMTP Relay
Endpoint	POST https://api.sendgrid.com/v3/mail/send	smtp.sendgrid.net ports 587/465
Authentification	Bearer token (API key)	User: apikey / Pass: API key
Rate limit	10 000 requêtes/seconde	Dépend de l'IP et du plan
Destinataires/req	Jusqu'à 1 000 (personalizations)	1 email = 1 connexion SMTP
Templates	Dynamic Templates (Handlebars)	Contenu inline uniquement
Scheduling	send_at (jusqu'à 72h à l'avance)	Via header X-SMTPAPI
Tracking	Natif (click, open, Google Analytics)	Via X-SMTPAPI
Compatibilité	Requiert SDK ou HTTP client	Tout système supportant SMTP
Cas d'usage idéal	Apps modernes, batch, personnalisation avancée	Legacy, plugins CMS, serveurs mail

Quand choisir la Web API v3 ?

La Web API v3 est la méthode recommandée par SendGrid pour toute nouvelle intégration. Elle est accessible à POST https://api.sendgrid.com/v3/mail/send (ou api.eu.sendgrid.com pour la région EU).

Avantages clés :

• Personalizations : envoi de jusqu'à 1 000 destinataires dans une seule requête, chacun recevant un contenu personnalisé différent
• Dynamic Templates : syntaxe Handlebars avec conditions, boucles, comparaisons, formatage de dates
• Scheduling : programmation d'envoi jusqu'à 72 heures à l'avance avec possibilité d'annulation
• Rate limit généreux : 10 000 requêtes/seconde sur l'endpoint mail/send

Exemple d'envoi avec personnalisation :

{
  "personalizations": [{
    "to": [{"email": "utilisateur@captaindns.com", "name": "Jean Dupont"}],
    "dynamic_template_data": {
      "prenom": "Jean",
      "numero_commande": "ORD-12345",
      "montant": "149,90 €"
    }
  }],
  "from": {"email": "commandes@captaindns.com"},
  "template_id": "d-abc123def456"
}

SDKs officiels : SendGrid maintient 7 SDKs officiels (Node.js, Python, PHP, Ruby, Go, Java, C#) qui encapsulent l'API REST et simplifient l'intégration.

Quand choisir le SMTP Relay ?

Le SMTP Relay est idéal pour les systèmes legacy ou les applications ne supportant que SMTP.

Configuration officielle :

SMTP server: smtp.sendgrid.net
SMTP user: apikey (littéralement la chaîne "apikey")
SMTP password: [votre clé API SendGrid]
Port: 587 (TLS recommandé) ou 465 (SSL) ou 2525 (fallback)

Point critique : l'authentification SMTP utilise une configuration spécifique. Le nom d'utilisateur est littéralement la chaîne apikey (pas votre identifiant de compte), et le mot de passe est votre clé API SendGrid.

Header X-SMTPAPI : permet d'accéder aux fonctionnalités avancées via SMTP (categories, unique_args, filtres, scheduling, tags de substitution). Taille maximale : 10 000 bytes.

Exemple de header X-SMTPAPI pour le tracking :

{
  "category": ["confirmation_commande"],
  "unique_args": {
    "order_id": "ORD-12345",
    "customer_id": "CUST-789"
  },
  "filters": {
    "clicktrack": {"settings": {"enable": 1}},
    "opentrack": {"settings": {"enable": 1}}
  }
}

Domain Authentication : SPF, DKIM 2048 bits et alignement DMARC

L'authentification de domaine chez SendGrid génère les enregistrements DNS nécessaires pour SPF, DKIM et l'alignement DMARC. Le processus s'effectue dans Settings > Sender Authentication > Domain Authentication.

Architecture avec Automated Security (recommandé)

Avec l'option Automated Security activée, SendGrid génère 3 enregistrements CNAME :

1. CNAME pour le Return-Path : em1234.captaindns.com pointant vers SendGrid
2. CNAME DKIM s1 : s1._domainkey.captaindns.com → s1.domainkey.u1234.wl5678.sendgrid.net
3. CNAME DKIM s2 : s2._domainkey.captaindns.com → s2.domainkey.u1234.wl5678.sendgrid.net

Avantages de cette architecture :

• Rotation automatique des clés DKIM : les deux sélecteurs (s1 et s2) permettent à SendGrid de changer les clés sans interruption de service
• Clés DKIM 2048 bits par défaut depuis mai 2021 (configurations antérieures peuvent utiliser 1024 bits)
• Aucun enregistrement SPF manuel requis : le CNAME délègue la gestion SPF à SendGrid
• Sélecteurs personnalisables : 1-3 caractères alphanumériques dans les paramètres avancés

Return-Path et alignement SPF : un avantage majeur

Le Return-Path (Envelope From) est crucial pour l'alignement DMARC. Par défaut, SendGrid utilise un sous-domaine au format em[XXX].captaindns.com :

• SPF passe automatiquement car le CNAME délègue la gestion SPF à SendGrid
• L'alignement SPF fonctionne en mode relaxed (le sous-domaine em1234.captaindns.com correspond au domaine parent captaindns.com)
• Pas besoin de modifier votre SPF principal : le CNAME gère tout

En revanche, pour une politique DMARC stricte (aspf=s), l'alignement SPF échouera, car le domaine Return-Path ne correspondra jamais exactement au domaine From. La solution est de s'appuyer sur DKIM pour l'alignement DMARC, qui supporte le mode strict (adkim=s).

Custom Return Path

L'option Custom Return Path dans les paramètres avancés permet de personnaliser le sous-domaine (par exemple mail.captaindns.com au lieu de em1234.captaindns.com).

Link Branding

Le Link Branding remplace les domaines SendGrid dans les liens trackés par votre propre domaine. Au lieu de sendgrid.net/click/xxx, les liens afficheront url1234.captaindns.com/click/xxx. Cette configuration nécessite 2 enregistrements CNAME supplémentaires et améliore la confiance des destinataires.

Migration vers DKIM 2048 bits

Pour migrer une configuration antérieure (clés 1024 bits) vers 2048 bits, il faut créer une nouvelle authentification de domaine avec un nouveau sélecteur personnalisé non utilisé auparavant.

IP dédiée vs IP partagée : stratégie de délivrabilité

SendGrid recommande officiellement une IP dédiée à partir de 50 000 emails par mois. Au-delà de 200 000-300 000 emails mensuels, deux IP dédiées sont conseillées.

IP partagée (plans Free et Essentials)

Avantages :

• Aucun warm-up nécessaire
• Réputation maintenue par SendGrid
• Idéale pour volumes faibles ou irréguliers

Inconvénients :

• Exposition aux risques de réputation liés aux autres expéditeurs du pool
• Problèmes de blocklist fréquents chez Microsoft/Outlook

IP dédiée (plan Pro et supérieur)

Le plan Pro inclut 1 IP dédiée, avec possibilité d'en ajouter à 30$/mois par IP supplémentaire.

Avantages :

• Réputation isolée et contrôlable
• Fonction d'IP Warmup automatique sur 41 jours
• Possibilité de séparer les flux (transactionnel vs marketing)

IP Warmup automatique : limite progressivement les envois selon un calendrier prédéfini :

• Jour 1 : 20 emails/heure
• Jour 41 : Plus de 19 millions/heure

IP Pools : permettent de regrouper plusieurs IP dédiées et de les assigner à différents flux. La séparation est renforcée par les Subusers (sous-comptes isolés avec leurs propres statistiques, listes de suppression et webhooks).

Subusers : les plans Pro et Premier supportent jusqu'à 15 subusers par compte.

Quand choisir une IP dédiée ?

Vous avez besoin d'une IP dédiée si :

• Volume régulier > 50 000 emails/mois
• Besoin de séparer réputation transactionnel vs marketing
• Exigences de whitelisting client ou conformité réglementaire
• Volume > 200 000 emails/mois : 2 IP dédiées recommandées

Restez sur IP partagée si :

• Volume < 50 000 emails/mois
• Envois irréguliers ou sporadiques
• Démarrage d'activité sans historique

Tarification 2025 et évolution du plan Free

Plans Email API

Plan	Volume mensuel	Prix/mois	IP dédiée	Subusers
Free	100/jour (60j)	Gratuit	Non	Non
Essentials 50K	50 000	19,95$	Non	Non
Essentials 100K	100 000	34,95$	Non	Non
Pro 100K	100 000	89,95$	1 incluse	Jusqu'à 15
Pro 300K	300 000	249$	1 incluse	Jusqu'à 15
Pro 700K	700 000	499$	1 incluse	Jusqu'à 15
Premier	Custom	Sur devis	1 incluse	Jusqu'à 15

Évolution importante : En mai 2025, SendGrid a annoncé la suppression du plan Free avec une période de transition de 60 jours. Les utilisateurs doivent migrer vers un plan payant pour continuer à envoyer des emails.

Coûts additionnels

• IP dédiée supplémentaire : 30$/mois
• Email Validation API : 2 500 validations/mois incluses (Pro), 5 000 (Premier), puis tarification à l'usage
• Inbound Parse : inclus dans tous les plans payants
• Dépassements : facturés au prorata (~0,001$/email sur Pro)

Limites techniques et rate limits

Rate limits par endpoint

Endpoint	Limite
v3 Mail Send	10 000 requêtes/seconde
API générale	600 requêtes/minute
Email Validation	7 requêtes/seconde

Lorsque la limite est atteinte, l'API retourne un code HTTP 429. Les headers X-RateLimit-Remaining et X-RateLimit-Reset indiquent le quota restant et le timestamp de réinitialisation.

Gestion recommandée : backoff exponentiel et mise en file d'attente locale.

Quotas par message

Paramètre	Limite
Taille maximale email	30 MB
Destinataires par message	1 000
Categories par message	10
Custom args	< 10 000 bytes
Groupes d'unsubscribe	200 par compte

Gestion des suppressions

SendGrid maintient automatiquement plusieurs listes de suppression :

• Global Suppressions : désabonnements globaux
• Group Unsubscribes : via ASM (Advanced Suppression Manager)
• Bounces : hard et soft
• Spam Reports
• Invalid Emails

Les adresses sont supprimées indéfiniment par défaut, avec option de purge configurable de 1 à 3650 jours pour les bounces.

Event Webhook et tracking en temps réel

Le webhook d'événements permet de recevoir en temps réel les notifications de delivery, engagement et compliance.

Événements disponibles

• Delivery : processed, dropped, delivered, deferred, bounce
• Engagement : open, click, spamreport, unsubscribe
• ASM : group_unsubscribe, group_resubscribe

Comportement et retry

Les événements sont envoyés par batch dans les 30 secondes ou lorsque le batch atteint 768 KB. En cas d'échec (réponse non-2xx), SendGrid réessaie pendant 24 heures avec des intervalles croissants.

Sécurité

La sécurité du webhook peut être assurée par :

• Signature ECDSA : headers X-Twilio-Email-Event-Webhook-Signature et X-Twilio-Email-Event-Webhook-Timestamp
• OAuth 2.0 Client Credentials

Exigence : endpoint doit supporter TLS 1.2 minimum.

Inbound Parse

L'Inbound Parse permet de recevoir et parser les emails entrants. La configuration nécessite un enregistrement MX pointant vers mx.sendgrid.net sur un sous-domaine dédié.

SendGrid extrait automatiquement :

• Headers
• Corps (text et HTML)
• Pièces jointes
• Score de spam (optionnel)

Cas d'usage : systèmes de ticketing, workflows de communication bidirectionnelle.

Fonctionnalités avancées

Email Validation API

Disponible sur plans Pro et Premier uniquement. Utilise le machine learning entraîné sur plus de 100 milliards d'emails.

Vérifications :

• Syntaxe
• Enregistrements DNS
• Détection adresses jetables
• Détection adresses de rôle
• Verdict : Valid / Risky / Invalid + score de confiance

Sandbox Mode

Permet de tester le format des requêtes sans envoyer réellement d'email.

Activé via mail_settings.sandbox_mode.enable: true, il :

• Valide la structure JSON
• Retourne un code 200 (vs 202 pour les envois réels)
• Ne consomme pas de crédits

Categories et unique_args

Permettent un tracking granulaire :

• Categories : regroupement statistique (newsletters, receipts, alerts)
• unique_args (custom_args en v3) : identifiants spécifiques (numéro de commande, ID client) retournés dans les événements webhook

Plan d'action : intégration en 5 étapes

1. Créer le compte et générer une API key

• Créer un compte SendGrid (plan Essentials minimum depuis suppression du Free)
• Générer une API key dans Settings > API Keys
• Définir les permissions (Full Access ou Mail Send uniquement)

2. Configurer Domain Authentication

• Aller dans Settings > Sender Authentication > Domain Authentication
• Activer Automated Security (recommandé)
• Créer les 3 enregistrements CNAME chez votre registrar :
  1. Return-Path (em1234.captaindns.com)
  2. DKIM s1 (s1._domainkey.captaindns.com)
  3. DKIM s2 (s2._domainkey.captaindns.com)
• Vérifier la propagation DNS (24-48h)

3. Choisir la méthode d'intégration

Option A : Web API v3

• Installer le SDK officiel (npm install @sendgrid/mail, pip install sendgrid, etc.)
• Implémenter l'endpoint POST /v3/mail/send
• Créer des Dynamic Templates si besoin

Option B : SMTP Relay

• Configurer votre app/plugin :
  • Host : smtp.sendgrid.net
  • Port : 587 (STARTTLS)
  • User : apikey
  • Password : votre API key

4. Configurer les webhooks

• Aller dans Settings > Mail Settings > Event Webhook
• Définir l'URL de votre endpoint (HTTPS + TLS 1.2)
• Sélectionner les événements (delivered, bounced, etc.)
• Activer la signature ECDSA pour la sécurité

5. Tester et monitorer

• Envoyer un email test
• Vérifier dans Activity Feed que l'email est bien délivré
• Vérifier les événements webhook
• Contrôler les statistiques (open rate, bounce rate)

FAQ

Pourquoi SendGrid utilise-t-il deux sélecteurs DKIM (s1 et s2) ?

Les deux sélecteurs permettent la rotation automatique des clés DKIM sans interruption de service. Lorsque SendGrid veut renouveler les clés pour des raisons de sécurité, il peut générer une nouvelle clé sur s2 pendant que s1 est encore actif, puis basculer progressivement le trafic. Cela évite toute interruption de délivrabilité lors du changement de clé.

Dois-je ajouter SendGrid dans mon enregistrement SPF ?

Non, avec Domain Authentication et Automated Security, c'est inutile. Le CNAME Return-Path (em1234.captaindns.com) délègue automatiquement la gestion SPF à SendGrid. Votre enregistrement SPF principal n'a pas besoin de mentionner SendGrid. Exception : si vous envoyez aussi directement depuis vos serveurs, vous devez les inclure dans votre SPF.

Comment fonctionne le scheduling d'envoi avec annulation ?

Utilisez send_at (timestamp Unix en secondes, max 72h à l'avance). Pour pouvoir annuler, générez d'abord un batch_id via POST /v3/mail/batch, incluez-le dans la requête d'envoi, puis soumettez une annulation au moins 10 minutes avant l'heure prévue via POST /v3/user/scheduled_sends.

Quelle est la limite réelle de destinataires par appel API ?

1 000 destinataires maximum via le tableau personalizations (to + cc + bcc combinés). Chaque destinataire peut recevoir un contenu personnalisé différent via dynamic_template_data. Pour envoyer à 10 000 personnes, il faut 10 appels API (limités à 10 000 req/s).

Puis-je utiliser le plan Essentials pour de la production critique ?

Oui, mais sans IP dédiée. Le plan Essentials utilise des IP partagées, exposant à des risques de réputation collective. Pour du transactionnel critique (confirmations commande, resets mot de passe), le plan Pro avec IP dédiée est recommandé dès 50 000 emails/mois. En dessous, Essentials suffit si votre volume est régulier.

Comment gérer les rate limits de 10 000 req/s ?

Implémenter un backoff exponentiel et une file d'attente locale. Surveiller les headers X-RateLimit-Remaining et X-RateLimit-Reset. Si vous atteignez 429, attendre le reset ou ralentir le débit. Pour les très gros volumes, utiliser plusieurs API keys et répartir les appels (rate limit par API key).

Le header X-SMTPAPI fonctionne-t-il aussi avec la Web API v3 ?

Non, X-SMTPAPI est spécifique au SMTP Relay. Avec la Web API v3, utilisez les paramètres JSON natifs : categories, custom_args, mail_settings (tracking), send_at (scheduling). La Web API offre un contrôle plus fin et structuré que le JSON dans un header SMTP.

Glossaire

• Web API v3 : API REST de SendGrid pour l'envoi d'emails transactionnels. Endpoint principal : POST /v3/mail/send. Rate limit : 10 000 requêtes/seconde. Méthode recommandée pour toute nouvelle intégration.

• SMTP Relay : Serveur SMTP de SendGrid (smtp.sendgrid.net) permettant d'envoyer via le protocole SMTP standard. Authentification : user apikey + password = API key. Ports disponibles : 587 (TLS), 465 (SSL), 2525 (fallback).

• Personalizations : Tableau JSON dans la Web API v3 permettant d'envoyer jusqu'à 1 000 destinataires par requête, chacun recevant un contenu personnalisé via dynamic_template_data.

• Dynamic Templates : Système de templates SendGrid utilisant la syntaxe Handlebars. Supporte variables, conditions, boucles, comparaisons, formatage de dates. Triple accolade {{{html}}} pour HTML non échappé.

• Domain Authentication : Configuration DNS pour authentifier votre domaine avec SendGrid. Avec Automated Security : 3 CNAME (Return-Path + DKIM s1 + DKIM s2). Génère clés DKIM 2048 bits avec rotation automatique.

• Return-Path (Envelope From) : Adresse technique utilisée pour le routage SMTP et les bounces. SendGrid utilise un sous-domaine de votre domaine (em1234.captaindns.com), permettant l'alignement SPF relaxed pour DMARC. Personnalisable via Custom Return Path.

• Automated Security : Option recommandée pour Domain Authentication. Génère des CNAME au lieu de TXT, permet la rotation automatique des clés DKIM, et utilise clés 2048 bits par défaut.

• IP Warmup : Processus automatique de montée en charge d'une IP dédiée neuve. Calendrier sur 41 jours : de 20 emails/heure (J1) à plus de 19 millions/heure (J41). Évite le spam massif et construit la réputation progressivement.

• Subusers : Sous-comptes isolés avec statistiques, listes de suppression et webhooks propres. Disponibles sur plans Pro et Premier (jusqu'à 15 subusers). Permettent de séparer réputation par client ou par flux.

• IP Pools : Groupes d'IP dédiées assignables à différents flux (transactionnel vs marketing, par client, par marque). Renforcent la séparation de réputation.

• Event Webhook : Endpoint HTTP appelé par SendGrid lors d'événements (delivered, bounced, opened, clicked). Envoi par batch (30s ou 768 KB). Retry pendant 24h en cas d'échec. Sécurité : signature ECDSA ou OAuth 2.0.

• X-SMTPAPI : Header JSON spécifique au SMTP Relay pour accéder aux fonctionnalités avancées (categories, unique_args, filtres, scheduling). Taille max : 10 000 bytes. Non utilisé avec la Web API v3.

• Link Branding : Configuration DNS pour remplacer les domaines SendGrid dans les liens trackés par votre propre domaine. Nécessite 2 CNAME supplémentaires. Améliore confiance et réputation.

• Sandbox Mode : Mode test qui valide la structure JSON sans envoyer réellement. Active via mail_settings.sandbox_mode.enable: true. Retourne code 200 (vs 202 en production). Ne consomme pas de crédits.

• Email Validation API : Service de validation d'adresses email par machine learning (Pro/Premier uniquement). Vérifie syntaxe, DNS, détecte jetables et rôles. Verdict : Valid / Risky / Invalid + score.

• Inbound Parse : Service pour recevoir et parser les emails entrants. Configuration : enregistrement MX vers mx.sendgrid.net sur sous-domaine. Extrait headers, corps, pièces jointes, score spam. Cas d'usage : ticketing, communication bidirectionnelle.

Sources officielles

• SendGrid Official Documentation
• Twilio SendGrid Pricing