E-mail API pro vývojáře

Jeden HTTP požadavek na POST https://topemail.cz/api/email/send s JSON tělem odešle e-mail z vaší domény; odpověď vrátí id a stav, změny stavu přijdou webhookem podepsaným HMAC. Autentizace je API klíčem, dokumentace a chybové hlášky jsou česky, specifikace je v OpenAPI. Prvních 1 000 e-mailů měsíčně je zdarma a testovat můžete bez ověřené domény.

Endpoint a tělo požadavku

Základní adresa je https://topemail.cz/api. Odeslání e-mailu je jeden POST na /email/send s hlavičkou Authorization: Bearer clientId:secret (API klíč z dashboardu). Tělo je JSON s poli from, to, subject a html nebo text; volitelně cc, bcc, replyTo, attachments (base64, celkem do 10 MB), tags a smsFallback. Odesílatel musí být na doméně ověřené ve vašem účtu, nebo na testovací doméně.

curl -X POST https://topemail.cz/api/email/send \
  -H "Authorization: Bearer <clientId>:<secret>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-2026-1042-confirm" \
  -d '{
    "from": "Můj e-shop <objednavky@muj-eshop.cz>",
    "to": "zakaznik@example.com",
    "replyTo": "podpora@muj-eshop.cz",
    "subject": "Potvrzení objednávky 2026-1042",
    "html": "<p>Děkujeme, objednávku jsme přijali…</p>",
    "tags": {"order": "2026-1042", "type": "confirm"}
  }'

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

API odpovídá 202 Accepted s identifikátorem e-mailu a cenou, kterou si za něj strhne z kreditu (0 u bezplatných e-mailů). Stav queued znamená, že e-mail prošel validací a je ve frontě; vlastní doručení sledujete webhookem nebo přes GET /v1/email/{id}.

Node.js

// Node.js 18+: nativni fetch, bez knihoven
const res = await fetch('https://topemail.cz/api/email/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.TOPEMAIL_KEY,   // "clientId:secret"
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-2026-1042-confirm',
  },
  body: JSON.stringify({
    from: 'Můj e-shop <objednavky@muj-eshop.cz>',
    to: 'zakaznik@example.com',
    subject: 'Potvrzení objednávky 2026-1042',
    html: '<p>Děkujeme, objednávku jsme přijali…</p>',
    tags: { order: '2026-1042', type: 'confirm' },
  }),
})
const data = await res.json()
if (!res.ok) throw new Error(data.code + ': ' + data.error)
console.log(data.id, data.status)   // em_01jb7k3x9… queued

PHP

<?php
// PHP 8: cURL bez knihoven (nebo composer require topemail/topemail-php)
$ch = curl_init('https://topemail.cz/api/email/send');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('TOPEMAIL_KEY'),   // "clientId:secret"
        'Content-Type: application/json',
        'Idempotency-Key: order-2026-1042-confirm',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'from'    => 'Můj e-shop <objednavky@muj-eshop.cz>',
        'to'      => 'zakaznik@example.com',
        'subject' => 'Potvrzení objednávky 2026-1042',
        'html'    => '<p>Děkujeme, objednávku jsme přijali…</p>',
        'tags'    => ['order' => '2026-1042', 'type' => 'confirm'],
    ], JSON_UNESCAPED_UNICODE),
]);
$data = json_decode(curl_exec($ch), true);
echo $data['id'];   // em_01jb7k3x9…

Oficiální knihovny: npm i topemail (Node.js 18+, TypeScript) a composer require topemail/topemail-php (PHP 8.0+); obě umí odeslání, stav, šablony, blokované adresy, automatické opakování při 429 a 5xx a ověření podpisu webhooku. Zdrojové kódy jsou na GitHubu pod licencí MIT. Podrobné návody máme pro Node.js, PHP, Python a Django, Laravel a n8n a Make.

Webhooky: stav doručení bez dotazování

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

POST https://vas-web.cz/topemail-webhook
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": "confirm"},
  "at": "2026-11-12T09:41:07Z",
  "reason": {"title": "Doručeno", "explanation": "Server příjemce e-mail přijal.", "advice": "Nemusíte nic dělat."} }

• →Podpis ověřujte z nezparsovaného těla a porovnávejte v konstantním čase (crypto.timingSafeEqual, hash_equals); SDK to dělají za vás. Vysvětlení pojmu: HMAC podpis.
• →Události mohou přijít opakovaně nebo mimo pořadí. Zpracování udělejte idempotentní: ukládejte dvojici id + status a duplicitu ignorujte.
• →Pole tags se vrací přesně tak, jak jste je poslali, takže objednávku nebo fakturu najdete bez ukládání id.
• →Pole reason obsahuje srozumitelný český popis stavu (title, explanation, advice), který můžete rovnou zobrazit operátorovi.

Idempotence: proč zákazník nedostane potvrzení dvakrát

Síť selže, timeout vyprší, worker se restartuje a váš kód požadavek zopakuje. Bez ochrany by zákazník dostal dvě potvrzení objednávky. Pošlete proto hlavičku Idempotency-Key s klíčem odvozeným z vaší entity, například order-2026-1042-confirm. Opakovaný požadavek se stejným klíčem e-mail znovu neodešle a vrátí původní odpověď, včetně původního id. U SMTP relay plní stejnou roli vlastní hlavička Message-ID; rozdíl popisuje heslo REST API vs. SMTP a idempotence.

Šablony na serveru

HTML nemusíte skládat v aplikaci. V dashboardu vytvoříte šablonu s proměnnými ({{orderNumber}}, {{trackingUrl}}…) a v požadavku pošlete jen "template": "expedice-zasilky" a "variables": {…}; předmět, HTML i textovou verzi doplní server. Šablony lze spravovat i přes API (/api/email/templates), takže je můžete verzovat spolu s kódem. Pro potvrzení objednávky, expedici, fakturu, reset hesla a ověřovací kód nabízíme připravené výchozí šablony, které si upravíte.

Limity, chyby a cena

• →Chyby vrací JSON s polem code: validation (400), unauthorized (401), forbidden (403, například daily_limit na testovací doméně), invalid_recipient (422), rate_limited (429). Při 429 a 5xx požadavek zopakujte s odstupem; SDK to dělají automaticky.
• →Přílohy celkem do 10 MB, každý příjemce v to, cc a bcc je jeden účtovaný e-mail.
• →Historie e-mailů a událostí 90 dní v dashboardu i přes GET /v1/email/{id}.
• →Nové účty zvyšují objem postupně; při vysoké míře vrácenek odesílání pozastavíme a ozveme se.

Cena nezávisí na způsobu odeslání: prvních 1 000 e-mailů v kalendářním měsíci zdarma, dál 0,06 Kč za e-mail do 5 000 e-mailů v měsíci, 0,02 Kč do 50 000 a 0,01 Kč nad 50 000, bez DPH. Bez paušálu, z předplaceného kreditu, který nepropadá; faktura v Kč. Podrobnosti v ceníku, kompletní referenci na stránce API a SMTP. Než začnete posílat zákazníkům, zkontrolujte DNS záznamy své domény bezplatným nástrojem.

Časté dotazy