Postmark

Postmark se věnuje výhradně transakční poště a je známý rychlým a spolehlivým doručováním do doručené pošty. Transakční a hromadný provoz odděluje do message streamů, takže reputace důležitých e-mailů netrpí.

Postmark zvolte, když je pro vás nejdůležitější doručitelnost a rychlost transakčních e-mailů (obnova hesla, účtenky, potvrzení z formulářů) a nevadí vám, že Postmark nové účty před plným spuštěním schvaluje. Studené oslovování ani kupované databáze Postmark nepovoluje. Alternativy najdete v přehledu služeb.

Co budete potřebovat

• Účet v Postmarku a server (tak Postmark říká projektu), např. „Web“.
• Ověřeného odesílatele: buď Sender Signature pro jednu adresu, nebo lépe ověřenou doménu (Sender Signatures → Add Domain or Signature).
• Schválení účtu, než začnete posílat mimo vlastní doménu – viz Sandbox a limity.
• Server API token daného serveru (Servers → váš server → API Tokens). Serverový token umí jen odesílat a číst data vlastního serveru – to je varianta s nejmenšími oprávněními. Nepoužívejte Account API token.

Připojení ve Frontmailu

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

Pole	Kde ho najdete	Příklad
Server API token	Servers → váš server → API Tokens	a1b2c3d4-e5f6-7890-abcd-ef1234567890
Message stream	Servers → váš server → Message Streams; použijte stream typu Transactional	outbound
Uživatelské jméno webhooku	Volitelné – jméno pro Basic auth nastavené u webhooku v Postmarku	frontmail
Heslo webhooku	Volitelné – odpovídající heslo	dlouhe-nahodne-heslo
Max. e-mailů za sekundu	Volitelné; výchozí 10/s	10

3. Klikněte na Ověřit a uložit – Frontmail tokenem načte údaje o serveru.
4. Když kontrola projde, služba se uloží. Přístupové údaje šifrujeme obálkovým šifrováním přes AWS KMS.

Broadcast streamy

Nenasměrujte Frontmail na stream typu Broadcast. Ten je určený pro newslettery a vyžaduje odkaz na odhlášení; transakční e-maily z formulářů patří do výchozího streamu outbound.

DNS: SPF, DKIM a DMARC

Po přidání domény vám Postmark ukáže dva záznamy:

; DKIM – selektor obsahuje část odvozenou od data, opište ho z Postmarku
20240101123456pm._domainkey.example.cz.  TXT  "k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GN…"

; Vlastní Return-Path – díky ní je SPF zarovnané s vaší doménou
pm-bounces.example.cz.                   CNAME  pm.mtasv.net.

; DMARC – nejdřív monitoring
_dmarc.example.cz.                       TXT    "v=DMARC1; p=none; rua=mailto:dmarc@example.cz"

• DKIM záznam má tvar <časové razítko>pm._domainkey; hodnotu vždy kopírujte přesně z Postmarku.
• S CNAME záznamem Return-Path na pm.mtasv.net nemusíte Postmark přidávat do SPF hlavní domény – SPF se kontroluje na subdoméně Return-Path, kterou spravuje Postmark.
• V Postmarku u každého záznamu klikněte na Verify. Až budou DMARC reporty čisté, zpřísněte na p=quarantine / p=reject.

Poznámka

Požadavky Gmailu a Yahoo z roku 2024 (ověřená a zarovnaná pošta, nízká míra stížností) splníte s DKIM + Return-Path + DMARC podle příkladu výše.

Regiony

Postmark má jediný API endpoint (api.postmarkapp.com) a region se nevybírá. Data se zpracovávají v USA; pokud potřebujete data v EU, projděte si DPA Postmarku.

Sandbox a limity

• Čekání na schválení: nový účet smí posílat jen na adresy na stejné doméně jako ověřený odesílatel, dokud ho Postmark neschválí. Jinak odeslání skončí chybou 412. O schválení požádejte v dashboardu Postmarku; obvykle to vyřídí do jednoho pracovního dne.
• Testovací režim: speciální token POSTMARK_API_TEST zprávy přijme, ale neodešle – hodí se pro lokální testy, Otestovat spojení ve Frontmailu ho ale odmítne, protože za ním není žádný server.
• Bezplatný vývojářský tarif: 100 e-mailů měsíčně.
• Postmark si pro každý stream vede vlastní seznam neaktivních příjemců (hard bounce, stížnosti); odeslání na ně skončí kódem 406.

Webhooky (sledování doručení)

Webhooky se v Postmarku nastavují pro každý message stream zvlášť.

1. Na stránce služby ve Frontmailu zkopírujte webhook URL (tlačítko kopírovat):

   https://api.frontmail.dev/webhooks/providers/postmark/<token>

2. V Postmarku otevřete Servers → váš server → stream (např. Default Transactional Stream) → Webhooks → Add webhook, vložte URL a vyberte události:

Událost v Postmarku	Událost ve Frontmailu
Delivery	delivered
Bounce – tvrdý (HardBounce, BadEmailAddress, ManuallyDeactivated)	bounced – přidá se na suppression list
Bounce – měkký/dočasný (SoftBounce, Transient, DnsError)	zaznamená se u zprávy
Spam Complaint	complained – přidá se na suppression list
Open	opened (zapněte sledování otevření u streamu)
Link Click	clicked (zapněte sledování odkazů u streamu)

3. Webhook chraňte přes Basic auth (doporučeno): ve formuláři webhooku vyplňte Basic auth credentials (jméno + dlouhé náhodné heslo) a stejné hodnoty zadejte ve Frontmailu do polí Uživatelské jméno webhooku / Heslo webhooku.

Ověření podpisu: Postmark webhooky nepodepisuje. Službu identifikuje tajný token v URL, a pokud nastavíte heslo webhooku, Frontmail odmítne každý požadavek bez shodných Basic auth údajů. Vyzkoušet to můžete tlačítkem Send test v Postmarku.

Frontmail ke každé zprávě přidá hlavičku X-Frontmail-Message-Id, aby se události spárovaly se správnou zprávou.

Časté chyby

• auth – nefunguje služba (neplatný token, nepotvrzený odesílatel, neschválený účet, neznámý stream). 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; bez ní 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 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ý nebo neaktivní příjemce, validační chyba). Záložní služba, pokud je, jinak failed a vrácení kreditu.
• transient – 5xx, timeouty, 429. Opakujeme s exponenciálně rostoucí pauzou; po vyčerpání pokusů failed a vrácení kreditu.

Chyba Postmarku	Třída	Co dělat
10 – chybný nebo chybějící Server API token (HTTP 401)	auth	Znovu zkopírujte serverový token (ne Account token).
400 – pro adresu Od není definovaný Sender Signature	auth	Ověřte doménu/adresu Od v Sender Signatures, nebo změňte adresu Od v šabloně.
401 – Sender Signature není potvrzený	auth	Klikněte na potvrzovací odkaz, který Postmark poslal na adresu odesílatele.
412 – účet čeká na schválení, příjemci omezeni na vaši doménu	auth	Požádejte v Postmarku o schválení účtu.
1235 – message stream nenalezen	auth	Opravte ID v poli Message stream (např. outbound).
406 – neaktivní příjemce	permanent	Adresa dříve vrátila bounce nebo si stěžovala; Postmark ji blokuje. Znovu aktivujte jen v případě, že jste si jistí.
300 / 422 – neplatný požadavek / neplatná adresa	permanent	Viz neplatný příjemce.
HTTP 429 / 500 / 503	transient	Limit rychlosti nebo výpadek – Frontmail to zopakuje sám.

Kontrolní seznam

• Doména ověřená v Postmarku (DKIM TXT + Return-Path CNAME pm.mtasv.net)
• DMARC záznam nastavený, zpočátku p=none
• Účet schválený Postmarkem
• Zadaný serverový API token (ne Account token)
• Message stream = transakční stream (outbound)
• Otestovat spojení prošel
• Webhook na streamu s událostmi Delivery, Bounce, Spam Complaint (+ Open/Click)
• Basic auth u webhooku a stejné údaje ve Frontmailu