n8n a Make: transakční e-mail přes HTTP Request node, spouštěče ze Shoptetu a Fakturoidu, idempotence

Spousta transakčních e-mailů nevzniká v e-shopu ani v aplikaci, ale „mezi systémy": zaplacená faktura ve Fakturoidu má spustit potvrzení s odkazem ke stažení, nová objednávka v Shoptetu má informovat externí sklad, formulář má poslat zákazníkovi PDF. Přesně na to jsou n8n a Make. TopEmail API je jeden HTTP požadavek s JSON, takže ho obě platformy odešlou standardním HTTP nodem bez vlastního konektoru. Článek ukazuje nastavení nodu, dva typické scénáře a jednu věc, na kterou se v automatizacích zapomíná: idempotenci.

Co posíláme

POST https://topemail.cz/api/email/send
Authorization: Bearer CLIENT_ID:SECRET
Content-Type: application/json
Idempotency-Key: invoice-8812-paid

{
  "from": "Firma s.r.o. <fakturace@firma.cz>",
  "to": ["zakaznik@example.com"],
  "subject": "Faktura 2026-8812 je zaplacena",
  "html": "<p>Děkujeme za úhradu…</p>",
  "text": "Děkujeme za úhradu…",
  "replyTo": "ucetni@firma.cz",
  "tags": {"invoice": "2026-8812", "type": "paid"}
}

Odpověď je {"ok": true, "emails": [{"id": "…", "to": "…", "status": "sent"}], "price": 0.06}. Adresa ve from musí být na doméně ověřené v TopEmail; postup je v návodu k SPF, DKIM a DMARC. Úplný popis polí je v OpenAPI specifikaci.

n8n: HTTP Request node

1. Přidejte node HTTP Request. Method POST, URL https://topemail.cz/api/email/send.
2. Authentication: Generic Credential Type → Header Auth. Vytvořte credential s Name Authorization a Value Bearer CLIENT_ID:SECRET. Klíč je tak uložený v šifrovaném úložišti n8n, ne v workflow, které můžete exportovat a sdílet.
3. Send Headers: zapnout, přidat Idempotency-Key s výrazem, například {{ 'invoice-' + $json.number + '-paid' }}.
4. Send Body: zapnout, Body Content Type JSON, Specify Body Using JSON a vložit:

{
  "from": "Firma s.r.o. <fakturace@firma.cz>",
  "to": ["{{ $json.client_email }}"],
  "subject": "Faktura {{ $json.number }} je zaplacena",
  "html": "<p>Dobrý den,</p><p>děkujeme za úhradu faktury {{ $json.number }}.</p>",
  "text": "Dobrý den, děkujeme za úhradu faktury {{ $json.number }}.",
  "replyTo": "ucetni@firma.cz",
  "tags": {"invoice": "{{ $json.number }}", "type": "paid"}
}

Pole to je vždy pole, i pro jednoho příjemce. Pokud hodnota z předchozího nodu může obsahovat uvozovky nebo nové řádky (třeba text z formuláře), použijte místo ručně psaného JSON volbu Using Fields Below, která hodnoty správně escapuje, nebo předřaďte node Set, který tělo sestaví jako objekt.

5. V Options zapněte Response → Include Response Headers and Status jen pro ladění; pro zpracování chyb nastavte On Error na Continue (using error output), abyste mohli větev s chybou poslat třeba do Slacku. V chybě najdete code (invalid_recipient, domain_not_verified, insufficient_credit…) a error.

Přílohu (PDF faktury) připojíte tak, že soubor stáhnete HTTP Request nodem s Response Format File, převedete nodem Extract from File (operace Move File to Base64 String) a do těla přidáte "attachments": [{"filename": "faktura.pdf", "content": "{{ $json.data }}", "contentType": "application/pdf"}].

Make: modul HTTP

1. Přidejte modul HTTP → Make a request.
2. URL https://topemail.cz/api/email/send, Method POST.
3. Headers: Authorization = Bearer CLIENT_ID:SECRET, Idempotency-Key = invoice-{{1.number}}-paid.
4. Body type Raw, Content type JSON (application/json), Request content JSON jako výše s mapovanými hodnotami z předchozího modulu. Pro bezpečné vložení textů použijte funkci {{replace(...)}} nebo lépe modul JSON → Create JSON se strukturou, který escapování vyřeší za vás.
5. Parse response zapnout; emails[].id pak můžete uložit do Google Sheets nebo do CRM.

Make má pro HTTP také variantu Make an API Key Auth request, kde klíč uložíte jako connection; Key name Authorization, API Key Bearer CLIENT_ID:SECRET, umístění v hlavičce.

Chyby řešte přes error handler na modulu HTTP: větev Resume pro 4xx (zalogovat, neopakovat) a Break pro 5xx a timeouty, který scénář za chvíli zopakuje se stejným Idempotency-Key.

Scénář 1: Fakturoid → e-mail při zaplacení

Fakturoid umí poslat webhook při událostech nad fakturou (například zaplacení). V n8n začněte nodem Webhook (POST), jeho URL vložte do nastavení webhooků ve Fakturoidu. Z payloadu použijte číslo faktury a e-mail klienta, případně dalším HTTP Request nodem (s účtem Fakturoidu) stáhněte PDF. Pak HTTP Request na TopEmail s Idempotency-Key invoice-<číslo>-paid. V Make je postup stejný s modulem Webhooks → Custom webhook, nebo s nativní aplikací Fakturoid, pokud ji v Make máte.

Scénář 2: Shoptet → vlastní e-mail

Shoptet posílá systémové e-maily sám, ale všechno navíc (žádost o recenzi, informace dopravci, B2B potvrzení) jde přes doplněk nebo webhook z Shoptet API; podrobnosti v článku o Shoptetu. Webhook nodem přijmete událost o objednávce, dohledáte detaily přes Shoptet API a pošlete e-mail s Idempotency-Key order-<kód>-<typ>. Pokud e-mail nemá odejít hned (recenze za 14 dní), vložte node Wait; v n8n i Make jsou dlouhé čekání podporované, ale idempotenční klíč platí 24 hodin, takže opakování po třech dnech už hlídat nebude. Pro delší odklady si držte vlastní záznam „odesláno" (tabulka v Google Sheets, databáze, Data Store v Make).

Idempotence: proč to v automatizaci řešit

Automatizace jsou náchylné na duplicity víc než aplikace: webhook ze zdroje přijde dvakrát, scénář ručně znovu spustíte při ladění, n8n zopakuje workflow po chybě v pozdějším nodu. Bez ochrany dostane zákazník dva stejné e-maily.

Dvě vrstvy obrany:

1. Idempotency-Key odvozený z události (invoice-8812-paid, ne {{ $now }} ani náhodné UUID). Server opakovaný požadavek do 24 hodin rozpozná a e-mail nepošle znovu, jen vrátí původní odpověď.
2. Vlastní stav pro vše, co přesahuje 24 hodin nebo co chcete vidět: před odesláním zkontrolujte v tabulce či Data Store, zda k dané události už e-mail neodešel, a po odeslání si uložte emails[0].id.

Při testování používejte oddělený testovací klíč, aby ladicí spuštění nešla reálným zákazníkům.

Stav doručení zpátky do automatizace

TopEmail při změně stavu volá váš webhook email.status s podpisem X-TopEmail-Signature: sha256=<HMAC-SHA256 těla>. V n8n ho přijmete nodem Webhook s Raw Body zapnutým, podpis spočítáte nodem Crypto (Action Hmac, Type SHA256, Encoding hex) nad syrovým tělem a porovnáte s hlavičkou nodem IF; pak podle status (delivered, bounced, complained) aktualizujete objednávku nebo pošlete upozornění. V Make použijte Custom webhook a funkci sha256(text; "hex"; key) v modulu Set variable. Protože se webhook při pomalé odpovědi opakuje, ukládejte události s klíčem (id, status, occurredAt) a duplicity ignorujte, jak popisuje návod k webhookům.

Nebo jednodušeji: značky tags z odeslání se ve webhooku vrátí, takže podle tags.invoice najdete řádek v tabulce bez ukládání id.

Časté chyby

• to jako řetězec místo pole: API vrátí validation.
• From z neověřené domény (domain_not_verified): často se v automatizaci omylem použije e-mail z Google účtu.
• Ručně skládaný JSON s neescapovaným textem z formuláře: požadavek je neplatný. Použijte Set/Create JSON.
• Idempotency-Key s časovým razítkem: každé spuštění je nový klíč, duplicity projdou.
• Klíč napsaný přímo v nodu a workflow exportované do Gitu: použijte credentials.

Shrnutí

HTTP Request node s hlavičkou Authorization: Bearer CLIENT_ID:SECRET, JSON tělem s to jako polem a Idempotency-Key odvozeným z události. Spouštěč je libovolný webhook (Fakturoid, Shoptet, formulář), stav doručení přijde zpět webhookem se značkami. Bez programování, za 0,06 Kč za e-mail, prvních 1 000 měsíčně zdarma. Co všechno API umí, je v dokumentaci; kdy je vhodnější SMTP, v srovnání SMTP a API.