Connecter SendGrid à n8n : envoi transactionnel, contacts marketing et signature du Event Webhook

Un email transactionnel qui part sans erreur ne veut pas dire qu'il arrive. SendGrid (racheté par Twilio en 2019) reste l'une des API d'envoi les plus utilisées, avec une particularité que n'ont ni Postmark ni Resend : n8n lui consacre un node natif complet, capable d'envoyer un email et de gérer des contacts marketing sans passer par un appel HTTP brut. La contrepartie arrive du côté des événements : aucun trigger dédié n'existe, et le webhook qui remonte les bounces et les clics se signe avec un algorithme asymétrique (ECDSA) que la plupart des tutoriels n8n, calibrés sur des signatures HMAC à la Stripe, ne couvrent pas.

Ce que le node SendGrid natif couvre — et ce qu'il ne couvre pas

Le node SendGrid de n8n expose deux ressources principales : Mail, pour l'envoi d'un email, et Contact, pour créer, récupérer, mettre à jour ou supprimer un contact et l'associer à une liste marketing (l'API sous-jacente est /v3/marketing/contacts). Contrairement à Postmark ou Resend, dont l'envoi d'email passe obligatoirement par un node HTTP Request brut, SendGrid n'exige aucune configuration manuelle de l'appel API pour ces deux usages.

Ce qui manque, en revanche, c'est un trigger : il n'existe pas de « SendGrid Trigger » qui recevrait automatiquement les événements de délivrabilité. Pour les bounces, ouvertures et clics, il faut construire la réception soi-même avec un node Webhook, exactement comme pour Resend — seule la partie envoi diffère entre les deux services.

Envoyer un email transactionnel avec le node SendGrid

Sur la ressource Mail, opération Send, le node attend une adresse From vérifiée, un ou plusieurs destinataires, un sujet et un contenu (texte et/ou HTML). Comme chez la plupart des API d'envoi transactionnel, l'adresse d'expéditeur doit être rattachée à une Sender Authentication validée — soit une adresse unique confirmée par email, soit un domaine vérifié par enregistrements DNS (SPF et DKIM) dans les Sender Authentication Settings du tableau de bord SendGrid. Sans cette étape, l'envoi échoue avant même d'atteindre un destinataire.

Pour joindre un fichier (devis, facture), le champ Attachments accepte un contenu encodé en base64 avec son type MIME — un contenu produit en amont par un PDF de facture généré dans le même workflow ou récupéré via le node Convert to File. Pour des emails construits à partir d'un Dynamic Template SendGrid (mise en page gérée côté SendGrid plutôt que dans le workflow), un appel direct à l'API via HTTP Request avec le champ template_id reste l'option la plus fiable : le node natif se prête surtout aux emails au contenu généré dynamiquement dans n8n.

Gérer les contacts et les listes marketing

La ressource Contact permet de créer ou mettre à jour un contact avec ses champs personnalisés, et de l'associer à une ou plusieurs listes. Un détail à connaître avant de chaîner des opérations : la création de contacts sur /v3/marketing/contacts est asynchrone côté SendGrid — l'appel renvoie un identifiant de job plutôt qu'une confirmation immédiate. Un workflow qui enchaîne « créer le contact » puis « l'ajouter à une campagne » dans la même exécution peut donc tenter d'agir sur un contact pas encore pleinement indexé ; un court délai ou une vérification via l'opération Get avant l'étape suivante évite ce genre de faux négatif intermittent.

La qualité de la liste de contacts pèse directement sur la réputation d'envoi. Une étude devenue une référence en sécurité des systèmes, Kanich, Kreibich, Levchenko et al. (2008), Spamalytics: An Empirical Analysis of Spam Marketing Conversion, publiée à l'ACM CCS, a mesuré depuis l'intérieur d'un botnet le taux de conversion réel d'une campagne d'emails non sollicités : de l'ordre de quelques envois convertis pour plusieurs millions de messages. Ce chiffre illustre, en creux, pourquoi les fournisseurs de messagerie traitent tout volume d'envoi vers des adresses non engagées comme un signal de risque — et pourquoi une liste de contacts propre (désinscriptions honorées, adresses en hard bounce retirées) protège la délivrabilité de l'ensemble des envois, transactionnels compris, bien plus efficacement qu'un réglage technique isolé.

Recevoir les événements avec un node Webhook

Dans les Mail Settings de SendGrid, l'onglet Event Webhook attend une URL — celle du node Webhook de n8n, en mode production — et une sélection des événements à transmettre, répartis en deux familles : les événements de délivrabilité (processed, delivered, bounce, dropped, deferred) et les événements d'engagement (open, click, unsubscribe, spam_report). SendGrid regroupe plusieurs événements dans un même appel POST, sous forme de tableau JSON — le workflow doit donc itérer sur la liste reçue plutôt que traiter un seul objet, avec un node Split Out si chaque événement doit être traité séparément en aval.

Un node IF ou Switch sépare ensuite les cas qui méritent une action : un bounce de type bounce classique (adresse invalide, définitif) n'appelle pas le même traitement qu'un bounce de type blocked (rejet temporaire, à réessayer) — une distinction proche de celle entre hard et soft bounce déjà rencontrée avec Postmark.

Vérifier la signature ECDSA du Event Webhook

Une fois l'option Signed Event Webhook Requests activée dans les Mail Settings, chaque appel entrant porte deux en-têtes : X-Twilio-Email-Event-Webhook-Signature (signature encodée en base64) et X-Twilio-Email-Event-Webhook-Timestamp. La vérification repose sur ECDSA, un schéma à clé publique/privée théorisé par Johnson, Menezes et Vanstone (2001), The Elliptic Curve Digital Signature Algorithm (ECDSA), publiée dans l'International Journal of Information Security — et c'est une différence structurelle avec la vérification HMAC décrite dans notre guide de sécurisation des webhooks n8n : ici, aucun secret partagé, seule la clé publique (récupérable dans les mêmes Mail Settings) permet de vérifier une signature produite avec la clé privée que SendGrid ne communique jamais.

Le message signé est la concaténation exacte du timestamp et du corps brut de la requête — d'où l'importance d'activer l'option Raw Body du node Webhook pour éviter que n8n ne reparse le JSON avant que la signature ne soit calculée, ce qui casserait systématiquement la vérification. Un node Code placé juste après le Webhook effectue le contrôle :

const crypto = require('crypto');

const publicKeyPem =
  '-----BEGIN PUBLIC KEY-----\n' +
  $env.SENDGRID_WEBHOOK_PUBLIC_KEY +
  '\n-----END PUBLIC KEY-----';

const signature = $request.headers['x-twilio-email-event-webhook-signature'];
const timestamp = $request.headers['x-twilio-email-event-webhook-timestamp'];
const rawBody = $request.body; // brut, grâce à l'option Raw Body du node Webhook

const verifier = crypto.createVerify('SHA256');
verifier.update(timestamp + rawBody);
verifier.end();

if (!verifier.verify(publicKeyPem, signature, 'base64')) {
  throw new Error('Signature SendGrid invalide');
}

return JSON.parse(rawBody).map((event) => ({ json: event }));

Comme pour toute vérification de signature, brancher ce node Code sur une sortie d'erreur explicite plutôt que de laisser l'exception remonter telle quelle permet de renvoyer un rejet propre à SendGrid sans faire ressembler l'incident à une panne interne.

Un cas concret : facture envoyée, suivie, et contact nettoyé au premier bounce

1. Un workflow de facturation génère le PDF et déclenche l'envoi via le node SendGrid (ressource Mail), en conservant l'identifiant du message aux côtés du numéro de facture dans une table Supabase.
2. Le node Webhook, signature vérifiée, reçoit les événements delivered et bounce et met à jour cette même table.
3. Sur un bounce définitif, le contact correspondant est marqué invalide via l'opération Update du node SendGrid — il ne recevra plus aucun envoi tant que l'adresse n'aura pas été corrigée manuellement, et une alerte Slack informe l'équipe comptable qu'une relance par un autre canal est nécessaire.

Pièges fréquents

• Vérifier la signature sur un body reparsé en JSON au lieu du corps brut : la signature ne correspondra jamais, quelle que soit la justesse du reste du code.
• Traiter le payload du Event Webhook comme un objet unique alors que SendGrid regroupe systématiquement plusieurs événements dans le même tableau JSON envoyé en une seule requête.
• Confondre HMAC et ECDSA : copier le code de vérification écrit pour un webhook Stripe ou GitHub ne fonctionnera pas ici, les deux schémas de signature ne sont pas interchangeables.
• Oublier la Sender Authentication avant le premier envoi : sans domaine vérifié ni adresse confirmée, chaque appel à la ressource Mail échoue, quelle que soit la justesse de la configuration du node.

Pour aller plus loin

Ce que SendGrid apporte en plus de Postmark et Resend, c'est la gestion native des contacts marketing directement depuis n8n — pratique pour un envoi transactionnel et une liste de diffusion gérés dans le même workflow, sans jongler avec un outil comme Brevo en parallèle. Ce même besoin de traçabilité — qui a reçu quoi, avec quel statut, et quelle correction a été appliquée en cas d'échec — est exactement ce que couvre le Pack Conformité & Audit (149 €), avec la brique de journalisation Supabase déjà prête à brancher en sortie d'un webhook signé. Combiné au Pack Inbox IA (79 €) pour le tri des réponses entrantes, le Bundle FlowKit Complet (269 € au lieu de 347 € pris séparément) couvre le cycle complet d'un email, de son envoi à la correction du contact en cas d'échec.