Přejít na obsah
Dokumentace

Návod

Každý seznam kontaktů má URL pro přihlášení, která přidává lidi bez API klíče. Seznamte se s formátem požadavku, s tím, co na něm mění double opt-in, s bezpečným voláním, limity a obnovením URL.

Aktualizováno 20. 10. 2026

Každý seznam kontaktů má URL pro přihlášení: veřejný endpoint, který do seznamu přidá osobu bez API klíče. Použijte ji k propojení přihlašovacího formuláře na vašem webu nebo nástroje bez kódu, který umí odeslat požadavek JSON, se seznamem kontaktů. Je to endpoint pro požadavky POST, ne stránka: když URL otevřete v prohlížeči, nikoho nepřihlásí.

Text
POST https://api.emailit.com/subscribe/{token}

token je tajný údaj seznamu. Kdokoli, kdo URL zná, může do seznamu přidávat adresy, takže s ní zacházejte jako s heslem.

Najděte URL

  1. Otevřete seznam kontaktů. Přejděte do Email MarketingAudiences a vyberte seznam.

  2. Zkopírujte URL. Vyberte Subscribe URL a zkopírujte URL z dialogového okna. Dialogové okno ukazuje také ukázkový požadavek a to, jestli je zapnutý double opt-in.

Přes API vrací stejnou hodnotu v poli token endpoint Načtení seznamu kontaktů.

Formát požadavku

Pošlete požadavek POST s tělem JSON a hlavičkou Content-Type: application/json. Hlavička Authorization není potřeba.

emailstringpovinné
Adresa, kterou chcete přihlásit. Ukládá se malými písmeny.
first_namestring
Křestní jméno osoby. U existujícího kontaktu přepíše uložené křestní jméno, pokud není prázdné.
last_namestring
Příjmení osoby. U existujícího kontaktu přepíše uložené příjmení, pokud není prázdné.
custom_fieldsobject
Hodnoty podle klíčů vlastních polí. Sloučí se s hodnotami existujícího kontaktu: klíče, které pošlete, se přepíšou, ostatní zůstanou.

Endpoint čte jen JSON. Těla kódovaná jako formulář, která posílá obyčejný HTML <form>, se odmítnou s kódem 400 a zprávou „Invalid JSON in request body“.

Odpovědi

Stav Tělo Kdy
200 { "message": "Subscribed successfully", "status": "subscribed" } Double opt-in je vypnutý a osoba byla přidána, znovu přihlášena nebo už přihlášená byla.
202 { "message": "Check your inbox to confirm the subscription.", "status": "pending" } Double opt-in je zapnutý: e-mail pro double opt-in se odeslal a osoba se přidá, až v něm klikne na odkaz. Lidé, kteří už přihlášení jsou nebo se hned po prvním přihlášení přihlásili znovu, dostanou stejnou odpověď bez nového e-mailu.
400 { "error": "Missing required field: email" } nebo { "error": "Invalid email format" } E-mail chybí nebo má chybný formát, případně tělo není JSON.
403 { "error": "Workspace suspended" } nebo { "error": "Workspace scheduled for deletion" } Workspace je zablokovaný, nebo naplánovaný ke smazání, takže nepřijímá žádná přihlášení.
404 { "error": "Audience not found" } Token je chybný nebo byl obnoven, případně je seznam archivovaný.
422 { "error": "...", "usage": { ... } } Seznam dosáhl limitu odběratelů.
429 Více než 30 požadavků za minutu ze stejné IP adresy, nebo, když je zapnutý double opt-in nebo potvrzovací e-mail, příliš mnoho přihlášení k seznamu nebo z vaší sítě za poslední hodinu. Zkuste to znovu po uplynutí počtu sekund z hlavičky retry-after.
503 { "error": "The double opt-in email could not be sent. Please try again later.", "code": "..." } Double opt-in je zapnutý, ale e-mail pro double opt-in se nepodařilo odeslat, například protože odesílací doména není ověřená nebo workspace nemá kredity. Osoba se nepřidá.

Co přihlášení udělá

  • Nová adresa: Emailit vytvoří kontakt a přihlásí ho k seznamu.
  • Existující kontakt, který v seznamu není: Emailit upraví zaslaná jména a vlastní pole a kontakt přihlásí.
  • Existující odběratel, který se odhlásil: Emailit ho znovu přihlásí.
  • Existující odběratel, který je přihlášený: nic se nezmění a odpověď je i tak 200.

Při zapnutém double opt-inu se nový kontakt vytvoří hned, jména a vlastní pole existujícího kontaktu se nezmění a přihlášení počká, dokud osoba neklikne na odkaz v e-mailu pro double opt-in.

Nové přihlášení vyvolá události webhooků subscriber.created (u opětovného přihlášení subscriber.updated), spustí automatizace Added to audience a pošle potvrzovací e-mail seznamu, pokud je zapnutý. Přihlášení nevyvolávají události contact.* a nemění marketingový stav kontaktu: pokud byl kontakt globálně odhlášený, kampaně ho budou dál vynechávat, dokud ho znovu nepřihlásíte v seznamu Contacts.

Připojte přihlašovací formulář

URL pro přihlášení nemá žádnou ochranu proti botům a přijímá jen JSON. Nejbezpečnější je odesílat formulář na vlastní server, tam ho zkontrolovat a URL pro přihlášení volat ze serveru. Token se tak neobjeví ve zdrojovém kódu stránky a spam můžete zablokovat dřív, než se dostane do seznamu.

  1. Přidejte formulář na stránku. Nechte ho odesílat na endpoint na vašem vlastním webu. Skryté pole website je honeypot: lidé ho nevidí, ale boti ho často vyplní.

    signup.html
    <form id="signup" method="post" action="/newsletter">
      <label for="email">Email</label>
      <input id="email" name="email" type="email" required>
    
      <label for="first_name">First name</label>
      <input id="first_name" name="first_name" type="text">
    
      <!-- Honeypot: hidden from people, often filled in by bots -->
      <div style="position:absolute;left:-10000px" aria-hidden="true">
        <input name="website" type="text" tabindex="-1" autocomplete="off">
      </div>
    
      <button type="submit">Subscribe</button>
      <p class="status" role="status"></p>
    </form>
  2. Zpracujte formulář na serveru. Zahoďte odeslání s vyplněným honeypotem, ověřte CAPTCHA, pokud ji používáte, a pak pole předejte URL pro přihlášení jako JSON. Token mějte v proměnné prostředí, například EMAILIT_SUBSCRIBE_TOKEN. Viz ukázky pro server níže.

  3. Vyzkoušejte to. Odešlete formulář se svou vlastní adresou a zkontrolujte, že se objevíte v tabulce odběratelů seznamu.

Ukázky pro server

server.js
import express from 'express';

const app = express();

app.post('/newsletter', express.urlencoded({ extended: false }), async (req, res) => {
  // Bots fill in the honeypot. Pretend it worked and stop.
  if (req.body.website) return res.redirect(303, '/thanks');

  const response = await fetch(
    `https://api.emailit.com/subscribe/${process.env.EMAILIT_SUBSCRIBE_TOKEN}`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        email: req.body.email,
        first_name: req.body.first_name || undefined,
      }),
    },
  );

  if (!response.ok) {
    const { error } = await response.json().catch(() => ({}));
    return res.status(response.status).send(error || 'Could not subscribe.');
  }

  res.redirect(303, '/thanks');
});

app.listen(3000);

Pokud stránka odesílá formulář JavaScriptem místo načtení celé stránky, volejte svůj vlastní endpoint přes fetch a volání Emailitu nechte na serveru:

signup.js
document.querySelector('#signup').addEventListener('submit', async (event) => {
  event.preventDefault();
  const form = new FormData(event.target);
  const response = await fetch('/newsletter', { method: 'POST', body: new URLSearchParams(form) });
  event.target.querySelector('.status').textContent = response.ok
    ? 'Thanks, you are subscribed.'
    : 'Something went wrong. Please try again.';
});

Limit rychlosti a vyšší objemy

URL pro přihlášení přijme 30 požadavků za minutu z každé IP adresy a nad tento limit vrací 429. Když váš server přeposílá každé přihlášení, všechna přicházejí z IP adresy vašeho serveru, takže limit 30 za minutu platí pro celý váš web. Když je zapnutý double opt-in nebo potvrzovací e-mail, platí pro přihlášení také limity férového využití pro každý seznam a každou síť, protože každé přihlášení odešle e-mail. Pokud jich čekáte víc, volejte ze serveru s API klíčem endpoint Přidání odběratele. Ten navíc vrací 409 u lidí, kteří už přihlášení jsou, a s "double_opt_in": true požádá o potvrzení.

Potvrzujte přihlášení

Pokud chcete, aby každý, kdo se přihlásí přes URL pro přihlášení, nejdřív potvrdil svou adresu, zapněte na kartě Settings seznamu double opt-in. URL pak vrací 202, Emailit pošle z vaší ověřené domény e-mail pro double opt-in a osoba se přidá, až v něm klikne na odkaz. Když váš formulář dostane 202, může zobrazit „Zkontrolujte svou schránku“.

Pokud chcete lidi přivítat, jakmile jsou v seznamu, zapněte potvrzovací e-mail seznamu.

Obnovte URL

Pokud URL unikla, nebo vám chodí spamová přihlášení, obnovte token. Stará URL okamžitě přestane fungovat a vrací 404.

  1. Otevřete dialogové okno. Na stránce seznamu kontaktů vyberte Subscribe URL.

  2. Obnovte token. Vyberte Reset token a potvrďte. Emailit vygeneruje novou URL.

  3. Aktualizujte své integrace. Nahraďte token všude, kde ho používáte, například v proměnné EMAILIT_SUBSCRIBE_TOKEN na serveru.

Obnovit token můžete jen ve webovém rozhraní.

Přidávejte lidi přes API a řešte opětovná přihlášení.
Umožněte lidem ze seznamů odejít.

Byla tato stránka užitečná?

Děkujeme za zpětnou vazbu.

Děkujeme, čteme každou zprávu.