Gmail (OAuth)

Integracja z Gmailem wysyła szablony Frontmail z twojej własnej skrzynki Gmail lub Google Workspace przez Gmail API. Wysłane wiadomości pojawiają się w folderze Wysłane, odpowiedzi wracają do twojej skrzynki odbiorczej, a odbiorcy widzą zwykły e-mail od ciebie.

Wybierz Gmaila, gdy prowadzisz stronę prywatną, portfolio lub małą firmę i chcesz, żeby zgłoszenia z formularzy i powiadomienia przychodziły z adresu, którego już używasz – bez konfiguracji DNS, jeśli masz adres @gmail.com. Gmail nie nadaje się do dużych wolumenów: Google ogranicza dzienną wysyłkę (zobacz Limity) i nie ma webhooków doręczeń. Do transakcyjnych wolumenów użyj Mailgun, Postmark, Amazon SES lub Resend. Zobacz przegląd usług.

OAuth zamiast haseł aplikacji

Gmaila możesz podłączyć także przez SMTP z hasłem aplikacji, ale OAuth jest bezpieczniejszy: Frontmail nigdy nie widzi twojego hasła, uprawnienie jest ograniczone do wysyłania, a w każdej chwili możesz je cofnąć na swoim koncie Google.

Wymagania

• Konto Gmail (@gmail.com) albo użytkownik Google Workspace z włączonym Gmailem.
• W Workspace: administrator musi zezwolić aplikacjom zewnętrznym na dostęp do danych Google albo jawnie oznaczyć Frontmail jako zaufany w Admin console → Security → Access and data control → API controls → App access control.
• Nic więcej – bez klucza API, bez projektu w Google Cloud.

Podłączenie we Frontmail

1. Otwórz Usługi e-mail → Dodaj usługę → Gmail.
2. Kliknij Połącz z Gmail. Nastąpi przekierowanie do Google.
3. Wybierz konto i przejrzyj ekran zgody. Frontmail prosi o:
   • https://www.googleapis.com/auth/gmail.send – wysyłanie e-maili w twoim imieniu. To zakres tylko do wysyłania: Frontmail nie może czytać, przeszukiwać, usuwać ani zmieniać żadnych e-maili w twojej skrzynce.
   • openid email – twój adres e-mail, żeby panel mógł pokazać, które konto jest podłączone, i użyć go jako domyślnego adresu nadawcy.
4. Kliknij Allow (Zezwól). Google przekieruje cię z powrotem, a usługa zostanie zapisana z widocznym podłączonym adresem.
5. Opcjonalnie ustaw Maks. liczba e-maili na sekundę (domyślnie 2/s) i kliknij Testuj połączenie, które odświeży token dostępu i sprawdzi, czy przyznano uprawnienie gmail.send.

Co jest przechowywane: Frontmail przechowuje refresh token OAuth (i krótkotrwały token dostępu), zaszyfrowany kopertowo przez AWS KMS. Token dostępu wygasa po około godzinie; Frontmail po cichu odświeża go przed wysyłką. Przepływ używa PKCE i zawsze prosi o dostęp offline, więc ponowne połączenie wydaje nowy refresh token.

Weryfikacja aplikacji

Produkcyjna aplikacja OAuth Frontmail jest zweryfikowana przez Google dla zakresu gmail.send, więc widzisz nazwę Frontmail i żadnego ostrzeżenia o „niezweryfikowanej aplikacji”.

Gdy token przestaje działać

Google unieważnia refresh token, gdy:

• cofniesz dostęp w Google Account → Security → Third-party apps & services → Frontmail,
• zmienisz hasło do konta Google (w przypadku zakresów Gmaila Google unieważnia istniejące tokeny),
• token nie będzie używany przez 6 miesięcy,
• albo administrator Workspace odbierze aplikacji dostęp.

Kolejna wysyłka lub health check kończy się wtedy błędem invalid_grant. Frontmail traktuje go jako błąd auth: usługa zostaje oznaczona jako unhealthy, dostajesz e-mail i baner w panelu, a wiadomości są wstrzymywane (albo wysyłane przez usługę zapasową), dopóki nie klikniesz Połącz ponownie na stronie usługi. Ponowne połączenie tworzy nowy refresh token i automatycznie zwalnia wstrzymane wiadomości.

Własne aplikacje OAuth / w trybie „Testing”

Jeśli używasz Frontmail z własnym klientem OAuth w Google Cloud, którego status publikacji to Testing, Google unieważnia refresh tokeny po 7 dniach – usługa co tydzień będzie przechodzić w stan unhealthy. Opublikuj aplikację (i przejdź weryfikację wrażliwego zakresu gmail.send), żeby tokeny były trwałe. Nie dotyczy to hostowanej aplikacji frontmail.dev.

DNS: SPF, DKIM i DMARC

• Adresy @gmail.com: nic nie musisz robić – Google podpisuje i uwierzytelnia pocztę.
• Google Workspace we własnej domenie: opublikuj rekordy Google, jeśli jeszcze tego nie zrobiono:

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

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

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

Po opublikowaniu rekordu DKIM kliknij Start authentication w Admin console. Gdy raporty będą czyste, zaostrz DMARC do p=quarantine / p=reject.

Notatka

Wymagania Google z 2024 roku dla nadawców masowych dotyczą poczty wysyłanej do użytkowników Gmaila z dowolnego miejsca – także z Workspace. Formularz kontaktowy nie dobije do progu 5000 dziennie, ale SPF + DKIM + DMARC w twojej domenie Workspace i tak są zalecane.

Adres nadawcy: Gmail wysyła jako podłączone konto. Innego adresu możesz użyć tylko wtedy, gdy jest skonfigurowany jako alias Send mail as (Wyślij jako) w ustawieniach Gmaila; w przeciwnym razie Gmail zamieni nadawcę na adres konta.

Regiony

Nie ma regionów – Gmail API jest globalne.

Limity wysyłki

Google stosuje dzienne limity na użytkownika. Ich przekroczenie blokuje wysyłkę nawet na 24 godziny.

Konto	Przybliżony limit
Gmail dla użytkowników indywidualnych (@gmail.com)	~500 odbiorców dziennie
Google Workspace	~2000 wiadomości dziennie (mniej w okresie próbnym)
Gmail API	250 jednostek limitu na użytkownika na sekundę; jedna wysyłka = 100 jednostek

Dlatego Frontmail wysyła przez Gmaila najwyżej 2 wiadomości na sekundę. Gdy Google odpowie dailyLimitExceeded, Frontmail czeka godzinę między kolejnymi próbami; jeśli limit się utrzymuje, wiadomość kończy jako failed, a kredyt wraca.

Śledzenie doręczeń (webhooki)

Gmail nie ma webhooków doręczeń, więc nie ma czego konfigurować, a na stronie usługi nie ma URL webhooka. Frontmail wie tylko, czy Google przyjął wiadomość (sent), czy ją odrzucił (failed). Odbicia przychodzą jako zwykłe e-maile „Delivery Status Notification” do twojej skrzynki Gmail i nie są automatycznie dodawane do listy wykluczeń Frontmail. Otwarcia i kliknięcia nie są śledzone.

Częste błędy

• auth – usługa nie działa (cofnięty/wygasły token, invalid_grant, 401/403, Gmail niewłączony dla użytkownika Workspace). Usługa zostaje oznaczona jako unhealthy; właściciel dostaje e-mail i baner w panelu. Przejmuje usługa zapasowa szablonu; w przeciwnym razie kredyt wraca, a wiadomość czeka w kolejce wstrzymanych wiadomości jako held_service_error i jest wysyłana automatycznie po ponownym połączeniu (sprawdzanym przy zapisie i w codziennym health checku).
• permanent – tej wiadomości nie da się wysłać (nieprawidłowy odbiorca, zbyt duża wiadomość, walidacja 400). Usługa zapasowa, jeśli jest skonfigurowana, w przeciwnym razie failed i zwrot kredytu.
• transient – 5xx, limity tempa/dzienne, timeouty. Ponawiane z wykładniczym opóźnieniem; po ostatniej próbie failed i zwrot kredytu.

Odpowiedź Google	Klasa	Co zrobić
invalid_grant – Token has been expired or revoked	auth	Kliknij Połącz ponownie na stronie usługi i znów przyznaj dostęp.
401 – Invalid Credentials	auth	Zwykle naprawia to automatyczne odświeżenie tokenu; jeśli błąd się utrzymuje, połącz ponownie.
403 – Insufficient Permission / insufficient_scope	auth	Na ekranie zgody odznaczono pole gmail.send – połącz ponownie i zezwól na wysyłanie.
403 – dostęp zablokowany przez administratora Workspace	auth	Poproś administratora, żeby oznaczył Frontmail jako zaufany w API controls.
400 failedPrecondition – Mail service not enabled	auth	Użytkownik Workspace nie ma licencji na Gmaila; włącz Gmaila albo podłącz inne konto.
400 invalidArgument – Invalid To header	permanent	Zobacz nieprawidłowy odbiorca.
413 / 400 – wiadomość jest zbyt duża	permanent	Zmniejsz rozmiar załączników (limit Gmaila to 25 MB).
429 / 403 rateLimitExceeded, userRateLimitExceeded, dailyLimitExceeded	transient	Zwolnij tempo albo poczekaj na odnowienie dziennego limitu; rozważ dostawcę transakcyjnego.
500 / 503 backendError	transient	Awaria Google – Frontmail ponawia próby.

Lista kontrolna

• Połączono przez Połącz z Gmail; udzielono zgody na wysyłanie e-maili
• Workspace: Frontmail dozwolony w API controls (jeśli dostęp jest ograniczony)
• Workspace we własnej domenie: SPF include:_spf.google.com, DKIM google._domainkey, DMARC
• Nadawca w szablonie = podłączony adres albo skonfigurowany alias Send mail as
• Testuj połączenie przechodzi
• Dzienny wolumen wyraźnie poniżej limitów Google
• Usługa zapasowa skonfigurowana w ważnych szablonach na wypadek unieważnienia tokenu