Budete potřebovat
- API klíč z Správa › API klíče a SMTP ve tvaru
clientId:secret(oprávnění send, pro výpis seznamů i read), - formulář v Kampaně › Formuláře (pro variantu s potvrzením), nebo seznam v Kampaně › Kontakty,
- volání ze serveru. API klíč nepatří do JavaScriptu v prohlížeči.
Krok 1: Zjistěte ID formuláře nebo seznamu
ID všech seznamů a formulářů vrátí:
curl https://topemail.cz/api/email/lists \ -H "Authorization: Bearer CLIENT_ID:SECRET"
Odpověď
{
"lists": [{ "id": "clx…", "name": "Odběratelé novinek", "subscribed": 1240 }],
"forms": [{ "id": "cly…", "name": "Pokladna", "listId": "clx…", "active": true }]
}Krok 2: Přihlaste odběratele s potvrzením
Pošlete formId a adresu. Odběrateli odejde potvrzovací e-mail podle nastavení formuláře a do seznamu se zapíše až po kliknutí na tlačítko. Pole ip je nepovinné: když voláte ze serveru, pošlete IP adresu zákazníka, uloží se k souhlasu.
curl
curl https://topemail.cz/api/email/contacts \
-H "Authorization: Bearer CLIENT_ID:SECRET" \
-H "Content-Type: application/json" \
-d '{
"formId": "ID_FORMULARE",
"email": "jana.novakova@example.cz",
"name": "Jana",
"ip": "203.0.113.10"
}'PHP
<?php
// Zákazník zaškrtl odběr novinek: pošleme mu potvrzovací e-mail.
$ch = curl_init('https://topemail.cz/api/email/contacts');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 8,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('TOPEMAIL_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'formId' => 'ID_FORMULARE',
'email' => $email,
'name' => $jmeno,
'ip' => $_SERVER['REMOTE_ADDR'],
]),
]);
$odpoved = json_decode(curl_exec($ch), true);
// $odpoved['status'] === 'pending_confirmation'JavaScript (Node.js)
// Node.js 18+ (na serveru, API klíč nikdy nedávejte do prohlížeče)
const res = await fetch('https://topemail.cz/api/email/contacts', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.TOPEMAIL_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ formId: 'ID_FORMULARE', email, name }),
})
const data = await res.json() // { ok: true, status: 'pending_confirmation' }Krok 3: Nebo zapište kontakt přímo
Pokud souhlas dokládáte sami (třeba zaškrtnutím v objednávce s uloženým záznamem), zapište kontakt rovnou do seznamu. Pole consentSource je povinné: napište, kde a jak kontakt souhlasil.
curl
curl https://topemail.cz/api/email/contacts \
-H "Authorization: Bearer CLIENT_ID:SECRET" \
-H "Content-Type: application/json" \
-d '{
"listId": "ID_SEZNAMU",
"email": "jana.novakova@example.cz",
"name": "Jana",
"fields": { "mesto": "Brno" },
"consentSource": "zaškrtnutí v objednávce č. 2026-1042"
}'Přímý zápis nikdy znovu nepřihlásí adresu, která se u vás odhlásila nebo si stěžovala. Takový kontakt se může přihlásit jen sám.
Obě varianty odpoví 200 s polem status:
| status | Co znamená |
|---|---|
pending_confirmation | potvrzovací e-mail odešel (nebo už čeká), kontakt se zapíše po potvrzení |
subscribed | kontakt je zapsaný v seznamu (přímý zápis) |
already_subscribed | kontakt už v seznamu je, nic se nezměnilo |
kept_unsubscribed | adresa se dřív odhlásila, zůstává odhlášená |
Chyby mají tvar { "error": "…", "code": "…" } se stavovým kódem 400, 401, 403, 404 nebo 429. Klíč v testovacím režimu nic nezapíše a vrátí "test": true.
Krok 4: Odhlaste kontakt
Když zákazník zruší odběr u vás (třeba v nastavení účtu e-shopu), pošlete to do TopEmailu. Bez listId se adresa odhlásí ze všech seznamů.
curl
curl https://topemail.cz/api/email/contacts/unsubscribe \
-H "Authorization: Bearer CLIENT_ID:SECRET" \
-H "Content-Type: application/json" \
-d '{ "email": "jana.novakova@example.cz" }'Odpověď
{ "ok": true, "updated": 1 }- Celá specifikace je v OpenAPI (tag contacts), odesílání e-mailů na stránce API a SMTP.
- Používáte WooCommerce? Plugin tohle dělá sám, viz odběr v pokladně.
Nefunguje to?
401 unauthorized
Chybí hlavička Authorization: Bearer clientId:secret, nebo je klíč neplatný či zrušený. Pro přidání a odhlášení potřebuje klíč oprávnění send, pro výpis seznamů read.
403 sending_paused
Účet ještě není schválený nebo je pozastavený. Stav vidíte v dashboardu.
429 rate_limited
Na jednu adresu pošleme nejvýš 3 potvrzení za 24 hodin a jeden účet přijme nejvýš 500 přihlášek s potvrzením denně. Zkuste to později.
Odpověď kept_unsubscribed
Adresa se u vás dřív odhlásila nebo si stěžovala, proto ji přímým zápisem znovu nepřihlásíme. Přihlásit se může sama, přes formulář nebo variantou s formId.
Nevíte si rady? Napište na info@topemail.cz nebo pošlete ticket z dashboardu. Odpovídáme česky, obvykle do jednoho pracovního dne.