Configurazione e-mail

In questa pagina

EmDash utilizza l’e-mail per login con link magico, inviti utente e recupero account. Un provider consegna la posta: il trasporto SMTP integrato in EmDash oppure un plugin provider.

Questa guida copre come funziona la pipeline e-mail, cosa ottieni pronto all’uso in sviluppo e come collegare un vero provider per la produzione.

Come funziona la consegna e-mail

Un singolo provider attivo consegna tutta la posta in uscita. Se nessun provider è attivo, le funzionalità che necessitano di e-mail non sono disponibili e i link di invito devono quindi essere copiati e condivisi manualmente dalla pagina Utenti.

Puoi vedere lo stato corrente in Settings → Email nell’amministrazione: se un provider è attivo, quale provider è, e un pulsante send test email che esercita l’intera pipeline.

Sviluppo: Provider console integrato

In sviluppo (astro dev), EmDash attiva automaticamente un provider console integrato quando nessun altro provider è attivo. Non invia nulla — registra ogni e-mail nel terminale e mantiene gli ultimi 100 messaggi in memoria.

Ciò significa che i link magici e gli inviti funzionano pronti all’uso in sviluppo: richiedi un link magico, quindi copia l’URL dal tuo output del terminale. Puoi anche elencare le e-mail catturate all’endpoint solo sviluppo GET /_emdash/api/dev/emails (e cancellarle con DELETE).

Se Settings → Email continua a mostrare la console dopo aver aggiunto un plugin provider o configurato SMTP, seleziona lì quel provider e salva.

Il provider console è solo per sviluppo e non viene mai eseguito nelle build di produzione.

Produzione: Trasporto SMTP integrato

Se hai credenziali SMTP (ad esempio Brevo, Office 365, Fastmail, Amazon SES o il tuo server di posta), EmDash può inviare tramite di esse senza un plugin. Il trasporto richiede TLS prima di autenticarsi, supporta AUTH PLAIN e AUTH LOGIN e rifiuta la porta 25.

Puoi configurarlo in due modi:

  • Nell’admin: apri Settings → Email, scegli SMTP, compila i dati del server e salva. Il salvataggio memorizza le impostazioni nel database e seleziona SMTP. EmDash cifra la password con EMDASH_ENCRYPTION_KEY, quindi quella chiave deve essere impostata. Le impostazioni salvate nell’admin hanno la precedenza sulle variabili d’ambiente, quindi cambia la password nell’admin quando la ruoti.
  • Con le variabili d’ambiente: imposta le seguenti variabili nell’ambiente di processo del server. Su Cloudflare usa wrangler secret put, e .env per lo sviluppo locale. Su Node, né astro dev né il server compilato caricano .env, quindi esporta le variabili o avvia il server con node --env-file=.env. Vedi Secrets & Key Management.
VariabileEsempioNote
EMAIL_SMTP_HOSTsmtp.example.comObbligatoria
EMAIL_SMTP_PORT587Facoltativa; predefinita 587. Usa 465 per TLS implicito
EMAIL_SMTP_USER[email protected]Obbligatoria; il login SMTP
EMAIL_SMTP_PASSyour-smtp-passwordObbligatoria; memorizzala come secret
EMAIL_SMTP_SECUREtls o starttlsFacoltativa; la porta 465 usa tls, ogni altra porta usa starttls
EMAIL_SMTP_FROMMy Site <[email protected]>Mittente predefinito facoltativo
EMAIL_SMTP_FROM_NAMEMy SiteNome visualizzato facoltativo per EMAIL_SMTP_FROM_EMAIL
EMAIL_SMTP_FROM_EMAIL[email protected]Indirizzo mittente facoltativo; ha la precedenza su EMAIL_SMTP_FROM
EMAIL_SMTP_REPLY_TO[email protected]Indirizzo Reply-To facoltativo

Senza una variabile per il mittente, EmDash invia da EMAIL_SMTP_USER. Se il tuo login SMTP non è un indirizzo e-mail, imposta EMAIL_SMTP_FROM_EMAIL o EMAIL_SMTP_FROM, altrimenti la consegna fallisce con Invalid sender address for SMTP delivery. In questo caso Settings → Email chiede un’e-mail del mittente prima di salvare.

Quando le variabili d’ambiente sono complete, EmDash invia tramite SMTP, a meno che non sia attivo un plugin provider e-mail o non sia selezionato un altro provider in Settings → Email. Per continuare a usare SMTP insieme a un plugin provider, seleziona lì SMTP e salva.

Su Cloudflare Workers, il trasporto richiede il flag di compatibilità nodejs_compat. Vedi la guida al deployment su Cloudflare.

Produzione: Installare un plugin provider

Cloudflare Workers

Su Cloudflare, usa il plugin cloudflareEmail() da @emdash-cms/cloudflare/plugins. Invia tramite Cloudflare Email Sending su un binding send_email del Worker, quindi non necessita di account esterno o chiave API. La guida al deployment Cloudflare ti guida attraverso l’onboarding del dominio mittente, l’aggiunta del binding e la registrazione del plugin.

Node e altre piattaforme

La famiglia di plugin mantenuta dalla comunità emdash-smtp copre SMTP generico più provider ospitati, inclusi Amazon SES, Brevo, Mailgun, Postmark, Resend, SendGrid, Zoho e altri.

pnpm add emdash-smtp

La seguente configurazione registra il plugin con EmDash:

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

export default defineConfig({
	integrations: [
		emdash({
			// ...la tua configurazione di database/storage
			plugins: [emdashSmtp()],
		}),
	],
});

Le credenziali del provider sono configurate tramite le impostazioni proprie del plugin — vedi il suo README per la matrice dei provider e i dettagli di configurazione.

Dove risiedono le credenziali del provider

I plugin provider dichiarano le loro chiavi API e password come impostazioni del plugin. Inseriscile nella pagina delle impostazioni del plugin nell’amministrazione; EmDash le memorizza nel database insieme ad altre impostazioni del plugin, e ruotare una chiave significa incollare il nuovo valore lì. Secrets & Key Management descrive lo storage e le sue avvertenze.

Se un plugin può leggere un segreto di deployment (wrangler secret put, .env) dipende dal suo formato, quindi segui il suo README. I plugin sandbox non possono accedere a process.env o ai binding della piattaforma. Un plugin nativo può leggere process.env; non deve usare import.meta.env, che viene inserito al momento della build e cuoce il valore della macchina di build nel bundle.

Selezionare un provider e testare

  1. Installa e attiva il plugin provider, quindi apri Settings → Email nell’amministrazione.

  2. Se è installato più di un plugin provider, scegli quello attivo lì — solo uno consegna alla volta.

  3. Usa Send test email per verificare l’intera pipeline end-to-end. Il risultato rivela direttamente gli errori di consegna, che è il modo più veloce per debuggare le credenziali.

Risoluzione dei problemi

  • “No email provider is configured”: nessun provider è attivo. Configura SMTP o attiva un plugin provider, quindi selezionalo in Settings → Email.
  • Link magici / inviti silenziosamente non disponibili — stessa causa. Senza un provider, la pagina Utenti crea comunque inviti, ma devi copiare il link di invito manualmente.
  • Funziona in sviluppo, fallisce in produzione — lo sviluppo usa il provider console integrato, che maschera un provider di produzione mancante. Verifica Settings → Email sul sito distribuito.
  • Le e-mail finiscono nello spam — configura SPF/DKIM/DMARC per il tuo dominio mittente presso il tuo provider e-mail; questo è lato provider, non un’impostazione EmDash.

Correlati