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.envper lo sviluppo locale. Su Node, néastro devné il server compilato caricano.env, quindi esporta le variabili o avvia il server connode --env-file=.env. Vedi Secrets & Key Management.
| Variabile | Esempio | Note |
|---|---|---|
EMAIL_SMTP_HOST | smtp.example.com | Obbligatoria |
EMAIL_SMTP_PORT | 587 | Facoltativa; predefinita 587. Usa 465 per TLS implicito |
EMAIL_SMTP_USER | [email protected] | Obbligatoria; il login SMTP |
EMAIL_SMTP_PASS | your-smtp-password | Obbligatoria; memorizzala come secret |
EMAIL_SMTP_SECURE | tls o starttls | Facoltativa; la porta 465 usa tls, ogni altra porta usa starttls |
EMAIL_SMTP_FROM | My Site <[email protected]> | Mittente predefinito facoltativo |
EMAIL_SMTP_FROM_NAME | My Site | Nome 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
-
Installa e attiva il plugin provider, quindi apri Settings → Email nell’amministrazione.
-
Se è installato più di un plugin provider, scegli quello attivo lì — solo uno consegna alla volta.
-
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
- Autenticazione — link magici, inviti e flussi di recupero che si basano sull’e-mail
- Riferimento hook e-mail —
email:beforeSend,email:deliver,email:afterSend