Sur cette page
Supabase vous fournit l’authentification, une base de données et un endroit où exécuter du code, puis s’arrête précisément là où la plupart des produits ont besoin d’une chose de plus : prévenir l’utilisateur qu’il s’est passé quelque chose. Un email de bienvenue après l’inscription, un reçu après un paiement, une notification quand une ligne change. Il n’y a pas de serveur mail dans la boîte, et l’environnement Deno des Edge Functions ne peut pas ouvrir de socket SMTP comme le ferait un processus Node.
Appelez une API email en HTTPS avec le fetch intégré de Deno. L’exemple relie une Edge Function à un déclencheur de base de données, range le secret de l’API en sécurité et gère les échecs avant la mise en production.
Qui appelle quoi
Avant d’écrire la moindre ligne, il vaut la peine de clarifier le rôle de chaque composant, car l’erreur la plus fréquente ici est d’architecture, pas de syntaxe.
L’Edge Function est le seul composant qui détient la clé API, le seul qui sait réessayer et le seul qui doit changer quand le fournisseur d’email change. La base de données se contente de dire « c’est arrivé » et passe à autre chose.
L’Edge Function
Créez-la avec supabase functions new send-welcome. Le tout se résume à deux requêtes derrière un petit utilitaire qui transforme une réponse en échec en erreur levée, car fetch se résout sans broncher sur un 500, et c’est précisément l’échec silencieux que vous voulez éviter.
const API = "https://sendtim.com/api/v1";
const API_KEY = Deno.env.get("SENDTIM_API_KEY")!;
const WELCOME_AUTOMATION = Deno.env.get("WELCOME_AUTOMATION_ID")!;
class ApiError extends Error {
constructor(readonly status: number, message: string) {
super(message);
}
}
async function api<T>(path: string, body: unknown, method = "POST"): Promise<T> {
const response = await fetch(`${API}${path}`, {
method,
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify(body),
});
if (!response.ok) {
// The error shape is { error: { code, message } }.
const detail = await response.text();
throw new ApiError(response.status, `${method} ${path}: ${detail}`);
}
return response.json() as Promise<T>;
}
Deno.serve(async (request) => {
const { email, firstName, plan } = await request.json();
// Upsert, not create: a retry updates the contact instead of failing.
const contact = await api<{ id: string; created: boolean }>(
"/contacts",
{
email,
firstName,
source: "supabase",
consentGiven: true,
consentSource: "signup_form",
customProperties: { plan },
},
"PUT",
);
await api(`/automations/${WELCOME_AUTOMATION}/trigger`, {
contactId: contact.id,
});
return new Response(JSON.stringify({ ok: true, contactId: contact.id }), {
headers: { "Content-Type": "application/json" },
});
});Deux points méritent qu’on s’y arrête. PUT /contacts crée ou met à jour selon l’adresse email et renvoie { id, created } : l’exécuter deux fois pour la même personne est sans danger. Et consentGiven n’est enregistré qu’une fois, à la création, ce qui rend la trace défendable plus tard : voyez la checklist RGPD pour comprendre pourquoi la source et l’horodatage comptent plus que l’indicateur lui-même.
Mettre la clé dans les secrets, pas dans la base de données
Les secrets des Edge Functions se définissent depuis la CLI et sont injectés comme variables d’environnement à l’exécution. Ils ne sont pas lisibles en SQL, et c’est voulu : une sauvegarde de base de données qui fuite ne doit pas contenir une clé capable d’écrire à toute votre liste.
supabase secrets set SENDTIM_API_KEY=sk_live_xxxxxxxxxxxx
supabase secrets set WELCOME_AUTOMATION_ID=7c1f8e2a-...
supabase functions deploy send-welcome --no-verify-jwt--no-verify-jwt est là parce que l’appelant est votre propre base de données et non un utilisateur connecté. La fonction est donc accessible à quiconque découvre l’URL : donnez-lui son propre secret partagé et vérifiez-le à l’entrée, ce que le trigger ci-dessous envoie dans un en-tête.
L’appeler depuis un trigger de base de données
L’extension pg_net fait des requêtes HTTP depuis Postgres de façon asynchrone : elle met la requête en file d’attente et renvoie immédiatement un identifiant au lieu d’attendre la réponse. Cette asynchronie est toute la raison de l’utiliser. Un trigger qui attend une API externe rend chaque inscription otage de la disponibilité d’un tiers, et une réponse lente garde une transaction ouverte pendant l’attente.
create extension if not exists pg_net with schema extensions;
create or replace function public.notify_welcome()
returns trigger
language plpgsql
security definer
set search_path = ''
as $$
begin
perform extensions.net_http_post(
url := 'https://<project-ref>.supabase.co/functions/v1/send-welcome',
headers := jsonb_build_object(
'Content-Type', 'application/json',
'x-webhook-secret', current_setting('app.webhook_secret', true)
),
body := jsonb_build_object(
'email', new.email,
'firstName', new.raw_user_meta_data ->> 'first_name',
'plan', 'free'
)
);
return new;
end;
$$;
create trigger on_user_created
after insert on auth.users
for each row execute function public.notify_welcome();Comme net_http_post n’attend pas, la fonction ne sait jamais d’ici si l’appel a réussi. C’est acceptable pour un email de bienvenue, et faux pour tout ce que l’utilisateur surveille, comme une réinitialisation de mot de passe. Dans ce cas, appelez la fonction directement depuis le code de votre application et laissez l’utilisateur voir le résultat.
Décider quoi faire de chaque échec
L’utilitaire ci-dessus lève une erreur pour toute réponse hors 2xx : la fonction renvoie alors un 500 et Supabase le journalise. C’est mieux que le silence, mais cela traite une adresse mal formée comme une limite de débit, alors que les deux appellent des réponses opposées.
const RETRYABLE = new Set([429, 500, 502, 503, 504]);
async function withRetry<T>(call: () => Promise<T>, attempts = 3): Promise<T> {
for (let attempt = 1; ; attempt += 1) {
try {
return await call();
} catch (error) {
const status = error instanceof ApiError ? error.status : 0;
const transient = status === 0 || RETRYABLE.has(status);
if (!transient || attempt >= attempts) throw error;
await new Promise((resolve) => setTimeout(resolve, 2 ** attempt * 250));
}
}
}Un statut 0 couvre le cas où fetch lui-même a été rejeté, ce qui signifie généralement que la requête n’est jamais arrivée, mais parfois que la réponse s’est perdue au retour. La création ou mise à jour rend cette ambiguïté sans danger : si le premier appel a bien abouti, la nouvelle tentative met à jour le même contact au lieu d’en créer un second.
- Les limites de débit s’appliquent par clé API et par minute, et dépendent du forfait. Une rafale d’inscriptions en est la cause habituelle, et la solution est de patienter plutôt que de demander une limite plus haute.
- Les erreurs de validation doivent être journalisées avec le contenu qui les a provoquées. Il s’agit presque toujours d’un email manquant ou d’une propriété personnalisée qui n’existe pas encore.
- Un 401 signifie que la clé a été révoquée ou que le secret n’a jamais été défini dans l’environnement où vous avez déployé. Vérifiez
supabase secrets listavant toute autre chose.
L’exécuter en local avant de la déployer
Les Edge Functions tournent en local avec le même environnement qu’en production : il n’y a guère d’excuse pour découvrir une faute de frappe au déploiement. Mettez les secrets dans un fichier d’environnement local, lancez la fonction et appelez-la avec curl.
# supabase/functions/.env.local (git-ignored)
# SENDTIM_API_KEY=sk_test_xxxxxxxx
# WELCOME_AUTOMATION_ID=7c1f8e2a-...
supabase functions serve send-welcome --env-file supabase/functions/.env.local
curl -X POST http://localhost:54321/functions/v1/send-welcome \
-H "Content-Type: application/json" \
-d '{"email":"you+test@example.com","firstName":"Ana","plan":"free"}'Utilisez une variante avec « + » de votre propre adresse plutôt qu’une adresse inventée. Les adresses inventées rebondissent définitivement, et des rebonds sur un nouveau domaine d’envoi coûtent plus cher que les cinq secondes gagnées. Si l’automatisation est en pause, l’appel de déclenchement réussit quand même et rien ne part : un bon moyen de tester la tuyauterie sans écrire à personne.
La même fonction pour d’autres événements
Une fois ce modèle en place, chaque autre email du cycle de vie repose sur les deux mêmes appels avec un autre identifiant d’automatisation. Une ligne de subscriptions qui passe à past_due déclenche la séquence de relance de paiement. Une insertion dans orders déclenche le reçu. Une ligne de projects inactive depuis trente jours déclenche le rappel.
Passez l’identifiant d’automatisation dans le corps de la requête plutôt que d’en coder un par fonction, et une seule fonction send-lifecycle-email les gère tous. Si la correspondance entre déclencheurs et automatisations s’étend, rangez-la dans une petite table : ajouter un email devient alors une ligne plutôt qu’un déploiement.
Ce qui doit rester hors de ce code, c’est la distinction entre un reçu et une campagne. Les deux passent par la même API, mais l’email transactionnel obéit à d’autres règles de consentement, de timing et de domaine d’envoi, et c’est dans la plateforme que cette différence a sa place.
Questions fréquentes
Les Edge Functions Supabase peuvent-elles envoyer des emails directement ?
Pas seules. Les Edge Functions tournent sous Deno, qui ne prend pas en charge SMTP comme un processus Node, et Supabase n’inclut pas de serveur mail. Vous envoyez en faisant une requête HTTPS depuis la fonction vers l’API d’un fournisseur d’email, ce que Deno gère avec le fetch intégré, sans dépendance.
Faut-il appeler l’API email depuis un trigger Postgres ?
Seulement via pg_net, qui met la requête en file d’attente et rend la main immédiatement. Un trigger qui attend une réponse HTTP garde la transaction ouverte aussi longtemps que le tiers met à répondre : un fournisseur lent devient une inscription lente, et une panne devient une insertion échouée.
Où stocker la clé API d’une Edge Function ?
Dans les secrets Supabase, définis avec `supabase secrets set` et lus avec `Deno.env.get`. Ne la mettez ni dans la base de données, ni dans une migration, ni là où un bundle client peut l’atteindre. Si une clé apparaît un jour dans un dépôt ou un navigateur, renouvelez-la au lieu de supprimer le commit.
Comment éviter que la fonction envoie des emails en double ?
Créez ou mettez à jour le contact par email au lieu de le créer simplement, pour qu’un appel relancé mette à jour la fiche existante au lieu d’échouer, et ne réessayez que les réponses qui pourraient réussir à la deuxième tentative : 429, 5xx et erreurs réseau. Un 400 ne deviendra jamais valide ; le réessayer ne fait que multiplier le bruit dans les journaux.
Comment tester une Edge Function qui envoie des emails ?
Lancez `supabase functions serve` avec un fichier d’environnement local et appelez la fonction avec curl, en utilisant une variante avec « + » de votre propre adresse. Garder l’automatisation cible en pause permet de tester tout le parcours, appels d’API compris, sans rien envoyer à une vraie personne.
