Fehlerbehebung

Beginnen Sie beim Fehlercode: Jeder API-Fehler enthält code und docs_url, und die Seite Fehlercodes erklärt jeden einzelnen. Der Verlauf zeigt jede angenommene Nachricht mit ihrer Zeitleiste, der Antwort des Anbieters und dem gerenderten Inhalt.

Die Anfrage schlägt fehl

403 origin_not_allowed – Tragen Sie die Domain Ihrer Website unter Sicherheit → Erlaubte Websites ein (und für die Entwicklung localhost). Prüfen Sie den genauen Host, einschließlich www.. Bei details.reason: "no_origin" hatte die Anfrage überhaupt keinen Origin (native App, Serverskript): Schalten Sie für Apps Mobile Apps erlauben ein, verwenden Sie auf Servern einen privaten Schlüssel. Siehe Erlaubte Domains.

403 private_key_in_browser – Ein privater Schlüssel wurde aus einer Webseite heraus verwendet. Nutzen Sie im Browser den öffentlichen Schlüssel und belassen Sie den privaten auf Ihrem Server. Siehe Schlüssel.

403 captcha_required / captcha_failed – Die Vorlage verlangt Turnstile. Rendern Sie das Widget innerhalb des Formulars oder übergeben Sie turnstileToken; setzen Sie das Widget nach jedem Versuch zurück, denn Tokens gelten nur einmal. captcha_failed mit hostname_mismatch bedeutet, dass das Widget auf einem anderen Hostnamen gelöst wurde als dem Origin der Anfrage – tragen Sie alle Hostnamen Ihrer Website in Ihr Turnstile-Widget ein. Siehe Turnstile.

403 captcha_not_configured – Die Vorlage verlangt das CAPTCHA, aber Ihre Organisation hat noch keine eigenen Turnstile-Schlüssel hinterlegt. Erstellen Sie in Cloudflare ein kostenloses Widget und tragen Sie dessen Site Key und Secret Key unter Sicherheit → Bot-Schutz (Turnstile) ein – oder schalten Sie das CAPTCHA in der Vorlage aus.

422 invalid_template_params – Sehen Sie sich details.issues an: Jeder Eintrag nennt den param und die verletzte Regel. Häufige Ursachen: Ein Pflichtfeld ist leer, ein email-Parameter hat einen Namen bekommen, ein number-Parameter "12 Stk.", ein list-Parameter einen String, der kein JSON ist.

403 dynamic_recipient_not_allowed – To/CC/BCC der Vorlage verwendet einen Parameter. Nutzen Sie für Bestätigungen eine automatische Antwort oder schalten Sie Dynamischen Empfänger erlauben unter Einstellungen → Schutz der Vorlage ein.

429 rate_limited – Sie haben das Limit des Tarifs, der IP oder des Schlüssels überschritten. Das SDK hat bereits gewartet und es erneut versucht. Für Massenversand vom Server nutzen Sie den Batch-Versand.

CORS-Fehler in der Browserkonsole – Meist steckt ein anderer Fehler dahinter: Die Anfrage wurde von einer Content-Security-Policy (connect-src) oder einem Werbeblocker blockiert oder ging an eine falsche apiUrl. Die Frontmail-API sendet CORS-Header für alle Origins; der Zugriff wird über die erlaubten Domains gesteuert.

Die Anfrage klappt, aber es kommt keine E-Mail an

1. Suchen Sie die Nachricht im Verlauf.
   • held – Ihre Credits sind aufgebraucht. Kaufen Sie ein Credit-Paket (Credits kaufen) oder warten Sie auf die Erneuerung; die Nachricht wird automatisch gesendet. Sie steht auch unter Zurückgehaltene E-Mails. Siehe Warteschlange zurückgehaltener E-Mails.
   • held_service_error – die Zugangsdaten Ihres E-Mail-Dienstes funktionieren nicht mehr. Öffnen Sie E-Mail-Dienste und reparieren oder verbinden Sie den Dienst neu; zurückgehaltene Nachrichten werden danach automatisch gesendet.
   • failed – öffnen Sie die Nachricht: Der Fehler des Anbieters steht in der Zeitleiste. Typische Ursachen sind eine nicht verifizierte Absenderdomain oder ein ungültiger Empfänger.
   • sent – der Anbieter hat die Nachricht angenommen. Lesen Sie weiter.
2. Prüfen Sie den Spam-Ordner. Liegt die Nachricht dort, richten Sie SPF, DKIM und DMARC für Ihre From-Domain ein, wie in der Anleitung Ihres Anbieters beschrieben, und verwenden Sie eine From-Adresse auf dieser Domain (keine @gmail.com-Adresse über einen Transaktionsanbieter).
3. Prüfen Sie die Sperrliste. Versände an gesperrte Adressen schlagen mit 451 fehl – und auch wenn Sie die Adresse nach einem Bounce von der Liste entfernt haben, existiert das Postfach vielleicht immer noch nicht.
4. Richten Sie Webhooks ein, um die Ereignisse delivered / bounced zu sehen, statt zu raten.

Der E-Mail-Dienst fällt immer wieder aus

• Gmail: Google widerruft Refresh-Tokens, wenn sich das Passwort ändert, wenn der Benutzer den Zugriff der App entfernt oder nach 6 Monaten ohne Nutzung. Verbinden Sie den Dienst neu.
• API-Anbieter: Der Schlüssel wurde rotiert oder seine Berechtigungen eingeschränkt. Erstellen Sie einen Schlüssel mit send-Berechtigung und aktualisieren Sie den Dienst.
• SMTP: Das Passwort des Postfachs hat sich geändert, oder der Anbieter verlangt bei aktivierter 2FA ein App-Passwort.

Richten Sie einen Ersatzdienst ein, damit ein defekter Dienst Ihre Formulare nicht lahmlegt, während Sie ihn reparieren.

E-Mails sehen falsch aus

• Styles fehlen in Gmail oder Outlook → schalten Sie in den Einstellungen der Vorlage CSS beim Speichern inline setzen ein.
• Text wird mit „Gesamte Nachricht anzeigen“ abgeschnitten → die E-Mail ist größer als ~100 kB; entfernen Sie eingebettete Bilder oder umfangreiche Styles.
• In der E-Mail steht wörtlich <b> → der Wert wurde escaped. Wenn Sie wirklich Markup brauchen, verwenden Sie einen html-Parameter (siehe Escaping).
• Datumsangaben in falscher Sprache oder Zeitzone → legen Sie die Sprache (Locale) der Vorlage und die Zeitzone Ihrer Organisation fest oder übergeben Sie formatDate den Parameter timeZone=.

Immer noch nicht gelöst?

Schreiben Sie an support@frontmail.dev und geben Sie die message_id an (oder den code und den Zeitpunkt des Fehlers). Senden Sie niemals Ihren privaten Schlüssel mit.