Postmark

Postmark skupia się wyłącznie na poczcie transakcyjnej i słynie z szybkiego, niezawodnego doręczania do skrzynki odbiorczej. Rozdziela ruch transakcyjny i masowy na strumienie wiadomości (message streams), co chroni reputację twoich ważnych e-maili.

Wybierz Postmark, gdy najważniejsze są dostarczalność i szybkość poczty transakcyjnej (resety haseł, potwierdzenia płatności, potwierdzenia z formularzy) i nie przeszkadza ci, że Postmark sprawdza nowe konta, zanim pozwoli im swobodnie wysyłać. Postmark nie pozwala na marketing do zimnych ani kupionych list. Alternatywy znajdziesz w przeglądzie usług.

Wymagania

• Konto Postmark i serwer (tak Postmark nazywa projekt), np. „Website”.
• Zweryfikowany nadawca: Sender Signature dla pojedynczego adresu albo – lepiej – zweryfikowana domena (Sender Signatures → Add Domain or Signature).
• Zatwierdzenie konta przed wysyłką do odbiorców spoza twojej domeny – zobacz Sandbox i limity.
• Server API token tego serwera (Servers → your server → API Tokens). Token serwera może tylko wysyłać i odczytywać dane własnego serwera – to opcja z minimalnymi uprawnieniami. Nie używaj tokenu Account API.

Podłączenie we Frontmail

1. Otwórz Usługi e-mail → Dodaj usługę → Postmark.
2. Wypełnij pola:

Pole	Gdzie je znaleźć	Przykład
Token Server API	Servers → your server → API Tokens	a1b2c3d4-e5f6-7890-abcd-ef1234567890
Message stream	Servers → your server → Message Streams; użyj strumienia Transactional	outbound
Nazwa użytkownika webhooka	Opcjonalnie – nazwa użytkownika Basic auth ustawiona w webhooku Postmark	frontmail
Hasło webhooka	Opcjonalnie – odpowiadające jej hasło	s3cr3t-long-random
Maks. liczba e-maili na sekundę	Opcjonalnie; domyślnie 10/s	10

3. Kliknij Zweryfikuj i zapisz – Frontmail odczyta tokenem dane serwera.
4. Usługa zostanie zapisana, gdy sprawdzenie się powiedzie. Dane dostępowe są szyfrowane kopertowo przez AWS KMS.

Strumienie broadcast

Nie kieruj Frontmail na strumień Broadcast. Strumienie broadcast są przeznaczone do newsletterów i wymagają linku do wypisania; e-maile transakcyjne z formularzy należą do domyślnego strumienia outbound.

DNS: SPF, DKIM i DMARC

Po dodaniu domeny Postmark pokazuje dwa rekordy do opublikowania:

; DKIM – the selector contains a date-based part, copy it from Postmark
20240101123456pm._domainkey.example.com.  TXT  "k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GN…"

; Custom Return-Path – makes SPF align with your domain
pm-bounces.example.com.                   CNAME  pm.mtasv.net.

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

• Host DKIM wygląda jak <timestamp>pm._domainkey; zawsze kopiuj dokładną wartość z Postmark.
• Z rekordem CNAME Return-Path wskazującym na pm.mtasv.net nie musisz dodawać Postmark do SPF domeny głównej – SPF jest sprawdzany w subdomenie Return-Path, którą zarządza Postmark.
• Kliknij Verify przy każdym rekordzie w Postmark. Gdy raporty będą czyste, zaostrz DMARC do p=quarantine / p=reject.

Notatka

Wymagania Gmaila i Yahoo z 2024 roku dla nadawców (uwierzytelniona i wyrównana poczta, niski wskaźnik spamu) spełnia DKIM + Return-Path + DMARC jak wyżej.

Regiony

Postmark ma jeden endpoint API (api.postmarkapp.com) i nie ma regionu do wyboru. Dane są przetwarzane w USA; jeśli zależy ci na przechowywaniu danych w UE, sprawdź umowę powierzenia (DPA) Postmark.

Sandbox i limity

• Oczekiwanie na zatwierdzenie: nowe konto może wysyłać tylko na adresy w tej samej domenie co zweryfikowany nadawca, dopóki Postmark go nie zatwierdzi. Próby wysyłki gdzie indziej kończą się kodem błędu 412. O zatwierdzenie poproś w panelu Postmark; zwykle trwa to do jednego dnia roboczego.
• Tryb testowy: specjalny token POSTMARK_API_TEST przyjmuje wiadomości bez ich wysyłania – przydatne do testów lokalnych, ale Testuj połączenie we Frontmail go odrzuci, bo nie stoi za nim żaden serwer.
• Darmowy plan dla programistów: 100 e-maili miesięcznie.
• Postmark prowadzi własną listę nieaktywnych odbiorców (twarde odbicia, skargi) dla każdego strumienia; wysyłka do nich kończy się kodem 406.

Webhooki (śledzenie doręczeń)

Webhooki Postmark konfiguruje się dla każdego strumienia wiadomości.

1. Skopiuj URL webhooka ze strony usługi we Frontmail (przycisk kopiowania):

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

2. W Postmark otwórz Servers → your server → strumień (np. Default Transactional Stream) → Webhooks → Add webhook, wklej URL i wybierz zdarzenia:

Zdarzenie Postmark	Zdarzenie Frontmail
Delivery	delivered
Bounce – twarde (HardBounce, BadEmailAddress, ManuallyDeactivated)	bounced – dodany do listy wykluczeń
Bounce – miękkie/przejściowe (SoftBounce, Transient, DnsError)	zapisywane przy wiadomości
Spam Complaint	complained – dodany do listy wykluczeń
Open	opened (włącz śledzenie otwarć w strumieniu)
Link Click	clicked (włącz śledzenie linków w strumieniu)

3. Zabezpiecz webhook przez Basic auth (zalecane): w formularzu webhooka wypełnij Basic auth credentials (nazwa użytkownika + długie losowe hasło) i wpisz te same wartości w polach usługi we Frontmail Nazwa użytkownika webhooka / Hasło webhooka.

Weryfikacja podpisu: Postmark nie podpisuje danych webhooków. Tajny token w URL identyfikuje usługę, a gdy ustawisz hasło webhooka, Frontmail odrzuca każde żądanie bez pasujących danych Basic auth. Sprawdzisz to przyciskiem Send test w Postmark.

Frontmail dodaje do każdej wiadomości nagłówek X-Frontmail-Message-Id, żeby zdarzenia trafiały do właściwej wiadomości.

Częste błędy

• auth – usługa nie działa (nieprawidłowy token, niepotwierdzony nadawca, niezatwierdzone konto, nieznany strumień). Usługa zostaje oznaczona jako unhealthy; właściciel dostaje e-mail i baner w panelu. Przejmuje usługa zapasowa szablonu; bez niej kredyt wraca, a wiadomość czeka w kolejce wstrzymanych wiadomości jako held_service_error i jest wysyłana automatycznie po naprawieniu usługi (sprawdzanej ponownie przy zapisie i w codziennym health checku).
• permanent – tej wiadomości nie da się wysłać (nieprawidłowy lub nieaktywny odbiorca, błąd walidacji). Usługa zapasowa, jeśli jest skonfigurowana, w przeciwnym razie failed i zwrot kredytu.
• transient – 5xx, timeouty, 429. Ponawiane z wykładniczym opóźnieniem; po wyczerpaniu prób failed i zwrot kredytu.

Błąd Postmark	Klasa	Co zrobić
10 – Bad or missing Server API token (HTTP 401)	auth	Skopiuj ponownie token Server (nie token Account).
400 – Sender signature not defined for From address	auth	Zweryfikuj domenę/adres nadawcy w Sender Signatures albo zmień nadawcę w szablonie.
401 – Sender signature not confirmed	auth	Kliknij link potwierdzający, który Postmark wysłał na adres nadawcy.
412 – Account pending approval, recipients restricted to your domain	auth	Poproś w Postmark o zatwierdzenie konta.
1235 – Message stream not found	auth	Popraw ID w polu Message stream (np. outbound).
406 – Inactive recipient	permanent	Adres wcześniej wygenerował odbicie lub skargę; Postmark go blokuje. Aktywuj go ponownie w Postmark tylko wtedy, gdy masz pewność.
300 / 422 – Invalid email request / invalid address	permanent	Zobacz nieprawidłowy odbiorca.
HTTP 429 / 500 / 503	transient	Limit żądań lub awaria – Frontmail automatycznie ponawia próby.

Lista kontrolna

• Domena zweryfikowana w Postmark (DKIM TXT + CNAME Return-Path pm.mtasv.net)
• Opublikowany rekord DMARC, na początek p=none
• Konto zatwierdzone przez Postmark
• Wpisany token API Server (nie token Account)
• Message stream = strumień transakcyjny (outbound)
• Testuj połączenie przechodzi
• Webhook w strumieniu z Delivery, Bounce, Spam Complaint (+ Open/Click)
• Basic auth w webhooku, te same dane we Frontmail