E-Mail-Einrichtung

Auf dieser Seite

EmDash verwendet E-Mail für Magic-Link-Login, Benutzereinladungen und Kontowiederherstellung. Ein Provider stellt die Mail zu: entweder der in EmDash integrierte SMTP-Transport oder ein Provider-Plugin.

Dieser Leitfaden behandelt, wie die E-Mail-Pipeline funktioniert, was Sie in der Entwicklung out of the box erhalten und wie Sie einen echten Provider für die Produktion einrichten.

Wie E-Mail-Zustellung funktioniert

Ein einzelner aktiver Provider stellt alle ausgehenden Mails zu. Wenn kein Provider aktiv ist, sind Funktionen, die E-Mail benötigen, nicht verfügbar, und Einladungslinks müssen dann manuell von der Benutzerseite kopiert und geteilt werden.

Sie können den aktuellen Status unter Settings → Email im Admin sehen: ob ein Provider aktiv ist, welcher Provider es ist, und eine send test email-Schaltfläche, die die vollständige Pipeline testet.

Entwicklung: Integrierter Console Provider

In der Entwicklung (astro dev) aktiviert EmDash automatisch einen integrierten Console Provider, wenn kein anderer Provider aktiv ist. Er sendet nichts — er protokolliert jede E-Mail im Terminal und behält die letzten 100 Nachrichten im Speicher.

Das bedeutet, Magic Links und Einladungen funktionieren out of the box in der Entwicklung: Fordern Sie einen Magic Link an und kopieren Sie dann die URL aus Ihrer Terminal-Ausgabe. Sie können auch erfasste E-Mails am dev-only-Endpunkt GET /_emdash/api/dev/emails auflisten (und mit DELETE löschen).

Zeigt Settings → Email nach dem Hinzufügen eines Provider-Plugins oder der Einrichtung von SMTP weiterhin die Konsole an, wählen Sie dort diesen Provider aus und speichern Sie.

Der Console Provider ist nur für die Entwicklung und läuft nie in Produktions-Builds.

Produktion: Integrierter SMTP-Transport

Wenn Sie SMTP-Zugangsdaten haben (zum Beispiel für Brevo, Office 365, Fastmail, Amazon SES oder Ihren eigenen Mailserver), kann EmDash ohne Plugin darüber senden. Der Transport verlangt TLS, bevor er sich authentifiziert, unterstützt AUTH PLAIN und AUTH LOGIN und lehnt Port 25 ab.

Sie können ihn auf zwei Arten konfigurieren:

  • Im Admin: Öffnen Sie Settings → Email, wählen Sie SMTP, tragen Sie die Serverdaten ein und speichern Sie. Beim Speichern werden die Einstellungen in der Datenbank abgelegt und SMTP wird ausgewählt. EmDash verschlüsselt das Passwort mit EMDASH_ENCRYPTION_KEY, daher muss dieser Schlüssel gesetzt sein. Im Admin gespeicherte Einstellungen haben Vorrang vor Umgebungsvariablen. Ändern Sie das Passwort daher bei der Rotation im Admin.
  • Mit Umgebungsvariablen: Setzen Sie die folgenden Variablen in der Prozessumgebung des Servers. Verwenden Sie auf Cloudflare wrangler secret put und für die lokale Entwicklung .env. Unter Node lädt weder astro dev noch der gebaute Server .env; exportieren Sie die Variablen daher oder starten Sie den Server mit node --env-file=.env. Siehe Secrets & Key Management.
VariableBeispielHinweise
EMAIL_SMTP_HOSTsmtp.example.comErforderlich
EMAIL_SMTP_PORT587Optional; Standard ist 587. Verwenden Sie 465 für implizites TLS
EMAIL_SMTP_USER[email protected]Erforderlich; der SMTP-Login
EMAIL_SMTP_PASSyour-smtp-passwordErforderlich; speichern Sie es als Secret
EMAIL_SMTP_SECUREtls oder starttlsOptional; Port 465 verwendet tls, jeder andere Port verwendet starttls
EMAIL_SMTP_FROMMy Site <[email protected]>Optionaler Standardabsender
EMAIL_SMTP_FROM_NAMEMy SiteOptionaler Anzeigename für EMAIL_SMTP_FROM_EMAIL
EMAIL_SMTP_FROM_EMAIL[email protected]Optionale Absenderadresse; hat Vorrang vor EMAIL_SMTP_FROM
EMAIL_SMTP_REPLY_TO[email protected]Optionale Reply-To-Adresse

Ohne Absendervariable sendet EmDash von EMAIL_SMTP_USER. Ist Ihr SMTP-Login keine E-Mail-Adresse, setzen Sie EMAIL_SMTP_FROM_EMAIL oder EMAIL_SMTP_FROM, andernfalls schlägt die Zustellung mit Invalid sender address for SMTP delivery fehl. Settings → Email fragt in diesem Fall vor dem Speichern nach einer Absender-E-Mail.

Sind die Umgebungsvariablen vollständig, sendet EmDash über SMTP, es sei denn, ein E-Mail-Provider-Plugin ist aktiv oder unter Settings → Email ist ein anderer Provider ausgewählt. Um SMTP weiterhin neben einem Provider-Plugin zu verwenden, wählen Sie dort SMTP aus und speichern Sie.

Auf Cloudflare Workers benötigt der Transport das Kompatibilitäts-Flag nodejs_compat. Siehe den Cloudflare-Bereitstellungsleitfaden.

Produktion: Provider-Plugin installieren

Cloudflare Workers

Auf Cloudflare verwenden Sie das cloudflareEmail()-Plugin aus @emdash-cms/cloudflare/plugins. Es sendet über Cloudflare Email Sending über ein send_email Worker-Binding, sodass es kein externes Konto oder API-Schlüssel benötigt. Der Cloudflare-Bereitstellungsleitfaden führt durch das Onboarding der Absender-Domain, das Hinzufügen des Bindings und die Registrierung des Plugins.

Node und andere Plattformen

Die community-verwaltete emdash-smtp-Plugin-Familie deckt generisches SMTP plus gehostete Provider ab, einschließlich Amazon SES, Brevo, Mailgun, Postmark, Resend, SendGrid, Zoho und mehr.

pnpm add emdash-smtp

Die folgende Konfiguration registriert das Plugin bei EmDash:

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

export default defineConfig({
	integrations: [
		emdash({
			// ...Ihre Datenbank-/Speicherkonfiguration
			plugins: [emdashSmtp()],
		}),
	],
});

Provider-Anmeldeinformationen werden über die eigenen Einstellungen des Plugins konfiguriert — siehe dessen README für die Provider-Matrix und Setup-Details.

Wo Provider-Anmeldeinformationen gespeichert werden

Provider-Plugins deklarieren ihre API-Schlüssel und Passwörter als Plugin-Einstellungen. Geben Sie sie auf der Einstellungsseite des Plugins im Admin ein; EmDash speichert sie in der Datenbank neben anderen Plugin-Einstellungen, und das Rotieren eines Schlüssels bedeutet, den neuen Wert dort einzufügen. Secrets & Key Management beschreibt die Speicherung und ihre Einschränkungen.

Ob ein Plugin stattdessen ein Bereitstellungsgeheimnis (wrangler secret put, .env) lesen kann, hängt von seinem Format ab, folgen Sie also dessen README. Sandboxed Plugins können nicht auf process.env oder Plattform-Bindings zugreifen. Ein natives Plugin kann process.env lesen; es darf nicht import.meta.env verwenden, das zur Build-Zeit eingefügt wird und den Wert der Build-Maschine in das Bundle einbrennt.

Provider auswählen und testen

  1. Installieren und aktivieren Sie das Provider-Plugin und öffnen Sie dann Settings → Email im Admin.

  2. Wenn mehr als ein Provider-Plugin installiert ist, wählen Sie dort den aktiven aus — nur einer liefert zur Zeit.

  3. Verwenden Sie Send test email, um die vollständige Pipeline End-to-End zu verifizieren. Das Ergebnis zeigt Zustellungsfehler direkt, was der schnellste Weg ist, Anmeldeinformationen zu debuggen.

Fehlerbehebung

  • “No email provider is configured”: Kein Provider ist aktiv. Konfigurieren Sie SMTP oder aktivieren Sie ein Provider-Plugin und wählen Sie es dann in Settings → Email aus.
  • Magic Links / Einladungen stillschweigend nicht verfügbar — gleiche Ursache. Ohne Provider erstellt die Benutzerseite weiterhin Einladungen, aber Sie müssen den Einladungslink manuell kopieren.
  • Funktioniert in der Entwicklung, schlägt in der Produktion fehl — die Entwicklung verwendet den integrierten Console Provider, der einen fehlenden Produktions-Provider maskiert. Überprüfen Sie Settings → Email auf der bereitgestellten Site.
  • E-Mails landen im Spam — konfigurieren Sie SPF/DKIM/DMARC für Ihre Absender-Domain bei Ihrem E-Mail-Provider; dies ist Provider-seitig, keine EmDash-Einstellung.

Verwandt