Envoyer un email transactionnel avec Next.js App Router

Dans Next.js, la frontière importante est simple : la clé Spore et l’envoi restent dans le runtime serveur. Votre bundle client ne voit jamais le secret, et une fonction dédiée transforme une action produit en email idempotent.

Architecture recommandée

Un client marqué server-only, puis une fonction métier appelée après la création réelle de l’utilisateur, de la commande ou du paiement. Vous évitez ainsi d’exposer un endpoint public capable d’envoyer des emails arbitraires.

1. Installer et déclarer la clé

pnpm add @lalternative/spore-sdk server-only

# .env.local — jamais NEXT_PUBLIC_SPORE_API_KEY
SPORE_API_KEY=spore_api_key_here

2. Créer le client serveur

// src/lib/spore.ts
import 'server-only'
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()

Le préfixe NEXT_PUBLIC_ est volontairement absent : il copierait la clé dans le JavaScript envoyé au navigateur.

3. Encapsuler l’envoi métier

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

Appelez cette fonction depuis une Route Handler, une Server Action ou un job, après avoir authentifié l’appel et chargé l’utilisateur depuis votre base. Ne faites pas confiance à un userId fourni directement par le navigateur.

4. Choisir le runtime Node.js

Si vous appelez l’envoi depuis une Route Handler, rendez le choix explicite :

// src/app/api/internal/welcome/route.ts
export const runtime = 'nodejs'

Le SDK est un package ESM TypeScript prévu pour Node.js. La réponse 202 arrive rapidement : Next.js n’attend pas la livraison SMTP finale.

5. Garder un retry sûr

Un déploiement serverless peut être interrompu après que Spore a reçu la requête. Réutilisez welcome:<userId> lors du retry. Un UUID recréé à chaque tentative produirait plusieurs intentions et pourrait donc envoyer plusieurs emails.

Pour suivre la suite, conservez le messageId dans votre base ou consommez les webhooks Spore hors de la requête utilisateur.

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