Premier envoi depuis Node.js

À la fin de cette page, un e-mail sera parti depuis ton script Node.js, et tu le verras dans E-mails.

Avant de commencer

• Un domaine vérifié dans ton espace, avec le statut Prêt. Sans lui, l’API refuse l’expéditeur. Voir Ajouter un domaine.
• Une clé d’API, créée dans Clés d’API. Elle commence par am_. Copie-la tout de suite : elle n’est plus jamais affichée.

1. Récupère le client

   Le client est un seul fichier, sans dépendance. Il fonctionne avec Node, Bun, Deno et les environnements edge. Ouvre-le, copie tout son contenu dans ton projet, par exemple dans src/lib/agentmail.ts.

   Tu peux aussi appeler l’API directement avec fetch. Les deux formes sont décrites dans Envoyer depuis ton logiciel.

2. Mets la clé dans `.env`

   Dans le fichier .env à la racine de ton projet :

   AGENTMAIL_API_KEY=am_…

   Ajoute .env à ton .gitignore si ce n’est pas déjà fait. Le client lit AGENTMAIL_API_KEY tout seul. Bun et Next.js chargent .env d’eux-mêmes. Avec Node 20.6 ou plus, lance ton script avec node --env-file=.env.

   La clé donne le droit d’envoyer au nom de ton espace. Elle reste dans ton serveur, jamais dans le code d’une page web. Le client refuse de tourner dans un navigateur, sauf si tu forces l’option dangerouslyAllowBrowser.

3. Envoie un premier e-mail

   import { Agentmail } from "./lib/agentmail"
   
   const mail = new Agentmail()
   
   const { id } = await mail.emails.send({
     from: "Hugo <hugo@envoi.tonentreprise.ch>",
     to: "toi@tonentreprise.ch",
     subject: "Premier envoi depuis Node",
     html: "<p>Ça marche. Ce message part de ton domaine.</p>",
     text: "Ça marche. Ce message part de ton domaine.",
   })
   
   console.log("E-mail parti :", id)

   from doit être une adresse d’un domaine vérifié de ton espace. to accepte une adresse ou un tableau d’adresses.

4. Lis la réponse et gère l'erreur

   Un envoi réussi renvoie { id }. Garde cet id : il sert à retrouver l’e-mail dans l’application et avec GET /emails/:id.

   Quand l’API refuse la requête, le client lève une AgentmailError. Elle indique ce qui s’est passé et si un nouvel essai a des chances d’aboutir :

   import { Agentmail, AgentmailError } from "./lib/agentmail"
   
   const mail = new Agentmail()
   
   try {
     const { id } = await mail.emails.send({
       from: "Hugo <hugo@envoi.tonentreprise.ch>",
       to: "toi@tonentreprise.ch",
       subject: "Premier envoi depuis Node",
       html: "<p>Ça marche.</p>",
     })
     console.log("E-mail parti :", id)
   } catch (error) {
     if (error instanceof AgentmailError) {
       console.error(error.statusCode, error.name, error.message)
       if (error.retryable) {
         // Réessayer plus tard a des chances d'aboutir.
       }
     }
     throw error
   }

   Les cas les plus fréquents :

   Ce que tu vois	Ce qu’il faut faire
   422 validation_error	Corrige le champ indiqué dans le message. Ne réessaie pas tel quel.
   403 invalid_api_key	La clé est fausse ou révoquée. Vérifie AGENTMAIL_API_KEY.
   429 rate_limit_exceeded	Trop d’envois en peu de temps. Attends quelques secondes, puis réessaie.
   429 daily_quota_exceeded	Le quota du jour est atteint. Inutile de réessayer avant le lendemain.
   500 internal_server_error	Erreur de notre côté. Réessaie avec la même clé d’idempotence.

   Le client ne réessaie seul un envoi que si tu lui fournis une clé d’idempotence. Sans elle, un nouvel essai pourrait doubler le message. Envoyer sans doublon décrit la boucle de réessai complète.

5. Vérifie dans l'application

   Ouvre E-mails. Ton message est en tête de liste, avec son parcours : en attente, envoyé, arrivé, puis ouvert si le destinataire affiche les images. Les liens partent tels quels : les clics ne sont mesurés que pour les campagnes et les workflows. Les statuts sont expliqués dans Statuts des e-mails.

Tant que le compte d’envoi n’est pas activé, le bandeau Mode test s’affiche : les envois sont simulés et rien ne part vraiment. Le code reste le même, seul le résultat change.

Si ça ne marche pas

• 403 invalid_api_key : la clé est mal copiée, ou elle a été révoquée. Crée-en une nouvelle dans Clés d’API et remplace la valeur dans .env.
• 422 validation_error sur from : l’adresse n’appartient pas à un domaine vérifié de ton espace, ou son domaine n’est pas encore Prêt.
• La variable AGENTMAIL_API_KEY est vide : ton script ne lit pas le fichier .env. Lance-le avec node --env-file=.env ou charge .env avant l’import.

Et ensuite

Référence de l'API

Les routes, les champs, les réponses et les en-têtes, au même endroit.

API : e-mails

Envoi seul, envoi par lot, et lecture du statut d’un e-mail.

Envoyer sans doublon

Relancer un envoi après une coupure sans que le destinataire reçoive deux fois le message.

Erreurs

Chaque code d’erreur, sa cause et la réaction attendue.