Mailjet

Mailjet (súčasť skupiny Sinch) je európska e-mailová platforma pre transakčnú aj marketingovú poštu. Dáta predvolene uchováva v EÚ a má použiteľný bezplatný tarif, preto je obľúbený u menších európskych firiem.

Mailjet zvoľte, keď chcete poskytovateľa s dátami v EÚ a bezplatným tarifom alebo už cez Mailjet posielate newslettery a transakčnú poštu chcete mať v rovnakom účte. Pre čisto transakčnú poštu s dôrazom na doručiteľnosť sa pozrite na Postmark, pre hosting v EÚ s vývojárskym API na Mailgun EU. Porovnanie: prehľad služieb.

Čo budete potrebovať

• Účet v Mailjete (nové účty môžu pred aktiváciou prejsť krátkou kontrolou).
• Overeného odosielateľa: doménu pridajte v Account settings → Senders & Domains → Add domain a overte ju (SPF + DKIM), prípadne aspoň overte jednu adresu odosielateľa.
• Pár API kľúčov (API key + secret key). Kľúče v Mailjete nemajú obmedziteľné oprávnenia, takže variantom s najmenšími právami je samostatný kľúč sub-accountu: Account settings → REST API → API Key Management → Create a sub-account API key. Sub-account má vlastných odosielateľov, štatistiky aj kvótu a dá sa zrušiť bez zásahu do hlavného kľúča.

Pripojenie vo Frontmaile

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

Pole	Kde ho nájdete	Príklad
API kľúč	Account settings → REST API → API Key Management	a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
Tajný kľúč	Na rovnakej stránke (zobrazí sa po kliknutí; dá sa pregenerovať)	f6e5d4c3b2a1…
Používateľské meno webhooku	Voliteľné – meno, ktoré vložíte do URL webhooku (pozri nižšie)	frontmail
Heslo webhooku	Voliteľné – zodpovedajúce heslo	dlhy-nahodny-retazec
Max. e-mailov za sekundu	Voliteľné; predvolene 10/s	5

3. Kliknite na Overiť a uložiť – Frontmail zavolá Mailjet API s párom kľúčov.
4. Keď kontrola prejde, služba sa uloží. Oba kľúče šifrujeme obálkovým šifrovaním cez AWS KMS.

Upozornenie

Ak používate kľúč sub-accountu, odosielacia doména musí byť overená v tomto sub-accounte (alebo s ním zdieľaná). Inak každé odoslanie skončí chybou „sender not validated“.

DNS: SPF, DKIM a DMARC

Hodnoty nájdete v Senders & Domains → vaša doména → Authentication settings:

; SPF – zlúčte s existujúcim SPF záznamom (na doméne smie byť len jeden!)
example.sk.                    TXT  "v=spf1 include:spf.mailjet.com ~all"

; DKIM
mailjet._domainkey.example.sk. TXT  "k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNAD…"

; Overenie vlastníctva domény (len ak oň Mailjet požiada)
mailjet._a1b2c3d4.example.sk.  TXT  "a1b2c3d4e5f6…"

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

• Ak už máte v=spf1 include:_spf.google.com ~all, upravte ho na v=spf1 include:_spf.google.com include:spf.mailjet.com ~all – druhý SPF záznam nepridávajte.
• Obálkovým odosielateľom je bounce doména Mailjetu, takže zarovnanie pre DMARC stojí na DKIM – skontrolujte, že DKIM svieti ako OK.
• DMARC začnite s p=none a neskôr ho sprísnite.

Poznámka

Pre požiadavky Gmailu a Yahoo z roku 2024 je podstatné nastavenie SPF + DKIM + DMARC vyššie; marketingová pošta navyše potrebuje odhlásenie jedným kliknutím, ktoré Mailjet pridáva do kampaní, nie do transakčných správ z Frontmailu.

Regióny

Frontmail komunikuje s api.mailjet.com. Mailjet predvolene ukladá dáta v EÚ. Prevádzkuje aj samostatnú americkú infraštruktúru (api.us.mailjet.com) pre účty založené tam – Frontmail zatiaľ podporuje len predvolený endpoint, použite teda účet zo štandardnej (európskej) platformy.

Sandbox a limity

• Bezplatný tarif: 200 e-mailov denne, 6 000 mesačne.
• Platené tarify denný strop rušia a účtujú sa mesačne.
• Pri vysokej miere bounce alebo sťažností môže compliance tím Mailjetu účet pozastaviť na kontrolu; do jej konca je odosielanie zablokované.
• Príznak SandboxMode v API Mailjetu správy len zvaliduje a neodošle; Frontmail ho nepoužíva.

Webhooky (sledovanie doručenia)

Mailjet ich nazýva Event notifications (webhooky).

1. Na stránke služby vo Frontmaile skopírujte URL webhooku (tlačidlo na kopírovanie):

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

2. Odporúčame ho chrániť cez Basic auth. Mailjet na to nemá samostatné pole, prihlasovacie údaje preto vložte priamo do URL a rovnaké hodnoty zadajte vo Frontmaile do polí Používateľské meno webhooku / Heslo webhooku:

   https://frontmail:dlhy-nahodny-retazec@api.frontmail.dev/webhooks/providers/mailjet/<token>

3. V Mailjete otvorte Account settings → Event notifications (webhooks) a URL vložte k týmto udalostiam:

Udalosť v Mailjete	Udalosť vo Frontmaile
Sent (prijaté serverom príjemcu)	delivered
Bounce – hard_bounce: true	bounced – pridá sa do zoznamu blokovaných adries
Bounce – mäkký, Blocked	zaznamená sa ako mäkký bounce
Spam	complained – pridá sa do zoznamu blokovaných adries
Open	opened
Click	clicked

4. Po uložení pošle Mailjet testovacie volanie; udalosť by sa mala objaviť v logu udalostí služby.

Overenie podpisu: Mailjet udalosti nepodpisuje. Službu identifikuje tajný token v URL, a ak nastavíte heslo webhooku, Frontmail odmietne každú požiadavku bez zhodného Basic auth.

Frontmail nastavuje CustomID Mailjetu na ID správy vo Frontmaile, aby sa udalosti spárovali so správnou správou.

Časté chyby

• auth – nefunguje služba (nesprávny API kľúč či tajný kľúč, 401/403, neoverený odosielateľ alebo doména, zablokovaný účet). 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ý príjemca, validácia 400). Záložná služba, ak je nastavená, inak failed a vrátenie kreditu.
• transient – 5xx, 429, timeouty. Opakujeme s exponenciálne rastúcou pauzou; po poslednom pokuse failed a vrátenie kreditu.

Odpoveď Mailjetu	Trieda	Čo robiť
401 – API key authentication/authorization failure	auth	Skontrolujte dvojicu API kľúč a tajný kľúč; prípadne ich pregenerujte.
403 – Forbidden / účet zablokovaný alebo v kontrole	auth	Pozrite sa do dashboardu Mailjetu a kontaktujte jeho podporu.
400 – „The sender … is not validated / not authorized“	auth	Overte adresu odosielateľa alebo doménu v Senders & Domains (v správnom sub-accounte).
400 mj-0013 – „… is an invalid email address“	permanent	Pozri neplatný príjemca.
400 – iné validačné chyby (príliš dlhý predmet, veľká príloha)	permanent	Upravte šablónu; pozri HTML šablóny.
429 – Too many requests	transient	Rate limit alebo denný limit; Frontmail to zopakuje. Znížte Max. e-mailov za sekundu.
500 / 503, timeout	transient	Výpadok Mailjetu – Frontmail to zopakuje.

Kontrolný zoznam

• Doména pridaná a overená v Mailjete (SPF include + mailjet._domainkey)
• Jediný zlúčený SPF záznam; DMARC p=none
• Samostatný pár kľúčov sub-accountu
• Otestovať pripojenie prešlo
• URL pre event notifications s Basic auth údajmi, rovnaké hodnoty vo Frontmaile
• Zapnuté udalosti sent, bounce, blocked, spam (+ open, click)
• Denný objem v medziach tarifu