SendGrid

Twilio SendGrid patří k největším e-mailovým platformám. Zvládá transakční i marketingovou poštu, škáluje na velmi vysoké objemy a přes evropské subusery nabízí i uložení dat v EU.

SendGrid zvolte, když ho už používáte (nebo Twilio), čekáte velké objemy nebo potřebujete jeho podrobná data o událostech a správu IP adres. U menších projektů může být překážkou kontrola nových účtů a změny bezplatného tarifu – rychlejší start nabídne Resend, Postmark nebo Mailgun. Viz přehled služeb.

Co budete potřebovat

Účet v SendGridu, který prošel jeho kontrolou (po nových účtech někdy SendGrid chce před odesíláním doplňující údaje).
Ověřeného odesílatele: Domain Authentication pro vaši doménu (doporučeno), nebo aspoň Single Sender Verification pro adresu Od (Settings → Sender Authentication).
API klíč s omezeným přístupem: Settings → API Keys → Create API Key → Restricted Access, u Mail Send nastavte Full Access a vše ostatní nechte na No Access. Frontmail při Otestovat spojení ověří, že klíč má oprávnění mail.send.

Připojení ve Frontmailu

Otevřete E-mailové služby → Přidat službu → SendGrid.
Vyplňte pole:

Pole	Kde ho najdete	Příklad
API klíč	Settings → API Keys (zobrazí se jen jednou při vytvoření)	`SG.aBcD….xYz`
Region	Globální pro běžné účty; EU subuser, pokud klíč patří subuserovi v EU	`Globální (api.sendgrid.com)`
Ověřovací klíč event webhooku	Settings → Mail Settings → Event Webhook → Signed Event Webhook → Verification Key	`MFkwEwYHKoZIzj0CAQYI…`
Max. e-mailů za sekundu	Volitelné; výchozí 10/s	`10`

Klikněte na Ověřit a uložit – Frontmail načte oprávnění klíče, a pokud chybí Mail Send, řekne vám to srozumitelnou hláškou.
Když kontrola projde, služba se uloží. Přístupové údaje šifrujeme obálkovým šifrováním přes AWS KMS.

DNS: SPF, DKIM a DMARC

S automated security (výchozí volba v Domain Authentication) po vás SendGrid chce tři CNAME záznamy a SPF i DKIM spravuje sám:

em1234.example.cz.             CNAME  u1234567.wl123.sendgrid.net.
s1._domainkey.example.cz.      CNAME  s1.domainkey.u1234567.wl123.sendgrid.net.
s2._domainkey.example.cz.      CNAME  s2.domainkey.u1234567.wl123.sendgrid.net.

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

em1234 je subdoména pro return-path (číslo se liší podle účtu); nese SPF, takže do SPF hlavní domény nemusíte přidávat include:sendgrid.net.
s1 / s2 jsou dva DKIM selektory, mezi kterými SendGrid střídá klíče.
S vypnutým automated security naopak sami nastavíte MX + TXT (v=spf1 include:sendgrid.net ~all) na subdoméně a DKIM TXT záznam.
Volitelně přidejte CNAME pro Link Branding, aby sledované odkazy vedly přes vaši doménu místo sendgrid.net.
DMARC začněte na p=none a zpřísněte ho, až budou reporty čisté.

Regiony

Region	API server	Poznámka
Globální	`api.sendgrid.com`	výchozí pro všechny účty
EU	`api.eu.sendgrid.com`	jen pro EU subusery – data se ukládají a zpracovávají v EU

Uložení dat v EU zařídíte vytvořením subusera připnutého k evropskému regionu (dostupnost závisí na tarifu) a vytvořením API klíče pod tímto subuserem. Klíč evropského subusera nefunguje proti globálnímu serveru a naopak.

Sandbox a limity

Bezplatný tarif: dříve 100 e-mailů denně; SendGrid bezplatnou nabídku změnil na časově omezenou zkušební verzi, ověřte si tedy svůj aktuální tarif.
Single Sender Verification povoluje jen tu jednu ověřenou adresu Od; pro cokoli dalšího použijte Domain Authentication.
Vlastní suppression skupiny SendGridu (bounce, blokace, stížnosti, neplatné adresy) zprávy na blokované adresy potichu zahodí – volání API uspěje a Event Webhook nahlásí dropped.
SendGrid má i sandbox mode (mail_settings.sandbox_mode), který požadavek jen zvaliduje a neodešle; Frontmail ho nepoužívá.

Webhooky (sledování doručení)

Na stránce služby ve Frontmailu zkopírujte webhook URL (tlačítko kopírovat):
```
https://api.frontmail.dev/webhooks/providers/sendgrid/<token>
```
V SendGridu otevřete Settings → Mail Settings → Event Webhook (v novějším rozhraní Create new webhook), vložte URL jako Post URL a vyberte události:

Událost v SendGridu	Událost ve Frontmailu
Delivered	`delivered`
Bounced	`bounced` (tvrdý) – přidá se na suppression list
Dropped	`bounced` (neplatná/dříve vrácená adresa → tvrdý, jinak měkký)
Deferred	zaznamená se u zprávy
Spam Reports	`complained` – přidá se na suppression list
Opened	`opened`
Clicked	`clicked`

Zapněte Signed Event Webhook (Security features), zkopírujte Verification Key (veřejný klíč) a vložte ho do pole Ověřovací klíč event webhooku ve Frontmailu.
Tlačítkem Test Integration v SendGridu pošlete ukázkovou dávku.

Ověření podpisu: SendGrid každou dávku podepisuje algoritmem ECDSA. Frontmail ověří hlavičku X-Twilio-Email-Event-Webhook-Signature nad časovým razítkem a surovým tělem požadavku pomocí vašeho veřejného klíče a požadavky starší než 15 minut odmítne. Bez klíče události ověřit nejde a ignorujeme je.

Každá zpráva dostane hlavičku X-Frontmail-Message-Id, podle které se události párují.

Časté chyby

auth – nefunguje služba (neplatný či odvolaný klíč, chybějící oprávnění Mail Send, neověřený odesílatel, 401/403). Služba se označí jako unhealthy, vlastník dostane e-mail a upozornění v dashboardu. Použije se záložní služba šablony, pokud existuje; jinak vrátíme kredit a zpráva počká ve frontě zadržených zpráv jako held_service_error a po opravě služby odejde sama (ověřujeme při uložení a při denní kontrole stavu).
permanent – nejde odeslat právě tahle zpráva (neplatný příjemce, validace 400/413). Záložní služba, pokud je, jinak failed a vrácení kreditu.
transient – 5xx, 429, timeouty. Opakujeme s exponenciálně rostoucí pauzou; po posledním pokusu failed a vrácení kreditu.

Odpověď SendGridu	Třída	Co dělat
`401` – The provided authorization grant is invalid, expired, or revoked	auth	Vytvořte nový API klíč a aktualizujte službu.
`403` – přístup odepřen / klíč nemá `mail.send`	auth	Upravte klíč: Mail Send → Full Access.
`403` – The from address does not match a verified Sender Identity	auth	Ověřte doménu nebo adresu Od v Sender Authentication.
`401`/`403` z `api.eu.sendgrid.com` s globálním klíčem	auth	Přepněte Region podle toho, kde klíč vznikl.
`400` – Does not contain a valid address (`personalizations.0.to.0.email`)	permanent	Viz neplatný příjemce.
`413` – Payload too large	permanent	Zpráva přesahuje 30 MB; zmenšete přílohy.
`429` – Too many requests	transient	Omezení rychlosti – zopakujeme po `Retry-After`.
`500` / `503`, timeout	transient	Výpadek SendGridu – Frontmail to zopakuje.

Kontrolní seznam

Domain Authentication: CNAME em…, s1._domainkey, s2._domainkey ověřené
DMARC záznam nastavený (zpočátku p=none)
Omezený API klíč jen s Mail Send
Správný Region (EU jen pro EU subusery)
Otestovat spojení prošel
Event Webhook s Delivered, Bounced, Dropped, Spam Reports (+ Opened/Clicked)
Signed Event Webhook zapnutý, ověřovací klíč zkopírovaný do Frontmailu