Envoyer un email transactionnel avec Node.js et TypeScript

Votre application Node.js doit décider quand envoyer un email, pas maintenir une connexion SMTP ni réimplémenter les retries. Le SDK TypeScript Spore vous donne un appel typé et laisse la signature DKIM, la file d’envoi et les bounces à la plateforme.

Ce que vous allez obtenir

Une fonction serveur réutilisable, configurée une fois au démarrage et sûre à relancer après un timeout. Elle convient à Express, Fastify, Hono, NestJS ou à un simple worker Node.js.

1. Installer le SDK

pnpm add @lalternative/spore-sdk

Gardez la clé côté serveur :

SPORE_API_KEY=spore_api_key_here

2. Configurer le client une fois

// src/spore.ts
import { configureSporeClient, getSporeAPI } from '@lalternative/spore-sdk'
 
const apiKey = process.env.SPORE_API_KEY
if (!apiKey) throw new Error('SPORE_API_KEY is required')
 
configureSporeClient({ apiKey })
 
export const spore = getSporeAPI()

Ce module centralise l’authentification. Aucun contrôleur et aucun job ne doit manipuler directement la clé.

3. Envoyer depuis votre code métier

// src/send-welcome-email.ts
import { spore } from './spore.js'
 
type User = { id: string; email: string; firstName: string }
 
export async function sendWelcomeEmail(user: User) {
  return spore.sendEmail(
    {
      from: 'hello@votredomaine.fr',
      to: [user.email],
      subject: `Bienvenue ${user.firstName}`,
      html: `<p>Votre compte est prêt, ${user.firstName}.</p>`,
    },
    { headers: { 'Idempotency-Key': `welcome:${user.id}` } },
  )
}

Le SDK type le corps de la requête et la réponse. Une faute sur to, subject ou html est donc détectée par TypeScript avant le déploiement.

4. Rendre les retries idempotents

La clé welcome:<userId> représente l’action métier, pas la tentative réseau. Si votre worker tombe après le POST, il réutilise la même clé et Spore renvoie la première réponse sans expédier un second email. Une nouvelle intention d’envoi doit recevoir une nouvelle clé.

5. Traiter la réponse asynchrone

sendEmail renvoie un statut initial queued et un messageId. Le code HTTP 202 signifie que Spore a accepté le message dans sa file, pas que le serveur du destinataire l’a déjà livré. Conservez l’identifiant et utilisez les webhooks pour réagir à email.sent, email.bounced ou email.failed.

Le résultat : votre code Node.js reste court, typé et testable, tandis que la complexité de délivrabilité reste hors de votre application.

Continuez avec la documentation du SDK Node.js ou la référence de sendEmail.