Zum Inhalt springen

Entwicklerleitfaden · Anmeldeformulare

Gestalten Sie Ihren eigenen Anmeldeablauf.

Behalten Sie HTML, Gestaltung und Website-Framework. Verbinden Sie Ihr Formular über den öffentlichen Anmeldeendpunkt mit einem veröffentlichten smartest.email-Formular.

Dieser Leitfaden behandelt

Öffentliche Formularkonfiguration und Anmeldungen von beliebigen Website-Ursprüngen

Einwilligung, Validierung, Antworten und Anfragelimits

Verwenden Sie die URL Ihres Formulars.

Erstellen Sie ein Formular unter Anmeldeformulare mit einem erforderlichen E-Mail-Feld und Einwilligungskästchen und veröffentlichen Sie es. Der Tab Installation zeigt die genaue URL.

Basis-URL

https://api.smartest.email/api/v1/public/forms/{FORM_ID}

Verwende die URL im Tab Einbinden deines Formulars. Ersetze FORM_ID in den folgenden Beispielen durch die ID deines veröffentlichten Formulars.

1

Erstellen

Legen Sie Felder und einen klaren Einwilligungstext fest.

2

Veröffentlichen

Neue Formulare beginnen als Entwürfe; öffentliche Routen geben bis zur Veröffentlichung 404 zurück.

3

Integrieren

Verwenden Sie den Einbettungscode oder die beiden öffentlichen Endpunkte unten.

Verwenden Sie Ihr eigenes HTML-Formular.

Direkte Übermittlung wird unterstützt. Erstellen und veröffentlichen Sie ein Formular in smartest.email, um Felder und Einwilligungstext festzulegen. Verwenden Sie dann seine ID in Ihrem Website-Formular. Der eingebettete Formulartyp erfordert keine Widget-Installation.

Ihre Website kann mit JavaScript fetch()übermitteln, oder Ihr Server kann die Anmeldung als JSON weiterleiten. Der öffentliche Endpunkt benötigt keinen API-Schlüssel, Zugriffstoken oder smartest.email-Einbettungsskript.

POST
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submit

Ersetzen Sie FORM_ID durch die UUID Ihres veröffentlichten Formulars. Senden Sie Content-Type: application/json mit dem folgenden Inhalt.

JSON-Anfrage · nach Einwilligung des Besuchers
{
  "data": {
    "email": "visitor@example.com"
  },
  "consent": true
}

Setzen Sie consent anhand der ausdrücklichen Wahl des Besuchers und zeigen Sie Einwilligungstext und Datenschutzhinweis. Belassen Sie consent auf oberster Ebene; platzieren Sie konfigurierte Kontaktfelder in data. Geben Sie alle Pflichtfelder Ihres veröffentlichten Formulars an.

Ein einfaches HTML-Formular benötigt einen Adapter

Der Endpunkt akzeptiert nur JSON. Ein normales <form method="post" action="…"> sendet URL-kodierte oder Multipart-Daten und erhält 415 JSON body required. Verwenden Sie das JavaScript-Browserbeispiel untenoder senden Sie an Ihren Server, der JSON an smartest.email weiterleitet.

Das Abrufen der öffentlichen Konfiguration hält Beschriftungen und Validierung mit dem veröffentlichten Formular synchron. Dies ist nicht für jede Übermittlung erforderlich. Ihre Integration steuert Erfolgsmeldung oder Weiterleitung; der Endpunkt antwortet immer mit JSON.

Zeigen Sie die veröffentlichten Felder an.

Dieser öffentliche Endpunkt benötigt keinen Zugriffstoken. Rufen Sie ihn beim Anzeigen eines Formulars ab und verwenden Sie Feldnamen, Einwilligungstext und Datenschutz-URL in Ihrer Oberfläche.

GET
https://api.smartest.email/api/v1/public/forms/{FORM_ID}

Gibt 200 mit sicheren Darstellungsdaten für ein aktives Formular zurück. Jeder erfolgreiche Abruf erhöht den Aufrufzähler; vermeiden Sie Polling.

GET
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/embed.js

Fertiges Inline- oder Popup-Widget-Skript. Verwenden Sie die genaue Skript-URL aus Installation, wenn Sie keine eigene Oberfläche brauchen.

GET
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/landing

Gehostete Anmeldeseite für ein aktives Formular.

GET /api/v1/public/forms/{FORM_ID} · Beispielantwort
{
  "id": "FORM_ID",
  "name": "Newsletter",
  "organizationName": "Example Studio",
  "type": "embedded",
  "fields": [
    { "name": "email", "type": "email", "label": "Email address", "required": true },
    { "name": "consent", "type": "checkbox", "label": "I agree to receive email updates.", "required": true }
  ],
  "styling": {},
  "successAction": {},
  "privacyUrl": "https://example.com/privacy"
}

Die Antwort kann weitere konfigurierte Felder, Auswahlmöglichkeiten und Validierungsregeln enthalten. successAction beschreibt das Verhalten des fertigen Widgets; direkte Übermittlung liefert weiterhin die allgemeine JSON-Antwort unten. Skript und gehostete Seite geben für Entwürfe, unveröffentlichte, ungültige oder unbekannte Formulare 404 zurück.

Einwilligung mit den Daten senden.

Senden Sie JSON nach ausdrücklicher Wahl von Marketing-E-Mails. Das Einwilligungsfeld gehört auf die oberste Ebene, nicht in data.

POST
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submit

Kein Zugriffstoken. Senden Sie Content-Type: application/json und {data:{email:...},consent:true}. Gibt dieselbe allgemeine Erfolgsmeldung für neue und bestehende Adressen zurück.

HTML + Browser-JavaScript · E-Mail und Einwilligung
<form id="signup-form">
  <fieldset id="signup-fields" disabled>
    <legend>Subscribe to email updates</legend>
    <label id="email-label" for="signup-email">Email address</label>
    <input id="signup-email" type="email" autocomplete="email" required>
    <label for="signup-consent">
      <input id="signup-consent" type="checkbox" required>
      <span id="consent-label"></span>
    </label>
    <a id="privacy-link" href="/privacy">Privacy notice</a>
    <button id="signup-submit" type="submit">Subscribe</button>
  </fieldset>
  <p id="signup-status" role="status" aria-live="polite"></p>
</form>
<script type="module">
  const endpoint = "https://api.smartest.email/api/v1/public/forms/FORM_ID";
  const form = document.querySelector("#signup-form");
  const fields = document.querySelector("#signup-fields");
  const button = document.querySelector("#signup-submit");
  const status = document.querySelector("#signup-status");
  let ready = false;
  let submitting = false;

  form.addEventListener("submit", async event => {
    event.preventDefault();
    if (!ready || submitting || !form.reportValidity()) return;
    submitting = true;
    button.disabled = true;
    try {
      const response = await fetch(endpoint + "/submit", {
        method: "POST",
        credentials: "omit",
        headers: { "Content-Type": "application/json", "Accept": "application/json" },
        body: JSON.stringify({
          data: { email: document.querySelector("#signup-email").value.trim() },
          consent: document.querySelector("#signup-consent").checked
        })
      });
      const result = await response.json();
      status.textContent = result.message || "Please try again.";
      if (response.ok) form.reset();
    } catch {
      status.textContent = "Please try again.";
    } finally {
      submitting = false;
      button.disabled = false;
    }
  });

  try {
    const response = await fetch(endpoint, { credentials: "omit" });
    if (!response.ok) throw new Error("Signup form unavailable");
    const config = await response.json();
    document.querySelector("#email-label").textContent =
      config.fields.find(field => field.name === "email").label;
    document.querySelector("#consent-label").textContent =
      config.fields.find(field => field.name === "consent").label;
    if (config.privacyUrl) {
      document.querySelector("#privacy-link").href = config.privacyUrl;
    }
    ready = true;
    fields.disabled = false;
  } catch (error) {
    status.textContent = error.message;
  }
</script>

Ersetzen Sie FORM_ID durch die Formular-UUID und setzen Sie den Ersatzlink /privacy auf Ihren eigenen Hinweis, wenn das Formular keine privacyUrlhat. Dieses Beispiel behandelt die zwei Pflichtfelder; zeigen und senden Sie alle weiteren Pflichtfelder Ihrer veröffentlichten Konfiguration.

Akzeptierte Antwort

JSON
{"success":true,"message":"Thank you for subscribing."}

Die Antwort verrät bewusst nicht, ob eine Adresse existiert. Bestehende abonnierte und abgemeldete Kontakte behalten ihren Status; nur eine neue akzeptierte Adresse fügt einen Abonnenten und einen Einwilligungsnachweis hinzu.

Senden Sie nur Namen aus dem veröffentlichten fields Array. Pflichtfelder müssen angegeben werden. Senden Sie weitere Kontrollkästchen als boolesche Werte, Zahlen als numerische Strings und Daten als YYYY-MM-DDund Auswahl- oder Radiowerte genau wie in options. Die API validiert die Daten erneut auf dem Server.

Die optionale Eigenschaft website auf oberster Ebene ist eine Spamfalle. Lassen Sie sie bei normalen Übermittlungen weg oder leer. Ein nichtleerer Wert liefert die allgemeine Erfolgsmeldung ohne Kontaktanlage; es ist kein Feld für die Website-URL des Besuchers.

Fehler und Anfragelimits behandeln.

Öffentliche Formularendpunkte erlauben ursprungsübergreifende GET-, POST- und OPTIONS-Anfragen mit Content-Type- und Accept-Headern. Verwenden Sie credentials: omit im Browser; Konto-Cookies, Authorization-Header und API-Schlüssel sind nicht nötig.

StatusBedeutung
200Konfiguration oder akzeptierte Übermittlung; eine doppelte Adresse erhält dieselbe Antwort.
400 / 415Ungültiges JSON / Anfrage ist nicht application/json.
404Unbekanntes, Entwurfs-, unveröffentlichtes oder ungültiges Formular.
409Das Konto hat sein Kontaktlimit erreicht.
413 / 422Inhalt größer als 16 KiB / Einwilligung oder Felddaten ungültig.
429Anfragelimit erreicht; Browsercode kann retry_after im JSON-Inhalt verwenden. Serverintegrationen können auch Retry-After.

Fehler verwenden {"error":true,"message":"..."}; Limitfehler enthalten auch retry_after in Sekunden. Für Formulare sind bis zu 30 Anfragen pro IP-Adresse und Minute zulässig, davon bis zu 10 Übermittlungen. Die Content Security Policy deiner Website muss den Zugriff erlauben auf https://api.smartest.email erlauben in connect-src; das fertige Widget benötigt dies auch in script-src.

Wenn dein eigener Server Übermittlungen weiterleitet, gilt das Anfragelimit gemeinsam für dessen ausgehende IP-Adresse.

Einwilligung und Zustellung

Eine neue akzeptierte Anmeldung erstellt einen abonnierten Kontakt und speichert Einwilligungstext, Zeit und angegebenen Ursprung. Ihre Oberfläche muss Einwilligungstext und Datenschutzhinweis vor der Übermittlung zeigen. Der Ursprung ist kein Identitätsnachweis. Der Endpunkt nutzt Single-Opt-in: Er sendet keine Bestätigung und prüft nicht die Inhaberschaft der Adresse.