Comment obtenir une clé API Resend et envoyer votre premier e-mail

Resend est une API d'e-mail conçue pour les développeurs : une seule requête POST, un seul corps JSON, et un e-mail transactionnel est envoyé. Chaque requête nécessite une clé API, et la manière dont vous créez cette clé détermine l'étendue des dégâts qu'une clé divulguée peut causer. Ce guide parcourt tout le chemin : inscription, vérification d'un domaine d'envoi (ou utilisation de l'adresse de test intégrée), création d'une clé avec la portée de permission appropriée, et envoi de votre premier e-mail avec curl, Node et Python. Vous stockerez également la clé dans Apidog afin de pouvoir tester le point de terminaison sans coller de secrets dans votre shell.

Si vous souhaitez avoir une vue d'ensemble de ce que l'API fait au-delà de l'envoi, le guide du débutant de l'API Resend couvre le reste. Tout ce qui suit est vérifié par rapport à la documentation officielle de Resend, de sorte que les chiffres et les chaînes d'erreur correspondent à ce que vous verrez.

Ce dont vous avez besoin avant de commencer

• Un compte Resend. Le plan gratuit est suffisant pour ce tutoriel.
• Un domaine que vous contrôlez. Si vous n'en avez pas sous la main, l'adresse de test couvre le premier envoi.
• curl sur votre machine, plus Node.js ou Python si vous voulez les exemples SDK.
• Apidog installé si vous prévoyez de suivre la section de test.

Étape 1 : créer un compte Resend

Inscrivez-vous sur resend.com et confirmez votre e-mail. Notez l'adresse avec laquelle vous vous êtes inscrit : tant que vous n'avez pas vérifié un domaine, c'est la seule boîte de réception à laquelle Resend livrera les e-mails de test, et l'oublier provoque le 403 le plus déroutant que vous verrez le premier jour.

Étape 2 : vérifier un domaine d'envoi ou utiliser l'adresse de test

Deux chemins ; commencez par le plus rapide.

Voie A : l'adresse de test d'intégration. Resend vous permet d'envoyer depuis onboarding@resend.dev sans aucune configuration. L'astuce est le destinataire : il doit s'agir de l'e-mail de votre propre compte. Envoyez à quelqu'un d'autre et l'API renverra un 403 avec le message "Vous ne pouvez envoyer des e-mails de test qu'à votre propre adresse e-mail".

Voie B : votre propre domaine. Pour tout envoi réel, ajoutez un domaine dans le tableau de bord sous Domaines. Resend recommande un sous-domaine tel que notifications.example.com au lieu de votre domaine racine, afin que la réputation d'envoi de votre produit reste séparée de votre courrier d'entreprise. Choisissez la région la plus proche de vos destinataires, puis copiez les enregistrements DNS générés par Resend dans votre fournisseur DNS. La documentation les décrit comme "les configurations DKIM et SPF (enregistrements TXT et MX ou CNAME)". Le sous-domaine du chemin de retour par défaut est send.example.com.

La vérification se termine généralement en 15 minutes, bien que la propagation DNS puisse prendre jusqu'à 72 heures. Si elle stagne, vérifiez deux coupables classiques : les enregistrements placés à la racine au lieu du sous-domaine send, et la mise en proxy de Cloudflare (l'icône de nuage doit être grise, pas orange). Corrigez les enregistrements, puis cliquez sur "Relancer la vérification". Ajoutez un enregistrement DMARC par la suite ; ce n'est pas obligatoire pour envoyer, mais les fournisseurs de boîtes de réception le récompensent.

Étape 3 : créer la clé API avec la bonne portée

Ouvrez la page des clés API dans le tableau de bord et cliquez sur Créer une clé API. Trois champs sont importants ; le document créer une clé API les couvre tous :

• Nom. Jusqu'à 50 caractères. Nommez-la pour l'application et l'environnement, comme billing-service-prod, afin que les clés soient faciles à distinguer plus tard.
• Permission. L'« accès complet » peut créer, supprimer, obtenir et mettre à jour n'importe quelle ressource, y compris les domaines et les autres clés API. L'« accès en envoi » ne peut envoyer que des e-mails. Choisissez l'accès en envoi pour tout ce qui est déployé. La clé d'accès complet appartient à votre ordinateur portable, ou nulle part.
• Domaine. Avec l'accès en envoi, vous pouvez restreindre la clé à un domaine vérifié. Une clé limitée à notifications.example.com ne peut pas envoyer depuis billing.example.com, ce qui limite la portée d'une fuite.

Resend affiche la clé une seule fois. Elle commence par re_, et une fois que vous fermez la boîte de dialogue, vous pouvez renommer la clé mais ne plus jamais la visualiser. Copiez-la directement dans une variable d'environnement :

export RESEND_API_KEY="re_xxxxxxxxx"

Les propres recommandations de Resend : les clés n'expirent jamais, donc faites-les pivoter tous les 90 jours ou plus tôt ; le tableau de bord signale toute clé inutilisée pendant 30 jours ; et si une clé fuit, supprimez-la immédiatement au lieu d'attendre la prochaine rotation. La validation de chaînes re_ dans Git est la voie de fuite la plus courante, alors exécutez un scanner de secrets sur vos dépôts avant le premier push.

Vous pouvez également créer des clés avec POST https://api.resend.com/api-keys, en passant name, permission (full_access ou sending_access) et un domain_id facultatif. Cet appel nécessite une clé d'accès complet, une raison de plus de n'en garder qu'une seule.

Étape 4 : envoyer votre premier e-mail

Le point de terminaison d'envoi est POST https://api.resend.com/emails. L'authentification est un jeton Bearer dans l'en-tête Authorization, le corps est en JSON, et seul HTTPS est accepté. Trois champs sont obligatoires : from, to et subject. Ajoutez html, text ou les deux ; si vous envoyez uniquement html, Resend génère la partie en texte brut. to accepte une chaîne ou un tableau de jusqu'à 50 adresses. La liste complète des paramètres se trouve dans la référence d'envoi d'e-mail.

curl

curl -X POST 'https://api.resend.com/emails' \
  -H "Authorization: Bearer $RESEND_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "Acme <onboarding@resend.dev>",
    "to": ["you@yourcompany.com"],
    "subject": "First Resend email",
    "html": "<p>Your Resend key works.</p>"
  }'

Un appel réussi renvoie {"id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"}. Une particularité : chaque requête doit contenir un en-tête User-Agent, sinon l'API répond 403 avec le code 1010. curl et les SDK en définissent un ; un client fait à la main dans un environnement d'exécution edge peut ne pas le faire.

Node.js

npm install resend

import { Resend } from 'resend';

const resend = new Resend(process.env.RESEND_API_KEY);

const { data, error } = await resend.emails.send({
  from: 'Acme <notifications@example.com>',
  to: ['you@yourcompany.com'],
  subject: 'First Resend email',
  html: '<p>Your Resend key works.</p>',
});

if (error) {
  console.error(error);
} else {
  console.log(data.id);
}

Le SDK Node ne lève jamais d'erreurs pour les erreurs d'API. Il renvoie { data, error }, alors vérifiez error avant de toucher à data.id.

Python

pip install resend

import os
import resend
from resend.exceptions import ResendError

resend.api_key = os.environ["RESEND_API_KEY"]

params: resend.Emails.SendParams = {
    "from": "Acme <notifications@example.com>",
    "to": ["you@yourcompany.com"],
    "subject": "First Resend email",
    "html": "<p>Your Resend key works.</p>",
}

try:
    email = resend.Emails.send(params)
    print(email["id"])
except ResendError as err:
    print(err)

Le SDK Python fait l'inverse : il lève ResendError en cas d'échec, alors enveloppez les envois dans un bloc try/except.

Étape 5 : stocker et tester la clé dans Apidog

Curl prouve que la clé fonctionne une fois. Apidog transforme cette utilisation unique en quelque chose que votre équipe peut réexécuter, et garde la clé hors de l'historique du shell et des journaux de discussion.

Stockez la clé comme une variable secrète. Créez un environnement appelé Resend, ajoutez RESEND_API_KEY comme variable et marquez-la comme secrète afin que la valeur soit masquée dans l'interface utilisateur et exclue des exportations. Le guide des environnements et variables secrètes couvre les séparations dev, staging et prod si vous conservez une clé d'envoi unique différente par environnement, ce que vous devriez faire.

Envoyez la requête. Créez une requête POST vers https://api.resend.com/emails, définissez l'authentification sur Bearer Token avec {{RESEND_API_KEY}}, et collez le corps JSON de l'exemple curl. Cliquez sur Envoyer. L'id apparaît dans le panneau de réponse à côté des en-têtes de limitation de débit couverts ci-dessous.

Enregistrez-le comme test. Ajoutez deux assertions : le statut est égal à 200 et $.id existe. Insérez la requête dans un scénario de test et vous aurez un test de fumée qui s'exécute chaque fois que quelqu'un touche au code e-mail. Pointez-le vers l'environnement de staging avec une clé d'envoi restreinte au domaine et il pourra être exécuté en toute sécurité depuis la CI.

Simulez le point de terminaison pour le travail frontend. Votre frontend a besoin de la forme de la réponse, pas d'un envoi réel. Simulez le point de terminaison dans Apidog afin qu'il renvoie {"id": "mock-email-id"} à chaque appel. L'équipe UI peut construire l'état "e-mail envoyé" toute la journée sans toucher au quota gratuit de 100 par jour ni spammer une vraie boîte de réception. Téléchargez Apidog pour le configurer ; le plan gratuit couvre quatre utilisateurs.

Limites du plan gratuit que vous rencontrerez en premier

La page de tarification de Resend indique que le plan gratuit comprend 3 000 e-mails par mois, plafonnés à 100 par jour, avec 3 domaines et une rétention des données de 30 jours. Le plan Pro commence à 20 $ par mois pour 50 000 e-mails, 10 domaines, et sans limite quotidienne, avec un dépassement à 0,90 $ par 1 000 e-mails.

Les e-mails de test vers les adresses resend.dev sont comptabilisés dans ces quotas, donc un test de charge visant delivered@resend.dev consomme toujours vos 100 quotidiens. bounced@resend.dev, complained@resend.dev et suppressed@resend.dev simulent un rebond dur, une plainte pour spam et un destinataire supprimé sans de vraies mauvaises adresses.

Indépendamment du quota, la limite de débit est par défaut de 10 requêtes par seconde et par équipe, partagée entre toutes les clés de l'équipe. Chaque réponse contient les en-têtes ratelimit-limit, ratelimit-remaining, ratelimit-reset et retry-after, de sorte qu'une boucle d'envoi peut reculer avant d'atteindre un 429. Besoin de plus ? Resend vous demande de contacter le support au lieu de créer des équipes supplémentaires.

Erreurs courantes et comment les corriger

Chaque échec est renvoyé au format JSON avec un statusCode, un name et un message. Voici ceux que vous rencontrerez le premier jour, d'après la référence des erreurs :

Un 401 avec une clé dont vous êtes sûr qu'elle est correcte signifie généralement un saut de ligne final dans la variable ou un fichier .env qui n'a jamais été chargé. Les deux ressemblent à une clé manquante du côté de l'API.

FAQ

Puis-je revoir ma clé API Resend après l'avoir créée ?

Non. Resend affiche la valeur une seule fois au moment de la création. Si vous la perdez, créez une nouvelle clé avec le même nom et les mêmes permissions, déployez-la, puis supprimez l'ancienne.

Dois-je choisir l'accès complet ou l'accès en envoi ?

L'accès en envoi, restreint à un domaine, pour chaque clé qui quitte votre machine. Conservez une clé d'accès complet pour les tâches de type tableau de bord, comme l'ajout de domaines ou la création d'autres clés, et ne la livrez jamais dans une application.

Puis-je tester l'envoi sans vérifier un domaine ?

Oui. Utilisez onboarding@resend.dev comme adresse from et l'e-mail de votre propre compte comme destinataire. Tout autre destinataire renvoie un 403 tant qu'un domaine n'est pas vérifié.

Est-il possible de gérer Resend depuis le terminal au lieu du tableau de bord ?

Oui. Le tutoriel de la CLI Resend explique comment l'installer et exécuter les commandes courantes de domaine et d'e-mail sans ouvrir de navigateur.

Que se passe-t-il si je dépasse 100 e-mails par jour avec le plan gratuit ?

L'API renvoie un 429 avec daily_quota_exceeded, et les envois reprennent après la réinitialisation quotidienne. Si vous avez régulièrement besoin de plus, le plan Pro supprime le plafond, et le récapitulatif des API d'e-mail gratuites montre comment les plans gratuits d'autres fournisseurs se comparent.

En résumé

Obtenir une clé API Resend prend deux minutes ; la configurer correctement en prend cinq. Vérifiez un sous-domaine, créez une clé d'envoi uniquement verrouillée sur ce domaine, conservez-la dans une variable d'environnement, et envoyez un e-mail avec curl pour confirmer l'aller-retour. Ensuite, déplacez la requête dans Apidog, enregistrez les assertions et simulez le point de terminaison afin que le reste de votre équipe puisse l'utiliser sans dépenser votre quota. Livrez la clé la moins puissante qui fait toujours le travail.