Sur cette page
Toute application Next.js finit par devoir envoyer quelque chose : un email de bienvenue après l’inscription, une notification quand un formulaire est envoyé, un reçu après un paiement. Le code nécessaire tient en quatre lignes. Ce qui prend un après-midi, c’est de savoir où ces quatre lignes ont le droit de vivre, car Next.js exécute votre code à plusieurs endroits et seuls certains peuvent garder un secret.
Les exemples ci-dessous gardent la clé API côté serveur, montrent une Server Action pour un formulaire et un Route Handler pour les appelants externes, puis gèrent l’envoi sans faire attendre l’inscription.
Où s’exécute le code, et où la clé peut vivre
L’App Router fait de tout un Server Component par défaut, ce qui est le bon choix par défaut. Dès qu’un fichier porte "use client", lui et tout ce qu’il importe sont compilés dans un bundle JavaScript envoyé au navigateur, où chaque chaîne de caractères est lisible par quiconque ouvre les DevTools.
Si vous soupçonnez qu’une clé est déjà partie, ne raisonnez pas : construisez l’application et cherchez dans le résultat. Si elle y figure, la seule solution est de la renouveler, car les bundles déployés sont déjà en cache dans des navigateurs et des CDN que vous ne contrôlez pas.
npm run build
grep -r "sk_live" .next/static | head
# Any hit at all means the key is public. Rotate it, then fix the file.Une Server Action pour votre propre formulaire
Quand l’appelant est un formulaire de votre application, une Server Action demande le moins de mécanique. Pas d’endpoint à sécuriser à part, pas de fetch à écrire côté client, et la fonction ne quitte jamais le serveur.
"use server";
import { z } from "zod";
const schema = z.object({
email: z.string().email(),
firstName: z.string().max(120).optional(),
});
const API = "https://sendtim.com/api/v1";
export async function subscribe(_: unknown, formData: FormData) {
const parsed = schema.safeParse({
email: formData.get("email"),
firstName: formData.get("firstName") || undefined,
});
if (!parsed.success) {
return { ok: false, error: "Enter a valid email address." };
}
const response = await fetch(`${API}/contacts`, {
method: "PUT",
headers: {
// Read on the server only. Never NEXT_PUBLIC_.
Authorization: `Bearer ${process.env.SENDTIM_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
...parsed.data,
source: "website",
consentGiven: true,
consentSource: "signup_form",
listIds: [process.env.NEWSLETTER_LIST_ID],
}),
});
if (!response.ok) {
console.error("subscribe failed", response.status, await response.text());
return { ok: false, error: "Something went wrong. Try again." };
}
return { ok: true };
}Côté client, il suffit d’un formulaire qui pointe vers elle, avec useActionState pour l’état d’attente et le message renvoyé, sans aucun code de fetch.
"use client";
import { useActionState } from "react";
import { subscribe } from "@/app/actions/subscribe";
export function SubscribeForm() {
const [state, action, pending] = useActionState(subscribe, null);
return (
<form action={action}>
<input type="email" name="email" required />
<button disabled={pending}>{pending ? "Joining…" : "Join"}</button>
{state?.ok ? <p>Check your inbox to confirm.</p> : null}
{state?.error ? <p role="alert">{state.error}</p> : null}
</form>
);
}Remarquez ce qui ne figure pas dans le fichier client : ni clé, ni hôte d’API, ni corps de requête. Seuls les données du formulaire et le résultat transitent.
Un Route Handler pour tous les autres
Les Server Actions servent à votre propre interface. Quand l’appelant est Stripe, un déclencheur Supabase, une tâche cron ou une application mobile, il vous faut un vrai endpoint, et c’est le rôle du Route Handler. La différence importante : l’authentification vous revient désormais, car l’URL est accessible à quiconque la trouve.
import { after } from "next/server";
export async function POST(request: Request) {
const secret = request.headers.get("x-webhook-secret");
if (secret !== process.env.WEBHOOK_SECRET) {
return Response.json({ error: "unauthorized" }, { status: 401 });
}
const { email, orderId, total } = await request.json();
// Answer the caller now; do the slow part after the response.
after(async () => {
try {
await sendReceipt({ email, orderId, total });
} catch (error) {
console.error("receipt failed", orderId, error);
}
});
return Response.json({ received: true });
}Comparez le secret en temps constant plutôt qu’avec === si l’endpoint est assez exposé pour mériter une attaque, et renvoyez un 401 avant de lire le corps pour qu’un appelant non authentifié ne puisse pas vous faire analyser du JSON arbitraire.
Ne pas faire attendre l’utilisateur pendant l’email
Un appel à une API email prend quelques centaines de millisecondes les bons jours. L’attendre dans la requête fait tourner le bouton pendant tout l’aller-retour, et sur une fonction serverless à froid, il peut s’écouler plus d’une seconde avant que quoi que ce soit ne semble se passer.
Next.js fournit after() exactement pour cela : le travail programmé à l’intérieur s’exécute une fois la réponse envoyée, tant que la fonction serverless est encore active. C’est le bon outil quand l’utilisateur n’a pas besoin de connaître le résultat, ce qui couvre les emails de bienvenue, les reçus et les notifications internes.
- Utilisez `after()` quand un échec ne doit pas changer ce que voit l’utilisateur. Un email de bienvenue qui échoue est une ligne de journal, pas une page d’erreur.
- Attendez l’appel quand le résultat est l’objet même de l’action. Une réinitialisation de mot de passe qui annonce « vérifiez votre boîte de réception » alors que l’envoi a échoué est pire qu’une erreur honnête.
- Utilisez une file d’attente dès que les échecs doivent survivre à une fonction qui plante.
after()garde le travail dans la même invocation : un délai dépassé l’emporte avec elle. - Ne lancez jamais un appel sans catch. Un rejet non géré dans un travail différé est invisible, la pire propriété qu’un bug puisse avoir.
Un dernier détail piège souvent : une Server Action est aussi un endpoint POST. Next.js lui génère un identifiant et le navigateur l’appelle comme n’importe quelle route : une action n’est donc pas privée du seul fait qu’aucun fichier n’existe dans app/api. Validez les entrées dans l’action elle-même plutôt que de compter sur le formulaire qui l’appelle habituellement, car rien n’empêche quelqu’un de l’appeler avec d’autres données.
Limiter le débit de tout ce qui n’est pas authentifié
Un endpoint public d’inscription est une API gratuite de création de contacts, et les robots les trouvent vite. Sans limite, un seul après-midi peut ajouter des milliers de fausses adresses à votre liste ; elles rebondiront à la campagne suivante et entraîneront votre réputation d’expéditeur avec elles.
const seen = new Map<string, number[]>();
const WINDOW = 60_000;
const MAX = 3;
export function allow(key: string): boolean {
const now = Date.now();
const hits = (seen.get(key) ?? []).filter((at) => now - at < WINDOW);
if (hits.length >= MAX) return false;
hits.push(now);
seen.set(key, hits);
return true;
}Une map en mémoire suffit à arrêter les abus occasionnels sur une seule instance, et devient fausse dès que vous passez à plusieurs instances, car chacune a sa propre map. Déplacez-la dans Redis ou votre base de données avant de vous y fier. Associez-la à un champ pot de miel et au double opt-in : ensemble, ils garantissent qu’une fausse adresse ne devient jamais un contact joignable. Les tactiques de formulaire d’inscription expliquent pourquoi cela compte plus que le taux de conversion du formulaire.
Garder l’email hors de votre code
Il est tentant de construire le HTML dans l’application Next.js, puisque c’est là que se trouvent les composants. C’est une décision que l’on regrette au bout d’environ quatre emails, quand une correction de texte exige un déploiement, que le mode sombre s’affiche mal dans Outlook et que personne ne peut rien prévisualiser sans lancer l’application.
Gardez le déclencheur dans le code et le contenu dans la plateforme d’emailing. Votre action crée ou met à jour le contact et indique à la plateforme quelle automatisation lancer ; l’automatisation gère le texte, la mise en forme, le timing et la vérification des blocages. Le code cesse de changer, et c’est tout l’intérêt. Le design d’email explique pourquoi ce problème de rendu est plus difficile qu’il n’y paraît.
Si vos données vivent dans Supabase plutôt que dans l’application Next.js, les deux mêmes appels fonctionnent depuis une Edge Function : envoyer des emails depuis les Edge Functions Supabase couvre la version déclenchée par la base de données.
Questions fréquentes
Peut-on appeler une API email depuis un client component dans Next.js ?
Pas avec une clé secrète. Tout ce qui se trouve dans un fichier marqué "use client" est compilé dans un bundle navigateur : la clé serait lisible par chaque visiteur. Appelez l’API depuis une Server Action ou un Route Handler, et laissez le client component appeler celui-ci.
Que fait réellement NEXT_PUBLIC_ ?
Il demande au compilateur Next.js d’intégrer la valeur au moment du build partout où la variable est référencée, y compris dans le code envoyé au navigateur. C’est une instruction de publication et non un espace de noms : un secret portant ce préfixe est public dès le déploiement et doit être renouvelé, pas caché.
Server Action ou Route Handler pour envoyer un email ?
Une Server Action quand l’appelant est un formulaire de votre application, car il n’y a pas d’endpoint distinct à sécuriser. Un Route Handler quand l’appelant est autre chose : un webhook de fournisseur de paiement, une tâche cron, un client mobile ou un autre service. Le Route Handler est une URL publique, il a donc besoin de sa propre authentification.
Comment éviter qu’une API email lente ralentisse mon formulaire ?
Renvoyez d’abord la réponse et exécutez l’appel dans `after()`, qui s’exécute une fois la réponse envoyée tant que la fonction est encore active. N’attendez l’appel que si l’utilisateur a vraiment besoin du résultat, comme pour une réinitialisation de mot de passe, où annoncer un succès pour un envoi raté est pire qu’une erreur.
Faut-il une file d’attente pour envoyer des emails depuis Next.js ?
Pas au début. `after()` règle le problème de latence et une nouvelle tentative à l’intérieur gère les échecs passagers. Une file devient nécessaire quand un échec doit survivre à l’arrêt de la fonction, ou quand vous avez besoin d’un ordre de livraison et d’une visibilité sur le retard, ce qui arrive généralement avec un vrai volume plutôt que le premier jour.
