Gmail (OAuth)

Integrácia s Gmailom posiela šablóny Frontmailu z vašej vlastnej schránky Gmail alebo Google Workspace cez Gmail API. Odoslané správy nájdete v priečinku Odoslané, odpovede chodia späť do vašej schránky a príjemcovia vidia bežný e-mail od vás.

Gmail zvoľte, keď máte osobný web, portfólio alebo malú firmu a chcete, aby odoslané formuláre a notifikácie chodili z adresy, ktorú už používate – pri @gmail.com bez akéhokoľvek nastavovania DNS. Na veľké objemy to nie je: Google obmedzuje denný počet odoslaných správ (pozri Limity odosielania) a webhooky o doručení neexistujú. Na transakčné objemy použite Mailgun, Postmark, Amazon SES alebo Resend. Pozri prehľad služieb.

OAuth namiesto hesiel aplikácií

Gmail sa dá pripojiť aj cez SMTP s heslom aplikácie, OAuth je však bezpečnejší: Frontmail nikdy neuvidí vaše heslo, oprávnenie je obmedzené na odosielanie a kedykoľvek ho môžete vo svojom účte Google odvolať.

Čo budete potrebovať

• Účet Gmail (@gmail.com) alebo používateľa Google Workspace so zapnutým Gmailom.
• Pri Workspace: administrátor musí povoliť aplikáciám tretích strán prístup k dátam Google, prípadne Frontmail výslovne označiť ako dôveryhodný v Admin console → Security → Access and data control → API controls → App access control.
• Nič ďalšie – žiadny API kľúč ani projekt v Google Cloud.

Pripojenie vo Frontmaile

1. Otvorte E-mailové služby → Pridať službu → Gmail.
2. Kliknite na Pripojiť Gmail. Presmerujeme vás na Google.
3. Vyberte účet a prejdite si obrazovku so súhlasom (consent screen). Frontmail žiada o:
   • https://www.googleapis.com/auth/gmail.send – odosielanie e-mailov vaším menom. Ide o oprávnenie len na odosielanie: Frontmail vo vašej schránke nemôže nič čítať, vyhľadávať, mazať ani meniť.
   • openid email – vašu e-mailovú adresu, aby dashboard ukázal, ktorý účet je pripojený, a použil ju ako predvolenú adresu odosielateľa.
4. Kliknite na Allow. Google vás vráti späť a služba sa uloží s pripojenou adresou.
5. Voliteľne nastavte Max. e-mailov za sekundu (predvolene 2/s) a kliknite na Otestovať pripojenie – obnoví sa prístupový token a overí sa, že oprávnenie gmail.send bolo udelené.

Čo ukladáme: Frontmail ukladá OAuth refresh token (a krátkodobý access token) zašifrované obálkovým šifrovaním cez AWS KMS. Access token vyprší približne za hodinu; Frontmail ho pred odoslaním potichu obnoví. Prihlásenie používa PKCE a vždy žiada o offline prístup, takže opätovné pripojenie vydá nový refresh token.

Overenie aplikácie

Produkčná OAuth aplikácia Frontmailu je Googlom overená pre oprávnenie gmail.send, takže uvidíte názov Frontmail a žiadne varovanie o neoverenej aplikácii.

Keď token prestane fungovať

Google refresh token zneplatní, keď:

• odvoláte prístup v Google Account → Security → Third-party apps & services → Frontmail,
• zmeníte heslo k účtu Google (pri oprávneniach pre Gmail Google existujúce tokeny ruší),
• token 6 mesiacov nepoužijete,
• alebo prístup aplikácii odoberie administrátor Workspace.

Ďalšie odoslanie alebo kontrola stavu potom skončí chybou invalid_grant. Frontmail ju berie ako chybu auth: služba sa označí ako unhealthy, dostanete e-mail a upozornenie v dashboarde a správy sa pozdržia (alebo odídu cez záložnú službu), kým na stránke služby nekliknete na Pripojiť znova. Opätovné pripojenie vytvorí nový refresh token a pozdržané správy sa automaticky uvoľnia.

Vlastné OAuth aplikácie v stave „Testing“

Ak Frontmail prevádzkujete s vlastným OAuth klientom v Google Cloud a jeho stav zverejnenia je Testing, Google refresh tokeny ruší po 7 dňoch – služba bude každý týždeň unhealthy. Aby tokeny vydržali, aplikáciu zverejnite (a pre citlivé oprávnenie gmail.send prejdite overením). Hostovanej aplikácie frontmail.dev sa to netýka.

DNS: SPF, DKIM a DMARC

• Adresy @gmail.com: nie je čo nastavovať – Google poštu podpíše a overí sám.
• Google Workspace na vlastnej doméne: ak ste to ešte neurobili, zverejnite záznamy od Googlu:

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

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

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

Po zverejnení DKIM záznamu kliknite v Admin console na Start authentication. Keď budú DMARC reporty čisté, sprísnite politiku na p=quarantine / p=reject.

Poznámka

Požiadavky Googlu na hromadných odosielateľov z roku 2024 platia pre poštu posielanú používateľom Gmailu odkiaľkoľvek – vrátane Workspace. Kontaktný formulár hranicu 5 000 správ denne nedosiahne, SPF + DKIM + DMARC na doméne vo Workspace však napriek tomu odporúčame.

Adresa odosielateľa: Gmail odosiela ako pripojený účet. Inú adresu môžete použiť len vtedy, keď ju máte v nastaveniach Gmailu ako alias Send mail as; inak Gmail adresu odosielateľa prepíše na adresu účtu.

Regióny

Regióny tu nie sú – Gmail API je globálne.

Limity odosielania

Google stráži denné limity pre každého používateľa. Po ich prekročení je odosielanie zablokované až na 24 hodín.

Účet	Približný limit
Bežný Gmail (@gmail.com)	cca 500 príjemcov denne
Google Workspace	cca 2 000 správ denne (v skúšobnej verzii menej)
Gmail API	250 jednotiek kvóty na používateľa za sekundu; jedno odoslanie = 100 jednotiek

Frontmail preto cez Gmail posiela najviac 2 správy za sekundu. Keď Google odpovie dailyLimitExceeded, Frontmail čaká medzi pokusmi hodinu; ak limit trvá, správa skončí ako failed a kredit sa vráti.

Sledovanie doručenia (webhooky)

Gmail nemá webhooky o doručení, takže nie je čo nastavovať a na stránke služby žiadnu URL webhooku nenájdete. Frontmail vie len to, či Google správu prijal (sent), alebo odmietol (failed). Bounce chodia ako bežné e-maily „Delivery Status Notification“ do vašej schránky v Gmaile a do zoznamu blokovaných adries Frontmailu sa automaticky nepridávajú. Otvorenia ani kliknutia sa nesledujú.

Časté chyby

• auth – nefunguje služba (odvolaný alebo expirovaný token, invalid_grant, 401/403, Gmail pri používateľovi Workspace vypnutý). Služba sa označí ako unhealthy, vlastník dostane e-mail a upozornenie v dashboarde. Prevezme to záložná služba šablóny; inak vrátime kredit a správa počká vo fronte pozdržaných e-mailov ako held_service_error a po opätovnom pripojení sa odošle sama (overujeme pri uložení a pri dennej kontrole stavu).
• permanent – nedá sa odoslať práve táto správa (neplatný príjemca, príliš veľká správa, validácia 400). Záložná služba, ak je nastavená, inak failed a vrátenie kreditu.
• transient – 5xx, rate limity a denné limity, timeouty. Opakujeme s exponenciálne rastúcou pauzou; po poslednom pokuse failed a vrátenie kreditu.

Odpoveď Googlu	Trieda	Čo robiť
invalid_grant – Token has been expired or revoked	auth	Na stránke služby kliknite na Pripojiť znova a prístup znova povoľte.
401 – Invalid Credentials	auth	Zvyčajne to vyrieši automatická obnova tokenu; ak to pretrváva, pripojte účet znova.
403 – Insufficient Permission / insufficient_scope	auth	Na obrazovke so súhlasom ste odškrtli odosielanie – pripojte účet znova a odosielanie povoľte.
403 – prístup zablokoval administrátor Workspace	auth	Požiadajte administrátora, aby Frontmail povolil v API controls.
400 failedPrecondition – Mail service not enabled	auth	Používateľ Workspace nemá licenciu na Gmail; zapnite ho alebo pripojte iný účet.
400 invalidArgument – Invalid To header	permanent	Pozri neplatný príjemca.
413 / 400 – príliš veľká správa	permanent	Zmenšite prílohy (limit Gmailu je 25 MB).
429 / 403 rateLimitExceeded, userRateLimitExceeded, dailyLimitExceeded	transient	Spomaľte alebo počkajte na obnovenie denného limitu; zvážte transakčnú službu.
500 / 503 backendError	transient	Výpadok u Googlu – Frontmail to zopakuje.

Kontrolný zoznam

• Pripojené cez Pripojiť Gmail, súhlas s odosielaním udelený
• Workspace: Frontmail povolený v API controls (ak sú obmedzené)
• Workspace na vlastnej doméne: SPF include:_spf.google.com, DKIM google._domainkey, DMARC
• Adresa odosielateľa v šablóne = pripojená adresa alebo nastavený alias Send mail as
• Otestovať pripojenie prešlo
• Denný objem hlboko pod limitmi Googlu
• Pri dôležitých šablónach nastavená záložná služba pre prípad odvolania tokenu