Gmail (OAuth)

Integrace s Gmailem posílá šablony Frontmailu z vaší vlastní schránky Gmail nebo Google Workspace přes Gmail API. Odeslané zprávy najdete ve složce Odeslané, odpovědi chodí zpět do vaší schránky a příjemci vidí běžný e-mail od vás.

Gmail zvolte, když máte osobní web, portfolio nebo malou firmu a chcete, aby odeslané formuláře a notifikace chodily z adresy, kterou už používáte – u @gmail.com bez jakéhokoli nastavování DNS. Na objemy to není: Google omezuje denní počet odeslaných zpráv (viz Limity odesílání) a webhooky o doručení neexistují. Na transakční objemy použijte Mailgun, Postmark, Amazon SES nebo Resend. Viz přehled služeb.

OAuth místo hesel aplikací

Gmail jde připojit i přes SMTP s heslem aplikace, OAuth je ale bezpečnější: Frontmail nikdy neuvidí vaše heslo, oprávnění je omezené na odesílání a kdykoli ho můžete ve svém účtu Google odvolat.

Co budete potřebovat

• Účet Gmail (@gmail.com) nebo uživatele Google Workspace se zapnutým Gmailem.
• U Workspace: administrátor musí povolit aplikacím třetích stran přístup k datům Google, případně Frontmail výslovně označit jako důvěryhodný v Admin console → Zabezpečení → Řízení přístupu a dat → Ovládací prvky API → Řízení přístupu aplikací.
• Nic dalšího – žádný API klíč ani projekt v Google Cloud.

Připojení ve Frontmailu

1. Otevřete E-mailové služby → Přidat službu → Gmail.
2. Klikněte na Připojit Gmail. Budete přesměrováni na Google.
3. Vyberte účet a projděte si obrazovku se souhlasem. Frontmail žádá o:
   • https://www.googleapis.com/auth/gmail.send – odesílání e-mailů vaším jménem. Jde o oprávnění jen k odesílání: Frontmail ve vaší schránce nemůže nic číst, hledat, mazat ani měnit.
   • openid email – vaši e-mailovou adresu, aby dashboard ukázal, který účet je připojený, a použil ji jako výchozí adresu Od.
4. Klikněte na Povolit. Google vás vrátí zpět a služba se uloží s připojenou adresou.
5. Volitelně nastavte Max. e-mailů za sekundu (výchozí 2/s) a klikněte na Otestovat spojení – ten obnoví přístupový token a ověří, že oprávnění gmail.send bylo uděleno.

Co ukládáme: Frontmail ukládá OAuth refresh token (a krátkodobý access token) zašifrované obálkovým šifrováním přes AWS KMS. Access token vyprší zhruba za hodinu; Frontmail ho před odesláním potichu obnoví. Přihlášení používá PKCE a vždy žádá o offline přístup, takže opětovné připojení vydá nový refresh token.

Ověření aplikace

Produkční OAuth aplikace Frontmailu je Googlem ověřená pro oprávnění gmail.send, takže uvidíte název Frontmail a žádné varování o neověřené aplikaci.

Když token přestane fungovat

Google refresh token zneplatní, když:

• odvoláte přístup v Účet Google → Zabezpečení → Aplikace a služby třetích stran → Frontmail,
• změníte heslo k účtu Google (u oprávnění pro Gmail Google stávající tokeny ruší),
• token 6 měsíců nepoužijete,
• nebo přístup aplikaci odebere administrátor Workspace.

Další odeslání nebo kontrola stavu pak skončí chybou invalid_grant. Frontmail ji bere jako chybu auth: služba se označí jako unhealthy, dostanete e-mail a upozornění v dashboardu a zprávy se zadrží (nebo odejdou přes záložní službu), dokud na stránce služby nekliknete na Reconnect. Opětovné připojení vytvoří nový refresh token a zadržené zprávy se automaticky uvolní.

Vlastní OAuth aplikace ve stavu „Testing“

Pokud Frontmail provozujete s vlastním OAuth klientem v Google Cloud a jeho stav publikování je Testing, Google refresh tokeny ruší po 7 dnech – služba bude každý týden unhealthy. Aby tokeny vydržely, aplikaci publikujte (a pro citlivé oprávnění gmail.send projděte ověřením). Hostované aplikace frontmail.dev se to netýká.

DNS: SPF, DKIM a DMARC

• Adresy @gmail.com: není co nastavovat – Google poštu podepíše a ověří sám.
• Google Workspace na vlastní doméně: pokud jste to ještě neudělali, přidejte záznamy od Googlu:

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

; DKIM – vygenerujte v Admin console → Aplikace → Google Workspace → Gmail → Ověření e-mailů
google._domainkey.example.cz.  TXT  "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A…"

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

Po zveřejnění DKIM záznamu klikněte v Admin console na Zahájit ověřování. Až budou DMARC reporty v pořádku, zpřísněte politiku na p=quarantine / p=reject.

Poznámka

Požadavky Googlu na hromadné odesílatele z roku 2024 platí pro poštu posílanou uživatelům Gmailu odkudkoli – včetně Workspace. Kontaktní formulář na hranici 5 000 zpráv denně nedosáhne, SPF + DKIM + DMARC na doméně ve Workspace ale přesto doporučujeme.

Adresa Od: Gmail odesílá jako připojený účet. Jinou adresu můžete použít jen tehdy, když ji máte v nastavení Gmailu jako alias Odesílat poštu jako; jinak Gmail adresu Od přepíše na adresu účtu.

Regiony

Regiony tu nejsou – Gmail API je globální.

Limity odesílání

Google hlídá denní limity pro každého uživatele. Po jejich překročení je odesílání zablokované až na 24 hodin.

Účet	Přibližný limit
Běžný Gmail (@gmail.com)	cca 500 příjemců denně
Google Workspace	cca 2 000 zpráv denně (ve zkušební verzi méně)
Gmail API	250 jednotek kvóty na uživatele za sekundu; jedno odeslání = 100 jednotek

Frontmail proto přes Gmail posílá nejvýš 2 zprávy za sekundu. Když Google odpoví dailyLimitExceeded, čeká Frontmail mezi pokusy hodinu; pokud limit trvá, skončí zpráva jako failed a kredit se vrátí.

Sledování doručení (webhooky)

Gmail nemá webhooky o doručení, takže není co nastavovat a na stránce služby žádnou webhook URL nenajdete. Frontmail ví jen to, jestli Google zprávu přijal (sent), nebo odmítl (failed). Bounce chodí jako běžné e-maily „Delivery Status Notification“ do vaší schránky v Gmailu a na suppression list Frontmailu se automaticky nepřidávají. Otevření ani kliknutí se nesledují.

Časté chyby

• auth – nefunguje služba (odvolaný nebo prošlý token, invalid_grant, 401/403, Gmail u uživatele Workspace vypnutý). Služba se označí jako unhealthy, vlastník dostane e-mail a upozornění v dashboardu. Převezme to záložní služba šablony; jinak vrátíme kredit a zpráva počká ve frontě zadržených zpráv jako held_service_error a po opětovném připojení se odešle sama (ověřujeme při uložení a při denní kontrole stavu).
• permanent – nejde odeslat právě tahle zpráva (neplatný příjemce, příliš velká zpráva, validace 400). Záložní služba, pokud je, jinak failed a vrácení kreditu.
• transient – 5xx, limity rychlosti a denní limity, timeouty. Opakujeme s exponenciálně rostoucí pauzou; po posledním pokusu failed a vrácení kreditu.

Odpověď Googlu	Třída	Co dělat
invalid_grant – Token has been expired or revoked	auth	Na stránce služby klikněte na Reconnect a přístup znovu povolte.
401 – Invalid Credentials	auth	Obvykle to vyřeší automatická obnova tokenu; pokud to trvá, připojte účet znovu.
403 – Insufficient Permission / insufficient_scope	auth	Na obrazovce souhlasu jste odškrtli odesílání – připojte znovu a odesílání povolte.
403 – přístup zablokoval administrátor Workspace	auth	Požádejte administrátora, aby Frontmail povolil v Ovládacích prvcích API.
400 failedPrecondition – Mail service not enabled	auth	Uživatel Workspace nemá licenci na Gmail; zapněte ho, nebo připojte jiný účet.
400 invalidArgument – Invalid To header	permanent	Viz neplatný příjemce.
413 / 400 – příliš velká zpráva	permanent	Zmenšete přílohy (limit Gmailu je 25 MB).
429 / 403 rateLimitExceeded, userRateLimitExceeded, dailyLimitExceeded	transient	Zpomalte, nebo počkejte na obnovení denního limitu; zvažte transakční službu.
500 / 503 backendError	transient	Výpadek u Googlu – Frontmail to zopakuje.

Kontrolní seznam

• Připojeno přes Připojit Gmail, souhlas s odesíláním udělen
• Workspace: Frontmail povolený v Ovládacích prvcích API (pokud jsou omezené)
• Workspace na vlastní doméně: SPF include:_spf.google.com, DKIM google._domainkey, DMARC
• Adresa Od v šabloně = připojená adresa nebo nastavený alias Odesílat poštu jako
• Otestovat spojení prošel
• Denní objem hluboko pod limity Googlu
• U důležitých šablon nastavená záložní služba pro případ odvolání tokenu