Napojení přes REST API nebo SMTP

Dva způsoby, jak z vaší aplikace nebo e-shopu odesílat e-maily z vlastní domény. REST API pro vlastní kód, SMTP relay pro všechno, co umí odesílat poštu. Stav doručení dostanete webhookem.

REST API: odeslání e-mailu

Základní adresa https://api.topemail.cz/v1. Autentizace hlavičkou Authorization: Bearer clientId:secret, kde dvojici vygenerujete v dashboardu (stejný princip jako u TopSMS). Pole from musí být na ověřené doméně vašeho účtu.

POST https://api.topemail.cz/v1/email/send
Authorization: Bearer <clientId>:<secret>
Content-Type: application/json

{
  "from": "Můj e-shop <objednavky@muj-eshop.cz>",
  "to": "zakaznik@example.com",
  "replyTo": "podpora@muj-eshop.cz",
  "subject": "Objednávka 2026-1042 byla odeslána",
  "html": "<p>Zásilku předáváme dopravci…</p>",
  "text": "Zásilku předáváme dopravci…",
  "tags": {"order": "2026-1042", "type": "shipping"}
}

HTTP/1.1 202 Accepted

{
  "ok": true,
  "id": "em_01jb7k3x9…",
  "status": "queued",
  "price": 0.06
}

• →to, cc, bcc: řetězec nebo pole adres; každý příjemce se účtuje jako jeden e-mail.
• →html a/nebo text: textovou verzi doplníme automaticky, pokud ji nepošlete.
• →attachments: pole { filename, content (base64), contentType }, celkem do 10 MB.
• →tags: vlastní klíče a hodnoty, vrací se v doručenkách i webhooku (např. číslo objednávky).
• →Idempotency-Key: volitelná hlavička; opakovaný požadavek se stejným klíčem e-mail nepošle znovu.
• →GET /v1/email/{id}: aktuální stav a historie událostí jednoho e-mailu.

SMTP relay

Pro WooCommerce, Shoptet, PrestaShop, fakturační systémy a cokoli, co umí odesílat poštu přes SMTP. Žádný kód, jen nastavení odchozího serveru. E-maily odeslané přes SMTP mají stejné doručenky, webhooky a historii jako e-maily z API.

Server:        smtp.topemail.cz
Port:          587 (STARTTLS)        alternativně 2525
Zabezpečení:   STARTTLS (TLS 1.2+)
Přihlášení:    uživatel = clientId, heslo = secret (API klíč)
Odesílatel:    adresa na ověřené doméně vašeho účtu

Značky k e-mailu lze přes SMTP předat hlavičkou X-TopEmail-Tags: order=2026-1042; type=shipping. Port 25 nepodporujeme.

Webhooky: událost email.status

Při každé změně stavu e-mailu pošleme HTTP POST na vaši adresu. Tělo je podepsané HMAC-SHA256 s tajným klíčem webhooku, podpis je v hlavičce X-TopEmail-Signature. Očekáváme odpověď 2xx do 10 s; při neúspěchu doručení opakujeme s rostoucím odstupem po dobu 24 hodin.

POST https://vas-web.cz/topemail-webhook
Content-Type: application/json
X-TopEmail-Event: email.status
X-TopEmail-Signature: sha256=3f1a…

{
  "event": "email.status",
  "id": "em_01jb7k3x9…",
  "status": "delivered",
  "to": "zakaznik@example.com",
  "tags": {"order": "2026-1042", "type": "shipping"},
  "at": "2026-11-12T09:41:07Z",
  "reason": null
}

// Node.js: ověření podpisu webhooku
const sig = req.headers['x-topemail-signature']            // "sha256=…"
const expected = 'sha256=' + crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(rawBody)                                         // nezparsované tělo
  .digest('hex')
if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
  return res.status(401).end()
}

U stavů bounced, deferred a suppressed je v poli reason srozumitelný důvod včetně odpovědi cílového serveru.

Cena za e-mail a co je v ní zahrnuto: ceník. Jak chráníme data: bezpečnost.