Configuration des e-mails

Sur cette page

EmDash utilise l’e-mail pour la connexion par lien magique, les invitations d’utilisateurs et la récupération de compte. Un fournisseur délivre le courrier : soit le transport SMTP intégré à EmDash, soit un plugin de fournisseur.

Ce guide couvre le fonctionnement du pipeline d’e-mails, ce que vous obtenez prêt à l’emploi en développement et comment connecter un vrai fournisseur pour la production.

Comment fonctionne la livraison d’e-mails

Un seul fournisseur actif délivre tout le courrier sortant. Si aucun fournisseur n’est actif, les fonctionnalités nécessitant un e-mail ne sont pas disponibles, et les liens d’invitation doivent alors être copiés et partagés manuellement depuis la page Utilisateurs.

Vous pouvez voir l’état actuel sous Settings → Email dans l’administration : si un fournisseur est actif, quel fournisseur c’est, et un bouton send test email qui teste le pipeline complet.

Développement : Fournisseur console intégré

En développement (astro dev), EmDash active automatiquement un fournisseur console intégré lorsqu’aucun autre fournisseur n’est actif. Il n’envoie rien — il journalise chaque e-mail dans le terminal et conserve les 100 derniers messages en mémoire.

Cela signifie que les liens magiques et les invitations fonctionnent prêts à l’emploi en développement : demandez un lien magique, puis copiez l’URL depuis votre sortie de terminal. Vous pouvez également lister les e-mails capturés au point de terminaison réservé au développement GET /_emdash/api/dev/emails (et les effacer avec DELETE).

Si Settings → Email affiche toujours la console après l’ajout d’un plugin de fournisseur ou la configuration de SMTP, sélectionnez ce fournisseur à cet endroit et enregistrez.

Le fournisseur console est réservé au développement et ne s’exécute jamais dans les builds de production.

Production : Transport SMTP intégré

Si vous disposez d’identifiants SMTP (par exemple Brevo, Office 365, Fastmail, Amazon SES ou votre propre serveur de messagerie), EmDash peut envoyer via ceux-ci sans plugin. Le transport exige TLS avant de s’authentifier, prend en charge AUTH PLAIN et AUTH LOGIN, et refuse le port 25.

Vous pouvez le configurer de deux façons :

  • Dans l’admin : ouvrez Settings → Email, choisissez SMTP, renseignez les informations du serveur et enregistrez. L’enregistrement stocke les paramètres dans la base de données et sélectionne SMTP. EmDash chiffre le mot de passe avec EMDASH_ENCRYPTION_KEY, cette clé doit donc être définie. Les paramètres enregistrés dans l’admin ont priorité sur les variables d’environnement ; changez donc le mot de passe dans l’admin lorsque vous le renouvelez.
  • Avec des variables d’environnement : définissez les variables suivantes dans l’environnement de processus du serveur. Sur Cloudflare, utilisez wrangler secret put, et .env pour le développement local. Sur Node, ni astro dev ni le serveur compilé ne chargent .env ; exportez donc les variables ou démarrez le serveur avec node --env-file=.env. Voir Secrets & Key Management.
VariableExempleRemarques
EMAIL_SMTP_HOSTsmtp.example.comObligatoire
EMAIL_SMTP_PORT587Facultatif ; 587 par défaut. Utilisez 465 pour le TLS implicite
EMAIL_SMTP_USER[email protected]Obligatoire ; l’identifiant de connexion SMTP
EMAIL_SMTP_PASSyour-smtp-passwordObligatoire ; stockez-le comme secret
EMAIL_SMTP_SECUREtls ou starttlsFacultatif ; le port 465 utilise tls, tous les autres ports utilisent starttls
EMAIL_SMTP_FROMMy Site <[email protected]>Expéditeur par défaut facultatif
EMAIL_SMTP_FROM_NAMEMy SiteNom d’affichage facultatif pour EMAIL_SMTP_FROM_EMAIL
EMAIL_SMTP_FROM_EMAIL[email protected]Adresse d’expéditeur facultative ; prioritaire sur EMAIL_SMTP_FROM
EMAIL_SMTP_REPLY_TO[email protected]Adresse Reply-To facultative

Sans variable d’expéditeur, EmDash envoie depuis EMAIL_SMTP_USER. Si votre identifiant SMTP n’est pas une adresse e-mail, définissez EMAIL_SMTP_FROM_EMAIL ou EMAIL_SMTP_FROM, sinon l’envoi échoue avec Invalid sender address for SMTP delivery. Dans ce cas, Settings → Email demande une adresse e-mail d’expéditeur avant d’enregistrer.

Lorsque les variables d’environnement sont complètes, EmDash envoie via SMTP, sauf si un plugin de fournisseur d’e-mail est actif ou si un autre fournisseur est sélectionné sous Settings → Email. Pour continuer à utiliser SMTP en parallèle d’un plugin de fournisseur, sélectionnez SMTP à cet endroit et enregistrez.

Sur Cloudflare Workers, le transport nécessite le flag de compatibilité nodejs_compat. Voir le guide de déploiement Cloudflare.

Production : Installer un plugin de fournisseur

Cloudflare Workers

Sur Cloudflare, utilisez le plugin cloudflareEmail() de @emdash-cms/cloudflare/plugins. Il envoie via Cloudflare Email Sending sur une liaison send_email du Worker, donc il n’a besoin d’aucun compte externe ni clé API. Le guide de déploiement Cloudflare vous guide à travers l’intégration du domaine expéditeur, l’ajout de la liaison et l’enregistrement du plugin.

Node et autres plateformes

La famille de plugins maintenue par la communauté emdash-smtp couvre le SMTP générique plus les fournisseurs hébergés, y compris Amazon SES, Brevo, Mailgun, Postmark, Resend, SendGrid, Zoho et plus.

pnpm add emdash-smtp

La configuration suivante enregistre le plugin avec EmDash :

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { emdashSmtp } from "emdash-smtp";

export default defineConfig({
	integrations: [
		emdash({
			// ...votre configuration de base de données/stockage
			plugins: [emdashSmtp()],
		}),
	],
});

Les informations d’identification du fournisseur sont configurées via les propres paramètres du plugin — consultez son README pour la matrice des fournisseurs et les détails de configuration.

Où résident les informations d’identification du fournisseur

Les plugins de fournisseur déclarent leurs clés API et mots de passe en tant que paramètres de plugin. Saisissez-les sur la page de paramètres du plugin dans l’administration ; EmDash les stocke dans la base de données aux côtés d’autres paramètres de plugin, et la rotation d’une clé signifie coller la nouvelle valeur là. Secrets & Key Management décrit le stockage et ses mises en garde.

Le fait qu’un plugin puisse lire un secret de déploiement (wrangler secret put, .env) dépend de son format, suivez donc son README. Les plugins sandbox ne peuvent pas accéder à process.env ou aux liaisons de plateforme. Un plugin natif peut lire process.env ; il ne doit pas utiliser import.meta.env, qui est intégré au moment de la compilation et cuit la valeur de la machine de build dans le bundle.

Sélectionner un fournisseur et tester

  1. Installez et activez le plugin de fournisseur, puis ouvrez Settings → Email dans l’administration.

  2. Si plus d’un plugin de fournisseur est installé, choisissez celui qui est actif là — un seul délivre à la fois.

  3. Utilisez Send test email pour vérifier le pipeline complet de bout en bout. Le résultat révèle directement les erreurs de livraison, ce qui est le moyen le plus rapide de déboguer les informations d’identification.

Dépannage

  • “No email provider is configured” : aucun fournisseur n’est actif. Configurez SMTP ou activez un plugin de fournisseur, puis sélectionnez-le dans Settings → Email.
  • Liens magiques / invitations silencieusement indisponibles — même cause. Sans fournisseur, la page Utilisateurs crée toujours des invitations, mais vous devez copier le lien d’invitation manuellement.
  • Fonctionne en développement, échoue en production — le développement utilise le fournisseur console intégré, qui masque un fournisseur de production manquant. Vérifiez Settings → Email sur le site déployé.
  • Les e-mails atterrissent dans les spams — configurez SPF/DKIM/DMARC pour votre domaine d’envoi chez votre fournisseur d’e-mails ; c’est côté fournisseur, pas un paramètre EmDash.

Connexe