Anmelde-URL

Jede Kontaktliste hat eine Anmelde-URL: einen öffentlichen Endpunkt, der eine Person ohne API-Schlüssel zur Kontaktliste hinzufügt. Damit verbinden Sie ein Anmeldeformular auf Ihrer Website oder ein No-Code-Tool, das eine JSON-Anfrage senden kann, mit einer Kontaktliste.

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

Das token ist das Geheimnis der Kontaktliste. Wer die URL hat, kann Adressen zur Kontaktliste hinzufügen. Behandeln Sie sie daher wie ein Passwort.

URL finden

1. Kontaktliste öffnen. Öffnen Sie Email Marketing›Audiences und wählen Sie die Kontaktliste.

2. URL kopieren. Wählen Sie Subscribe URL und kopieren Sie die URL aus dem Dialog.

Per API liefert Kontaktliste abrufen denselben Wert in token.

Anfrageformat

Senden Sie eine POST-Anfrage mit JSON-Body und Content-Type: application/json. Der Header Authorization ist nicht nötig.

Der Endpunkt liest nur JSON. Formularkodierte Bodys, wie sie ein einfaches HTML-<form> sendet, werden mit 400 und „Invalid JSON in request body“ abgelehnt.

Antworten

Was eine Anmeldung bewirkt

• Neue Adresse: Emailit legt den Kontakt an und meldet ihn bei der Kontaktliste an.
• Bestehender Kontakt, nicht auf der Kontaktliste: Emailit aktualisiert die gesendeten Namen und eigenen Felder und meldet den Kontakt an.
• Bestehender Abonnent, der sich abgemeldet hatte: Emailit meldet ihn erneut an.
• Bestehender, angemeldeter Abonnent: Außer dem Anmeldedatum ändert sich nichts, und die Antwort ist trotzdem 200.

Anmeldungen über die Anmelde-URL senden keine subscriber.*- oder contact.*-Webhook-Events und starten keine Automatisierungen mit dem Trigger Added to audience. Sie ändern auch nicht den Marketing-Status eines Kontakts: War der Kontakt global abgemeldet, überspringen Kampagnen ihn weiterhin, bis Sie ihn auf der Seite Contacts erneut anmelden.

Anmeldeformular anbinden

Die Anmelde-URL hat keinen Bot-Schutz und akzeptiert nur JSON. Am sichersten ist es, Ihr Formular an Ihren eigenen Server zu senden, es dort zu prüfen und die Anmelde-URL vom Server aus aufzurufen. So bleibt das Token aus Ihrem Seitenquelltext heraus, und Sie können Spam blockieren, bevor er Ihre Kontaktliste erreicht.

1. Formular in Ihre Seite einbauen. Senden Sie es an einen Endpunkt auf Ihrer eigenen Website. Das versteckte Feld website ist ein Honeypot: Menschen sehen es nicht, Bots füllen es aber oft aus.

   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. Formular auf Ihrem Server verarbeiten. Verwerfen Sie Honeypot-Treffer, prüfen Sie ein CAPTCHA, falls Sie eines verwenden, und leiten Sie die Felder dann als JSON an die Anmelde-URL weiter. Bewahren Sie das Token in einer Umgebungsvariable wie EMAILIT_SUBSCRIBE_TOKEN auf. Siehe die Serverbeispiele unten.

3. Testen. Senden Sie das Formular mit Ihrer eigenen Adresse ab und prüfen Sie, ob Sie in der Abonnententabelle der Kontaktliste erscheinen.

Serverbeispiele

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 !== 200) {
    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" }'

Wenn Ihre Seite per JavaScript statt mit einem vollständigen Seitenaufruf sendet, rufen Sie mit fetch Ihren eigenen Endpunkt auf und belassen den Aufruf an Emailit auf dem Server:

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.';
});

Rate Limit und höhere Volumen

Die Anmelde-URL akzeptiert 30 Anfragen pro Minute von jeder IP-Adresse und gibt darüber 429 zurück. Wenn Ihr Server jede Anmeldung weiterleitet, kommen alle von der IP Ihres Servers; die 30 pro Minute gelten dann also für Ihre gesamte Website. Erwarten Sie mehr, rufen Sie stattdessen Abonnent hinzufügen mit einem API-Schlüssel von Ihrem Server aus auf. Dieser Endpunkt gibt außerdem 409 für bereits angemeldete Personen zurück und startet Automatisierungen mit dem Trigger Added to audience, etwa um eine Willkommens-E-Mail zu senden.

Anmeldungen bestätigen

Die Anmelde-URL fügt Personen sofort hinzu. Emailit sendet keine Bestätigungs-E-Mail und bittet die Person nicht, ihre Adresse zu bestätigen (Double-Opt-in).

Wenn Sie bestätigte Anmeldungen möchten, bauen Sie die Bestätigung in Ihren eigenen Ablauf ein: Wenn jemand das Formular absendet, speichern Sie die Anfrage auf Ihrem Server und senden der Person eine E-Mail mit einem Bestätigungslink, der zurück auf Ihre Website führt. Rufen Sie die Anmelde-URL erst auf, wenn die Person diesen Link geöffnet hat.

URL zurücksetzen

Setzen Sie das Token zurück, wenn die URL bekannt geworden ist oder Sie Spam-Anmeldungen erhalten. Die alte URL funktioniert sofort nicht mehr und gibt 404 zurück.

1. Dialog öffnen. Wählen Sie auf der Seite der Kontaktliste Subscribe URL.

2. Zurücksetzen. Wählen Sie Reset token und bestätigen Sie. Emailit erzeugt eine neue URL.

3. Integrationen aktualisieren. Ersetzen Sie das Token überall, wo Sie es verwenden, etwa in der Variable EMAILIT_SUBSCRIBE_TOKEN auf Ihrem Server.

Das Token lässt sich nur in der Weboberfläche zurücksetzen.

Siehe auch