Transakční e-mail je zpráva, kterou příjemce čeká jako reakci na svou akci — potvrzení objednávky, reset hesla, potvrzení rezervace. Posílá se jednomu člověku, hned a bez odhlašovacího odkazu. Váš e-shop nebo rezervační systém pošle jeden požadavek a P-AileR zprávu odešle stejnou ověřenou cestou jako kampaně (podpis DKIM, ověřená doména).
Hromadné rozesílky přes API neposílejte — na newslettery a obchodní nabídky je v aplikaci Mailer, který k nim přidá povinný odhlašovací odkaz a měří výsledky.
V aplikaci v Můj účet → API klíče klikněte na „Vytvořit klíč". Klíč se zobrazí jen jednou — uložte si ho do svého systému (my ukládáme pouze jeho otisk, zpětně ho nezobrazíme). Klíčů můžete mít až 5, třeba zvlášť pro e-shop a zvlášť pro testovací prostředí. Klíč je heslo — patří na server, ne do veřejného kódu stránek.
Metoda POST na adresu https://pailer.cz/pailer-zero/api.php, tělo v JSON, klíč v hlavičce Authorization: Bearer …. Funguje jen přes HTTPS.
curl -X POST https://pailer.cz/pailer-zero/api.php \
-H "Authorization: Bearer pailer_VAS_KLIC" \
-H "Content-Type: application/json" \
-d '{
"od": "objednavky@vase-firma.cz",
"od_jmeno": "Vaše firma",
"komu": "zakaznik@example.com",
"predmet": "Potvrzení objednávky č. 12345",
"telo_html": "<p>Dobrý den, děkujeme za objednávku.</p>",
"idempotence_klic": "objednavka-12345"
}'
A totéž v čistém PHP, bez knihovny:
$data = [
'od' => 'objednavky@vase-firma.cz',
'komu' => 'zakaznik@example.com',
'predmet' => 'Potvrzení objednávky č. 12345',
'telo_html' => '<p>Dobrý den, děkujeme za objednávku.</p>',
'idempotence_klic' => 'objednavka-12345',
];
$ch = curl_init('https://pailer.cz/pailer-zero/api.php');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer pailer_VAS_KLIC',
'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_RETURNTRANSFER => true,
]);
$odpoved = curl_exec($ch);
$stav = curl_getinfo($ch, CURLINFO_HTTP_CODE); // 202 = přijato
od — vaše odesílací adresa (adresa na ověřené vlastní doméně, nebo adresa na společné doméně služby — nejlépe vyhrazená jen pro vás),komu — jedna adresa příjemce (jedno volání = jeden e-mail),predmet a telo_html nebo telo_text,od_jmeno, reply_to, prilohy a idempotence_klic.Přílohy: nejvýš 3 na zprávu a dohromady do 5 MB, obsah v base64: "prilohy": [{"nazev": "faktura.pdf", "obsah": "JVBERi0…"}]. Povolené typy: PDF, PNG, JPEG, GIF, iCalendar, prostý text a CSV — typ se pozná z obsahu souboru, ne z názvu.
Limity délek: předmět nejvýš 200 znaků, jméno odesílatele 100 a idempotenční klíč 64; celý požadavek včetně příloh v base64 nejvýš 8 MB. Obrázky v HTML vkládejte odkazem na váš web, ne vloženým souborem (data:) — takový požadavek odmítneme.
Personalizační značky API nedoplňuje — do těla vložte rovnou hotový text; data zná váš systém.
Když spojení spadne, váš systém obvykle požadavek zopakuje — a zákazník by dostal potvrzení dvakrát. Pošlete proto idempotence_klic: vlastní označení akce (třeba číslo objednávky). Se stejným klíčem už nic znovu neodešleme a vrátíme původní výsledek.
| Kód | Význam |
|---|---|
| 202 | Přijato — zpráva odešla, nebo odejde během chvíle. |
| 200 | Duplicitní požadavek (stejný idempotenční klíč) — nic se neodeslalo znovu. |
| 400 / 415 | Tělo není platný JSON, nebo chybí hlavička Content-Type. |
| 405 | Jiná metoda než POST. |
| 401 | Neplatný nebo zrušený klíč. |
| 403 | Volání bez HTTPS, pozastavený účet, pozastavené odesílání nebo vypršelé předplatné. |
| 413 | Požadavek je větší než 8 MB, nebo přílohy přesahují 5 MB. |
| 422 | Chyba v datech (adresa, předmět, typ přílohy), nebo zprávu trvale odmítl server příjemce. |
| 429 | Překročen limit — hlavička Retry-After říká, za kolik sekund to zkusit znovu. U minutového a hodinového stropu, zahřívání domény a špičky společné domény jde o chvíli; kód limit_vycerpan znamená vyčerpaný měsíční limit tarifu — obnoví se začátkem měsíce, nebo si limit navyšte. |
| 503 | Služba je dočasně nedostupná — požadavek zopakujte. |
Chyba přijde v těle jako {"ok":false,"chyba":{"kod":"…","zprava":"…"}} — česky a srozumitelně, text můžete rovnou zapsat do svého logu.
Odeslané zprávy se počítají do měsíčního limitu vašeho tarifu stejně jako rozesílky. Navíc platí strop 60 zpráv za minutu a 600 za hodinu — pojistka proti chybě ve vašem systému. Pokud se vaše odesílací doména právě zahřívá a denní limit je vyčerpaný, API vrátí 429 s kódem warmup_limit; limit se obnoví o půlnoci. Při odesílání ze společné (platformní) adresy může ve špičce přijít i 429 s kódem platforma_vytizena — stačí požadavek za chvíli zopakovat; vlastních ověřených domén se toto omezení netýká.
Odhlášení z newsletteru se transakčních e-mailů netýká — potvrzení objednávky pošleme i odhlášenému. Neodešleme ale na neexistující (nedoručitelné) adresy, na adresy, jejichž majitel si stěžoval na nevyžádanou poštu, a na adresy, které jste si sami v Kontaktech zablokovali — tam by zpráva stejně nedorazila.
V Můj účet → Oznámení do vašeho systému zadáte adresu (jen https://), na kterou pošleme automatickou zprávu, když se transakční e-mail nepodaří doručit (nedorucitelnost), když si na něj příjemce stěžoval (stiznost), a volitelně i o odeslání každé zprávy (odeslano). Váš e-shop tak hned ví, že má zákazníka oslovit jinak. Zpráva je podepsaná, takže si ověříte, že přišla od nás; při výpadku vašeho serveru ji během následujících hodin několikrát zopakujeme. Přesný tvar zpráv a ověření podpisu popisuje nápověda přímo v aplikaci.
Dotazy k API rádi zodpovíme na info@pailer.cz.