Gmail (OAuth)

Die Gmail-Integration sendet Frontmail-Vorlagen über die Gmail API aus Ihrem eigenen Gmail- oder Google-Workspace-Postfach. Gesendete Nachrichten erscheinen in Ihrem Ordner Gesendet, Antworten landen in Ihrem Posteingang, und Empfänger sehen eine ganz normale E-Mail von Ihnen.

Wählen Sie Gmail, wenn Sie eine private Website, ein Portfolio oder ein kleines Unternehmen betreiben und Formulareinsendungen und Benachrichtigungen von der Adresse kommen sollen, die Sie ohnehin nutzen – bei @gmail.com ganz ohne DNS-Einrichtung. Für größere Volumen ist Gmail nicht gedacht: Google begrenzt den täglichen Versand (siehe Versandlimits), und es gibt keine Zustell-Webhooks. Für transaktionale Volumen nutzen Sie Mailgun, Postmark, Amazon SES oder Resend. Siehe die Übersicht der E-Mail-Dienste.

OAuth statt App-Passwörtern

Sie können Gmail auch per SMTP mit einem App-Passwort verbinden, OAuth ist aber sicherer: Frontmail sieht Ihr Passwort nie, die Berechtigung ist auf das Senden beschränkt, und Sie können sie jederzeit in Ihrem Google-Konto widerrufen.

Voraussetzungen

• Ein Gmail-Konto (@gmail.com) oder ein Google-Workspace-Nutzer mit aktiviertem Gmail.
• Bei Workspace: Ihr Administrator muss Drittanbieter-Apps den Zugriff auf Google-Daten erlauben oder Frontmail ausdrücklich als vertrauenswürdig einstufen unter Admin console → Security → Access and data control → API controls → App access control.
• Sonst nichts – kein API-Schlüssel, kein Google-Cloud-Projekt.

In Frontmail verbinden

1. Öffnen Sie E-Mail-Dienste → Dienst hinzufügen → Gmail.
2. Klicken Sie auf Gmail verbinden. Sie werden zu Google weitergeleitet.
3. Wählen Sie das Konto und prüfen Sie den Zustimmungsbildschirm. Frontmail fragt nach:
   • https://www.googleapis.com/auth/gmail.send – E-Mails in Ihrem Namen senden. Das ist eine reine Sendeberechtigung: Frontmail kann in Ihrem Postfach keine E-Mails lesen, durchsuchen, löschen oder ändern.
   • openid email – Ihre E-Mail-Adresse, damit das Dashboard anzeigen kann, welches Konto verbunden ist, und sie als Standard-Absenderadresse verwenden kann.
4. Klicken Sie auf Allow. Google leitet Sie zurück, und der Dienst wird mit der verbundenen Adresse gespeichert.
5. Legen Sie optional Max. E-Mails pro Sekunde fest (Standard 2/s) und klicken Sie auf Verbindung testen – dabei wird das Zugriffstoken erneuert und geprüft, ob die Berechtigung gmail.send erteilt wurde.

Was gespeichert wird: Frontmail speichert das OAuth-Refresh-Token (und ein kurzlebiges Access-Token), verschlüsselt mit AWS KMS per Envelope-Verschlüsselung. Das Access-Token läuft nach etwa einer Stunde ab; Frontmail erneuert es vor dem Senden unbemerkt. Der Ablauf nutzt PKCE und fordert immer Offline-Zugriff an, sodass ein erneutes Verbinden ein frisches Refresh-Token ausstellt.

Verifizierung der App

Die produktive OAuth-App von Frontmail ist von Google für die Berechtigung gmail.send verifiziert. Sie sehen daher den Namen Frontmail und keine Warnung „unverified app“.

Wenn das Token nicht mehr funktioniert

Google macht ein Refresh-Token ungültig, wenn Sie:

• den Zugriff unter Google-Konto → Sicherheit → Drittanbieter-Apps und -Dienste → Frontmail widerrufen,
• das Passwort Ihres Google-Kontos ändern (bei Gmail-Berechtigungen widerruft Google bestehende Tokens),
• das Token 6 Monate lang nicht verwenden,
• oder ein Workspace-Administrator der App den Zugriff entzieht.

Der nächste Versand oder die nächste Statusprüfung schlägt dann mit invalid_grant fehl. Frontmail behandelt das als auth-Fehler: Der Dienst wird als unhealthy markiert, Sie erhalten eine E-Mail und ein Banner im Dashboard, und Nachrichten werden zurückgehalten (oder über den Ersatzdienst gesendet), bis Sie auf der Seite des Dienstes auf Neu verbinden klicken. Das erneute Verbinden erzeugt ein neues Refresh-Token und gibt zurückgehaltene Nachrichten automatisch frei.

Eigene OAuth-Apps im Status „Testing“

Wenn Sie Frontmail mit einem eigenen OAuth-Client in Google Cloud betreiben, dessen Veröffentlichungsstatus Testing ist, lässt Google Refresh-Tokens nach 7 Tagen ablaufen – der Dienst wird dann jede Woche unhealthy. Veröffentlichen Sie die App (und schließen Sie die Verifizierung für die sensible Berechtigung gmail.send ab), damit die Tokens bestehen bleiben. Die gehostete App auf frontmail.dev ist davon nicht betroffen.

DNS: SPF, DKIM und DMARC

• Adressen @gmail.com: nichts zu tun – Google signiert und authentifiziert die Mails selbst.
• Google Workspace auf eigener Domain: Veröffentlichen Sie die Einträge von Google, falls noch nicht geschehen:

; SPF
example.de.                    TXT  "v=spf1 include:_spf.google.com ~all"

; DKIM – erzeugen unter Admin console → Apps → Google Workspace → Gmail → Authenticate email
google._domainkey.example.de.  TXT  "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A…"

; DMARC
_dmarc.example.de.             TXT  "v=DMARC1; p=none; rua=mailto:dmarc@example.de"

Nachdem Sie den DKIM-Eintrag veröffentlicht haben, klicken Sie in der Admin console auf Start authentication. Verschärfen Sie DMARC auf p=quarantine / p=reject, sobald die Berichte sauber aussehen.

Hinweis

Die Anforderungen von Google an Massenversender aus dem Jahr 2024 gelten für alle Mails an Gmail-Nutzer, egal von wo – auch aus Workspace. Ein Kontaktformular erreicht die Schwelle von 5.000 Nachrichten pro Tag nicht, SPF + DKIM + DMARC auf Ihrer Workspace-Domain sind trotzdem empfehlenswert.

Absenderadresse: Gmail sendet als das verbundene Konto. Eine andere Adresse können Sie nur verwenden, wenn sie in den Gmail-Einstellungen als Alias unter Senden als eingerichtet ist; andernfalls ersetzt Gmail die Absenderadresse durch die Adresse des Kontos.

Regionen

Es gibt keine Regionen – die Gmail API ist global.

Versandlimits

Google setzt tägliche Limits pro Nutzer durch. Wer sie überschreitet, kann bis zu 24 Stunden lang nicht senden.

Konto	Ungefähres Limit
Privates Gmail (@gmail.com)	ca. 500 Empfänger pro Tag
Google Workspace	ca. 2.000 Nachrichten pro Tag (im Testzeitraum weniger)
Gmail API	250 Kontingenteinheiten pro Nutzer und Sekunde; ein Versand = 100 Einheiten

Frontmail sendet über Gmail daher höchstens 2 Nachrichten pro Sekunde. Antwortet Google mit dailyLimitExceeded, wartet Frontmail zwischen den Versuchen jeweils eine Stunde; besteht das Limit weiter, endet die Nachricht als failed und der Credit wird erstattet.

Zustellverfolgung (Webhooks)

Gmail hat keine Zustell-Webhooks – es gibt also nichts zu konfigurieren und auf der Seite des Dienstes keine Webhook-URL. Frontmail weiß nur, ob Google die Nachricht angenommen (sent) oder abgelehnt (failed) hat. Bounces kommen als normale E-Mails „Delivery Status Notification“ in Ihrem Gmail-Posteingang an und werden nicht automatisch auf die Sperrliste von Frontmail gesetzt. Öffnungen und Klicks werden nicht erfasst.

Häufige Fehler

• auth – der Dienst funktioniert nicht (Token widerrufen oder abgelaufen, invalid_grant, 401/403, Gmail für den Workspace-Nutzer nicht aktiviert). Der Dienst wird als unhealthy markiert; der Inhaber erhält eine E-Mail und ein Banner im Dashboard. Der Ersatzdienst der Vorlage übernimmt; andernfalls wird der Credit erstattet und die Nachricht wartet als held_service_error in der Warteschlange zurückgehaltener E-Mails und wird nach dem erneuten Verbinden automatisch gesendet (geprüft beim Speichern und bei der täglichen Statusprüfung).
• permanent – genau diese Nachricht kann nicht gesendet werden (ungültiger Empfänger, Nachricht zu groß, Validierungsfehler 400). Ersatzdienst, falls eingerichtet, sonst failed und Erstattung.
• transient – 5xx, Rate- und Tageslimits, Timeouts. Wiederholung mit exponentiellem Backoff; nach dem letzten Versuch failed und Erstattung.

Antwort von Google	Klasse	Was zu tun ist
invalid_grant – Token has been expired or revoked	auth	Klicken Sie auf der Seite des Dienstes auf Neu verbinden und erteilen Sie den Zugriff erneut.
401 – Invalid Credentials	auth	Wird meist durch die automatische Token-Erneuerung behoben; bleibt der Fehler, verbinden Sie neu.
403 – Insufficient Permission / insufficient_scope	auth	Auf dem Zustimmungsbildschirm wurde das Senden abgewählt – verbinden Sie neu und erlauben Sie das Senden.
403 – Zugriff vom Workspace-Administrator blockiert	auth	Bitten Sie Ihren Administrator, Frontmail unter API controls als vertrauenswürdig einzustufen.
400 failedPrecondition – Mail service not enabled	auth	Der Workspace-Nutzer hat keine Gmail-Lizenz; aktivieren Sie Gmail oder verbinden Sie ein anderes Konto.
400 invalidArgument – Invalid To header	permanent	Siehe ungültiger Empfänger.
413 / 400 – Nachricht zu groß	permanent	Verkleinern Sie die Anhänge (das Limit von Gmail liegt bei 25 MB).
429 / 403 rateLimitExceeded, userRateLimitExceeded, dailyLimitExceeded	transient	Senden Sie langsamer oder warten Sie, bis das Tageslimit zurückgesetzt wird; erwägen Sie einen transaktionalen Anbieter.
500 / 503 backendError	transient	Störung bei Google – Frontmail wiederholt den Versand.

Checkliste

• Über Gmail verbinden verbunden; Zustimmung zum Senden von E-Mails erteilt
• Workspace: Frontmail in den API controls erlaubt (falls eingeschränkt)
• Workspace auf eigener Domain: SPF include:_spf.google.com, DKIM google._domainkey, DMARC
• Absenderadresse der Vorlage = die verbundene Adresse oder ein eingerichteter Alias unter Senden als
• Verbindung testen erfolgreich
• Tägliches Volumen deutlich unter den Limits von Google
• Ersatzdienst für wichtige Vorlagen eingerichtet, falls das Token widerrufen wird