Comment une équipe produit peut-elle implémenter l’API e-mail Resend en toute sécurité ?

Définissez l’opération produit avant la requête au fournisseur

Partez d’une opération applicative bien délimitée : vérification de compte, reçu, alerte de sécurité ou notification demandée par le destinataire. L’endpoint public du produit doit autoriser l’appelant, le tenant, la catégorie de message, l’identité d’expéditeur, les destinataires et le modèle avant même qu’un payload Resend existe. Ne laissez pas un navigateur soumettre des valeurs `from`, `to`, du HTML ou des options fournisseur arbitraires tout en détenant un identifiant réutilisable. Créez un enregistrement sortant interne durable contenant une clé d’événement applicative, le tenant, la révision du modèle, l’expéditeur approuvé, l’ensemble des destinataires et l’état courant. Un worker peut traduire cet enregistrement en requête au fournisseur. Cette frontière tient les clés API et le contenu non fiable des messages à l’écart des clients, rend la prévention des doublons testable, et permet au produit de changer de fournisseur sans réécrire chaque workflow métier. Séparez dans le modèle interne les messages transactionnels et ceux qui dépendent du consentement, afin que les préférences, les suppressions et les décisions en cas d’incident restent explicites.

Vérifiez le domaine exact utilisé dans l’adresse From

Ajoutez dans Resend un domaine que vous contrôlez et publiez les enregistrements DNS affichés pour ce domaine. Vérifiez le domaine organisationnel ou le sous-domaine réellement utilisé dans l’adresse From visible, au lieu de supposer qu’une identité parente sans rapport le couvre. Examinez la politique SPF et DMARC existante avant de modifier le DNS, et ne créez jamais un second enregistrement SPF pour le même nom d’hôte. Utilisez un sous-domaine d’envoi dédié lorsque des exigences d’isolation, de propriété ou de migration le justifient. Une fois que le tableau de bord signale la vérification, examinez un message de test reçu pour confirmer l’adresse From visible, l’identité de signature DKIM, le chemin de retour, les résultats d’authentification et le comportement des réponses. La vérification par le fournisseur prouve qu’une identité configurée a passé le contrôle de configuration du fournisseur. Elle ne prouve ni le consentement du destinataire, ni l’acceptation par le serveur de réception, ni le placement en boîte de réception, ni une bonne réputation. Conservez la propriété du DNS et l’historique des modifications en dehors du tableau de bord du fournisseur, afin que la rotation et le retour arrière restent possibles.

Créez une clé API au moindre privilège pour chaque charge

Resend documente des clés API avec des niveaux d’accès et une restriction de domaine facultative. Un worker d’envoi doit utiliser une clé limitée à l’envoi et, lorsque l’architecture le permet, au seul domaine dont cette charge est propriétaire. Gardez la gestion, les domaines, les webhooks et l’administration du compte sous une autorité distincte. Créez des clés séparées pour le développement, la préproduction et la production, afin qu’un environnement inférieur ne puisse pas envoyer avec l’identité de production ni consommer ses limites. Stockez chaque secret directement dans un gestionnaire de secrets, exposez-le uniquement au processus serveur qui en a besoin, et transmettez-le comme autorisation Bearer via HTTPS. Ne copiez pas la clé dans le contrôle de version, les artefacts de build, les logs, les modèles, les outils d’analyse, les tickets ou les prompts. La rotation doit être répétée : créez une clé de remplacement de portée équivalente, mettez à jour le worker, vérifiez le trafic contrôlé et la corrélation des événements, puis révoquez l’ancienne clé. Déclenchez des alertes sur les échecs d’authentification et d’autorisation inattendus, car ils peuvent signaler une expiration, une révocation, une dérive de portée ou l’exposition d’un secret.

Une tâche durable, une tentative d’envoi idempotente

Réservez la tâche sortante interne avant d’appeler Resend. Dérivez une valeur d’idempotence d’un fait produit stable, comme le tenant, le type d’opération et l’ID immuable de l’événement applicatif, et non d’une tentative aléatoire. Envoyez cette valeur dans l’en-tête `Idempotency-Key`. Resend documente actuellement que ces clés empêchent les requêtes d’e-mail en double, expirent au bout de 24 heures et peuvent contenir au maximum 256 caractères. Cette fenêtre côté fournisseur est utile, mais ne constitue pas une garantie complète contre les doublons au niveau du produit. Conservez une contrainte d’unicité sur la clé d’événement interne pour les workflows métier plus longs, sérialisez les workers susceptibles de réclamer la même tâche, et stockez l’ID d’e-mail du fournisseur renvoyé par une requête réussie. Si un timeout réseau rend l’acceptation ambiguë, placez la tâche dans un état inconnu et rapprochez-la des logs ou des événements du fournisseur avant tout renvoi. Réutiliser une même clé stable pour la même opération logique est plus sûr que générer une nouvelle clé à chaque nouvelle tentative de transport.

Construisez et validez la requête d’e-mail avec soin

L’endpoint d’envoi de Resend accepte une adresse From, des destinataires, un objet et le contenu du message, avec des options documentées comme le texte, le HTML, un contenu rendu avec React, des modèles, Cc, Bcc, reply-to, des en-têtes, des pièces jointes, des tags et l’envoi programmé. N’exposez que le sous-ensemble dont le produit a besoin. Validez la syntaxe des adresses et la propriété par le tenant, plafonnez le nombre de destinataires et de pièces jointes en dessous des limites du fournisseur, rejetez l’injection de sauts de ligne dans les en-têtes, et construisez le contenu lié au MIME avec des bibliothèques maintenues ou des champs fournisseur de confiance. Ne placez ni identifiants, ni données personnelles sensibles, ni saisies client non filtrées dans les tags ou les en-têtes. Stockez une révision de modèle et des variables assainies plutôt que de journaliser le contenu complet. Un adaptateur interne doit renvoyer un résultat restreint, comme un ID fournisseur accepté ou un échec classé, sans faire fuiter les détails de la réponse du fournisseur dans le code métier. Vous pourrez ainsi adapter les noms de champs propres au fournisseur, les versions de SDK ou les limites de requêtes sans modifier le contrat d’événement produit.

Classez les réponses de l’API et les limites d’usage avant de réessayer

Considérez la réponse HTTP comme une observation parmi d’autres dans le workflow. Une réponse d’envoi réussie renvoie un identifiant d’e-mail à stocker avec la tâche interne, mais elle n’établit ni l’acceptation par la destination ni le placement en boîte de réception. Corrigez les erreurs de validation, d’authentification, de domaine, de permission et de payload au lieu de les réessayer aveuglément. Resend documente des limites de requêtes API et renvoie des en-têtes de limite de débit et de quota, avec des champs décrivant la capacité restante, le moment de réinitialisation et le délai avant nouvelle tentative ; une réponse 429 doit attendre l’intervalle documenté, avec un jitter ajouté. Réessayez les échecs de transport et les erreurs serveur éligibles avec un backoff exponentiel, un nombre fini de tentatives et la même clé d’idempotence logique tant que sa fenêtre documentée s’applique. Les échecs ambigus exigent un rapprochement, car le fournisseur a pu accepter l’e-mail même si le client n’a pas reçu la réponse. Déclenchez des alertes lorsque des échecs répétés se concentrent sur un domaine, un modèle, une clé ou un tenant, mais tenez les identifiants, le contenu complet et les données de destinataires superflues à l’écart des logs opérationnels.

Authentifiez les requêtes webhook avant de traiter les événements

Configurez un endpoint webhook HTTPS dédié et conservez le corps brut exact de la requête. Resend documente la signature des webhooks via des en-têtes compatibles Svix et des secrets de signature. Vérifiez l’ID du webhook, l’horodatage et la signature sur le payload non modifié avant toute analyse JSON ou resérialisation, et utilisez le processus de vérification officiel ou une bibliothèque compatible maintenue. Rejetez les requêtes invalides ou périmées, plafonnez la taille des requêtes et gardez le secret de signature séparé de la clé d’envoi. Après authentification, stockez durablement ou mettez en file d’attente l’événement avant d’en accuser réception, pour qu’un plantage du processus n’efface pas silencieusement des preuves de livraison. Les systèmes de livraison peuvent renvoyer et dupliquer des webhooks : utilisez donc l’identifiant d’événement comme clé de déduplication et rendez les transitions d’état monotones. Un événement tardif ou en double ne doit pas écraser un résultat final plus informatif simplement parce qu’il est arrivé en dernier. Consignez les échecs de vérification et le retard des événements comme des signaux opérationnels, sans conserver le contenu brut des messages au-delà de la durée de conservation nécessaire.

Modélisez les événements du fournisseur sans surestimer la livraison

Resend publie des types d’événements d’e-mail nommés, notamment sent, delivered, delivery delayed, bounced, complained, failed, opened et clicked. Faites correspondre ces noms fournisseur à un modèle d’états interne, avec le type d’événement d’origine, l’ID d’e-mail du fournisseur, l’ID d’événement, l’horodatage, le périmètre des destinataires et les données de diagnostic disponibles. Un événement sent décrit la progression chez le fournisseur. Un événement delivered signale une livraison selon la sémantique d’événements documentée par Resend, mais un succès SMTP auprès d’un système de réception ne révèle toujours pas le dossier final du destinataire. Les ouvertures et les clics sont des observations d’engagement, pas des preuves de livraison, et les technologies de protection de la vie privée peuvent les fausser. Les bounces, les plaintes et les échecs permanents doivent mettre à jour l’état de sécurité du destinataire avant la décision d’envoi suivante. Gardez l’historique des événements fournisseur en ajout seul (append-only) et dérivez le statut affiché à l’utilisateur à partir de règles explicites. Vous conservez ainsi des preuves pour le support et évitez des nouvelles tentatives dangereuses une fois la responsabilité transférée ou après un signal négatif du destinataire.

Testez les chemins d’échec et de reprise avec des destinataires contrôlés

Utilisez une clé hors production, un sous-domaine vérifié contrôlé et des boîtes aux lettres appartenant à l’équipe. Testez le contenu texte et HTML, le comportement de reply-to, les limites de pièces jointes, les clés d’idempotence stables et les identifiants fournisseur stockés. Soumettez deux fois la même tâche logique et vérifiez que les contrôles de l’application et du fournisseur ne créent pas de doublon involontaire. Testez un payload invalide, un mauvais domaine, une clé révoquée, une permission insuffisante, une limite de débit, un timeout de transport, un bounce, une plainte, un retard de livraison, un webhook dupliqué, un corps signé modifié, un horodatage de webhook périmé et la rotation du secret de signature. Vérifiez que la réception des événements est durable avant l’accusé de réception et que la sécurité des destinataires bloque une tâche ultérieure. Testez la rotation DNS et le retrait du fournisseur sans supprimer d’enregistrements sans rapport. Les tableaux de bord doivent couvrir les échecs d’envoi, la latence, les échecs de vérification des webhooks, le retard des événements, les bounces, les plaintes et les files de rapprochement. Relisez la documentation actuelle de Resend et les paramètres du compte au lancement, car les quotas, les limites, les champs d’événements et les permissions disponibles peuvent changer indépendamment du code applicatif déployé.

Comparez les capacités API publiées avant de migrer

SendHQ publie un contrat OpenAPI 3.1 pour son API e-mail limitée à l’espace de travail, comprenant l’envoi depuis un domaine vérifié, les e-mails entrants, les modèles hébergés, les événements de livraison et les suppressions. Avant de migrer une intégration, comparez les corps de requête, l’authentification, l’idempotence, les identifiants renvoyés, les formes d’erreur, les webhooks, les règles de domaine et le comportement des suppressions, puis validez-les par des tests au niveau des champs. Ne supposez pas la compatibilité à partir de noms d’endpoint similaires.

Questions fréquentes

Sources

• API d’envoi d’e-mails de Resend — Resend
• Clés API Resend — Resend
• Domaines Resend — Resend
• Clés d’idempotence Resend — Resend
• Limites d’usage de Resend — Resend
• Webhooks Resend — Resend
• Vérifier les requêtes webhook de Resend — Resend
• Types d’événements webhook de Resend — Resend
• RFC 5321 : Simple Mail Transfer Protocol — RFC Editor
• Contrat OpenAPI de SendHQ — SendHQ