SMTP vs. REST API pro transakční e-maily: co zvolit

Každá e-mailová brána nabízí dvě cesty: SMTP relay, kam se aplikace přihlásí jako k běžnému poštovnímu serveru, a REST API, kam pošle JSON. Výsledek je stejný, e-mail z vaší domény s doručenkou. Liší se tím, kolik práce dá napojení, co všechno při odeslání můžete ovlivnit a jak se chová, když něco selže. Tenhle článek je rozhodovací pomůcka pro vývojáře a majitele e-shopů.

SMTP relay v kostce

SMTP je protokol z roku 1982, kterým si servery předávají poštu. Relay znamená, že vaše aplikace předá e-mail našemu serveru a ten ho doručí dál. Nastavení je pět položek:

Server:      smtp.topemail.cz
Port:        587 (STARTTLS), záloha 2525
Uživatel:    clientId
Heslo:       secret (API klíč)
Odesílatel:  adresa na ověřené doméně

Umí to každá platforma, framework i fakturační program, který kdy posílal e-mail. Nic neprogramujete, jen přepíšete konfiguraci. Co dostanete:

• stejné doručenky, webhooky a historii jako u API,
• DKIM podpis a soulad s SPF a DMARC vaší domény,
• značky pro párování přes hlavičku X-TopEmail-Tags: order=2026-1042; type=shipping.

Co nedostanete:

• ID e-mailu v odpovědi. SMTP server odpoví „250 OK, zařazeno", ale identifikátor pro dotaz na stav musíte dohledat přes značky nebo Message-ID.
• Strukturovanou chybu. Když je adresa na blokovaném seznamu nebo from není na ověřené doméně, SMTP vrátí kód a větu textu; knihovna ji obvykle převede na obecnou výjimku.
• Idempotenci. Pošlete-li stejný e-mail dvakrát, odejde dvakrát.

REST API v kostce

Jeden HTTP požadavek s JSON:

POST https://api.topemail.cz/v1/email/send
Authorization: Bearer <clientId>:<secret>
Content-Type: application/json
Idempotency-Key: order-2026-1042-confirm

{
  "from": "Můj e-shop <objednavky@muj-eshop.cz>",
  "to": "zakaznik@example.com",
  "subject": "Potvrzení objednávky 2026-1042",
  "html": "<p>…</p>",
  "text": "…",
  "tags": {"order": "2026-1042", "type": "confirm"}
}

Odpověď 202 Accepted s id, stavem a cenou. Co dostanete navíc proti SMTP:

• ID hned v odpovědi, pro GET /v1/email/{id} i pro párování webhooků bez hledání.
• Idempotency-Key. Opakovaný požadavek se stejným klíčem (po timeoutu, po restartu workeru) e-mail nepošle znovu. U potvrzení objednávek je to nejdůležitější vlastnost celého API.
• Chyby jako JSON s kódem a vysvětlením: neověřená doména, adresa na blokovaném seznamu, chybějící předmět, překročený limit. Aplikace na ně může reagovat, ne jen logovat.
• Přílohy a značky jako pole, ne jako hlavičky, které někde cestou zmizí.

Cena je stejná, 0,06 Kč za e-mail, ať použijete cokoli.

Rozhodovací tabulka

Na co si dát pozor u SMTP

• Spojení na každý e-mail. Knihovny často otevírají a zavírají SMTP spojení pro každou zprávu, což je pomalé. Při větším objemu spojení držte nebo odesílejte z fronty.
• Timeout a opakování. Pokud knihovna po timeoutu zkusí odeslat znovu, může e-mail odejít dvakrát; server mohl první pokus přijmout a odpověď se jen ztratila. Idempotenci musíte řešit sami (například si uložit, že pro objednávku a stav už odesláno bylo).
• Odesílatel z neověřené domény. Plugin v e-shopu rád přepíše From na adresu administrátora (admin@gmail.com). Výsledek je odmítnutí. Vynuťte adresu odesílatele v nastavení pluginu.
• Port 25. Nepodporujeme ho a hostingy ho blokují. 587 se STARTTLS je standard.

Na co si dát pozor u API

• Nezparsujte odpověď jen na ok: true. Uložte si id; bez něj později nedohledáte stav.
• Idempotency-Key musí být stabilní pro danou událost (order-1042-confirm), ne náhodný pro každý pokus. Náhodný klíč idempotenci ruší.
• Vlastní textová verze. API ji doplní z HTML, pokud chybí, ale vámi napsaná je lepší.
• Klíč v konfiguraci, ne v repozitáři. Klíč jde v dashboardu zneplatnit a vygenerovat nový, ale commit v historii zůstane.

Obojí najednou

Časté a rozumné řešení: e-shop posílá potvrzení a notifikace přes SMTP (nic se neprogramuje), vlastní aplikace nebo worker posílá ověřovací kódy a faktury přes API. Oba kanály jsou na jednom účtu, s jednou doménou, jedním blokovaným seznamem a jedním webhookem. Značky z SMTP hlavičky i z API pole vypadají ve webhooku stejně, takže zpracování stavů je jedno.

Shrnutí

SMTP: nula kódu, funguje všude, ale bez ID v odpovědi, bez idempotence a s chybami v prostém textu. API: pár řádků kódu, ale ID hned, Idempotency-Key, strukturované chyby. Pro hotové platformy SMTP, pro vlastní kód API, pro obojí jeden účet. Podrobnosti k polím, hlavičkám a stavům najdete v přehledu API a SMTP; jak stavy zpracovat, v článku o webhookách.