Návod
URL pro přihlášení
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.
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í.
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
-
Otevřete seznam kontaktů. Přejděte do Email MarketingAudiences a vyberte seznam.
-
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éfirst_namestringlast_namestringcustom_fieldsobjectEndpoint č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.
-
Přidejte formulář na stránku. Nechte ho odesílat na endpoint na vašem vlastním webu. Skryté pole
websiteje honeypot: lidé ho nevidí, ale boti ho často vyplní.<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> -
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. -
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
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);<?php
// Bots fill in the honeypot. Pretend it worked and stop.
if (!empty($_POST['website'])) {
header('Location: /thanks', true, 303);
exit;
}
$token = getenv('EMAILIT_SUBSCRIBE_TOKEN');
$ch = curl_init("https://api.emailit.com/subscribe/{$token}");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'email' => $_POST['email'] ?? '',
'first_name' => $_POST['first_name'] ?? null,
]),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 300) {
http_response_code($status);
echo json_decode($body, true)['error'] ?? 'Could not subscribe.';
exit;
}
header('Location: /thanks', true, 303);curl "https://api.emailit.com/subscribe/$EMAILIT_SUBSCRIBE_TOKEN" \
-X POST \
-H "Content-Type: application/json" \
-d '{ "email": "ada@example.com", "first_name": "Ada" }'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:
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.
-
Otevřete dialogové okno. Na stránce seznamu kontaktů vyberte Subscribe URL.
-
Obnovte token. Vyberte Reset token a potvrďte. Emailit vygeneruje novou URL.
-
Aktualizujte své integrace. Nahraďte token všude, kde ho používáte, například v proměnné
EMAILIT_SUBSCRIBE_TOKENna serveru.
Obnovit token můžete jen ve webovém rozhraní.