Postmark

Postmark sa venuje výhradne transakčnej pošte a je známy rýchlym a spoľahlivým doručovaním do doručenej pošty. Transakčnú a hromadnú prevádzku oddeľuje do message streamov, takže reputácia dôležitých e-mailov netrpí.

Postmark zvoľte, keď je pre vás najdôležitejšia doručiteľnosť a rýchlosť transakčných e-mailov (obnovenie hesla, potvrdenia platieb, potvrdenia z formulárov) a neprekáža vám, že Postmark nové účty pred plným spustením schvaľuje. Studené oslovovanie ani kupované databázy Postmark nepovoľuje. Alternatívy nájdete v prehľade služieb.

Čo budete potrebovať

Účet v Postmarku a server (tak Postmark nazýva projekt), napr. „Web“.
Overeného odosielateľa: buď Sender Signature pre jednu adresu, alebo lepšie overenú doménu (Sender Signatures → Add Domain or Signature).
Schválenie účtu, skôr než začnete posielať mimo vlastnej domény – pozri Sandbox a limity.
Server API token daného servera (Servers → váš server → API Tokens). Serverový token vie len odosielať a čítať dáta vlastného servera – to je variant s najmenšími oprávneniami. Nepoužívajte Account API token.

Pripojenie vo Frontmaile

Otvorte E-mailové služby → Pridať službu → Postmark.
Vyplňte polia:

Pole	Kde ho nájdete	Príklad
Server API token	Servers → váš server → API Tokens	`a1b2c3d4-e5f6-7890-abcd-ef1234567890`
Message stream	Servers → váš server → Message Streams; použite stream typu Transactional	`outbound`
Používateľské meno webhooku	Voliteľné – meno pre Basic auth nastavené pri webhooku v Postmarku	`frontmail`
Heslo webhooku	Voliteľné – zodpovedajúce heslo	`dlhe-nahodne-heslo`
Max. e-mailov za sekundu	Voliteľné; predvolene 10/s	`10`

Kliknite na Overiť a uložiť – Frontmail pomocou tokenu načíta údaje o serveri.
Keď kontrola prejde, služba sa uloží. Prístupové údaje šifrujeme obálkovým šifrovaním cez AWS KMS.

DNS: SPF, DKIM a DMARC

Po pridaní domény vám Postmark ukáže dva záznamy, ktoré treba zverejniť:

; DKIM – selektor obsahuje časť odvodenú od dátumu, skopírujte ho z Postmarku
20240101123456pm._domainkey.example.sk.  TXT  "k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GN…"

; Vlastná Return-Path – vďaka nej je SPF zarovnané s vašou doménou
pm-bounces.example.sk.                   CNAME  pm.mtasv.net.

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

DKIM záznam má tvar <časová pečiatka>pm._domainkey; hodnotu vždy kopírujte presne z Postmarku.
S CNAME záznamom Return-Path na pm.mtasv.net nemusíte Postmark pridávať do SPF hlavnej domény – SPF sa kontroluje na subdoméne Return-Path, ktorú spravuje Postmark.
V Postmarku pri každom zázname kliknite na Verify. Keď budú DMARC reporty čisté, sprísnite politiku na p=quarantine / p=reject.

Regióny

Postmark má jediný API endpoint (api.postmarkapp.com) a región sa nevyberá. Dáta sa spracúvajú v USA; ak potrebujete mať dáta v EÚ, prejdite si DPA Postmarku.

Sandbox a limity

Čakanie na schválenie: nový účet smie posielať len na adresy na rovnakej doméne ako overený odosielateľ, kým ho Postmark neschváli. Inak odoslanie skončí chybou 412. O schválenie požiadajte v dashboarde Postmarku; zvyčajne ho vybavia do jedného pracovného dňa.
Testovací režim: špeciálny token POSTMARK_API_TEST správy prijme, ale neodošle – hodí sa na lokálne testy, Otestovať pripojenie vo Frontmaile ho však odmietne, pretože za ním nie je žiadny server.
Bezplatný vývojársky tarif: 100 e-mailov mesačne.
Postmark si pre každý stream vedie vlastný zoznam neaktívnych príjemcov (hard bounce, sťažnosti); odoslanie na ne skončí kódom 406.

Webhooky (sledovanie doručenia)

Webhooky sa v Postmarku nastavujú pre každý message stream zvlášť.

Na stránke služby vo Frontmaile skopírujte URL webhooku (tlačidlo na kopírovanie):
```
https://api.frontmail.dev/webhooks/providers/postmark/<token>
```
V Postmarku otvorte Servers → váš server → stream (napr. Default Transactional Stream) → Webhooks → Add webhook, vložte URL a vyberte udalosti:

Udalosť v Postmarku	Udalosť vo Frontmaile
Delivery	`delivered`
Bounce – tvrdý (`HardBounce`, `BadEmailAddress`, `ManuallyDeactivated`)	`bounced` – pridá sa do zoznamu blokovaných adries
Bounce – mäkký/dočasný (`SoftBounce`, `Transient`, `DnsError`)	zaznamená sa pri správe
Spam Complaint	`complained` – pridá sa do zoznamu blokovaných adries
Open	`opened` (zapnite sledovanie otvorení pri streame)
Link Click	`clicked` (zapnite sledovanie odkazov pri streame)

Webhook chráňte cez Basic auth (odporúčané): vo formulári webhooku vyplňte Basic auth credentials (meno + dlhé náhodné heslo) a rovnaké hodnoty zadajte vo Frontmaile do polí Používateľské meno webhooku / Heslo webhooku.

Overenie podpisu: Postmark webhooky nepodpisuje. Službu identifikuje tajný token v URL, a ak nastavíte heslo webhooku, Frontmail odmietne každú požiadavku bez zhodných Basic auth údajov. Vyskúšať to môžete tlačidlom Send test v Postmarku.

Frontmail ku každej správe pridá hlavičku X-Frontmail-Message-Id, aby sa udalosti spárovali so správnou správou.

Časté chyby

auth – nefunguje služba (neplatný token, nepotvrdený odosielateľ, neschválený účet, neznámy stream). Služba sa označí ako unhealthy, vlastník dostane e-mail a upozornenie v dashboarde. Prevezme to záložná služba šablóny; bez nej vrátime kredit a správa počká vo fronte pozdržaných e-mailov ako held_service_error a po oprave služby sa odošle sama (overujeme pri uložení a pri dennej kontrole stavu).
permanent – nedá sa odoslať práve táto správa (neplatný alebo neaktívny príjemca, validačná chyba). Záložná služba, ak je nastavená, inak failed a vrátenie kreditu.
transient – 5xx, timeouty, 429. Opakujeme s exponenciálne rastúcou pauzou; po vyčerpaní pokusov failed a vrátenie kreditu.

Chyba Postmarku	Trieda	Čo robiť
`10` – chybný alebo chýbajúci Server API token (HTTP 401)	auth	Znova skopírujte serverový token (nie Account token).
`400` – pre adresu odosielateľa nie je definovaný Sender Signature	auth	Overte doménu/adresu odosielateľa v Sender Signatures alebo zmeňte odosielateľa v šablóne.
`401` – Sender Signature nie je potvrdený	auth	Kliknite na potvrdzovací odkaz, ktorý Postmark poslal na adresu odosielateľa.
`412` – účet čaká na schválenie, príjemcovia obmedzení na vašu doménu	auth	Požiadajte v Postmarku o schválenie účtu.
`1235` – message stream sa nenašiel	auth	Opravte ID v poli Message stream (napr. `outbound`).
`406` – neaktívny príjemca	permanent	Adresa predtým vrátila bounce alebo sa sťažovala; Postmark ju blokuje. Znova ju aktivujte, len ak ste si istí.
`300` / `422` – neplatná požiadavka / neplatná adresa	permanent	Pozri neplatný príjemca.
HTTP `429` / `500` / `503`	transient	Rate limit alebo výpadok – Frontmail to zopakuje automaticky.

Kontrolný zoznam

Doména overená v Postmarku (DKIM TXT + Return-Path CNAME pm.mtasv.net)
DMARC záznam zverejnený, na začiatok p=none
Účet schválený Postmarkom
Zadaný serverový API token (nie Account token)
Message stream = transakčný stream (outbound)
Otestovať pripojenie prešlo
Webhook na streame s udalosťami Delivery, Bounce, Spam Complaint (+ Open/Click)
Basic auth pri webhooku a rovnaké údaje vo Frontmaile