Wie Formulare funktionieren

Ein Formular hat zwei Kopien dessen, was Besucher sehen. document ist der Entwurf, den Sie bearbeiten, und publishedDocument ist das, was die gehostete Seite, die Einbettung und der Anmelde-Endpunkt verwenden. Speichern ändert nur den Entwurf, und POST /forms/{id}/publish kopiert ihn in die Live-Kopie. hasUnpublishedChanges zeigt Ihnen, dass sich die beiden unterscheiden.

• —draft: nie veröffentlicht. Niemand kann es sehen oder sich darüber anmelden.
• —live: veröffentlicht und nimmt Anmeldungen an.
• —paused: veröffentlicht, aber geschlossen. Die Seite zeigt die Pausenmeldung aus den Texten des Formulars, und Anmeldungen werden abgelehnt.

settings sind etwas anderes: wohin Anmeldungen gehen, Double-Opt-in, der Absender, was nach der Anmeldung geschieht und wer über jede Anmeldung informiert wird. Sie gelten, sobald sie gespeichert sind, ob veröffentlicht oder nicht.

Ein Dokument besteht aus einer Liste von fields, den umgebenden Texten in copy und einem style. Jedes Eingabefeld hat einen key, den Namen, unter dem seine Antwort gesendet wird: ein Kleinbuchstabe, gefolgt von bis zu 39 Kleinbuchstaben, Ziffern oder Unterstrichen, eindeutig im Formular und nie mit oe_ beginnend. Jedes Formular hat genau ein email-Feld; sein Schlüssel ist email, und es ist erforderlich.

• —Eingabefelder: email, text, textarea, number, phone, url und date.
• —Auswahlfelder: select, radio und checkboxes, jeweils mit options.
• —checkbox für ein Ja oder Nein und consent für ein Kästchen, das angekreuzt werden muss, wenn es erforderlich ist.
• —Mit audiences wählt die Person Listen: Jeder value einer Option ist eine Audience-ID in diesem Workspace.
• —hidden trägt einen Wert, den der Besucher nie sieht: den, den Ihre Seite sendet, oder andernfalls seinen defaultValue, etwa einen Kampagnennamen.
• —heading, paragraph und divider dienen nur dem Layout des Formulars und senden nichts.

Setzen Sie mapsTo bei einem Textfeld auf firstName, lastName oder name, und die Antwort wird zum Namen des Kontakts, den die Anmeldung anlegt. Ein bereits bestehender Kontakt behält seinen Namen. Jede Antwort bleibt mit der Bezeichnung, die sie damals hatte, an der Einsendung gespeichert, sodass alte Einsendungen auch nach einer Änderung des Formulars richtig lesbar bleiben.

Veröffentlichen Sie zuerst. Nutzen Sie dann diejenige der drei Varianten, die zur Seite passt. Alle erreichen dasselbe Formular und zählen dieselben Anmeldungen. Aufrufe werden nur auf der gehosteten Seite und in der Einbettung gezählt, Anmeldungen über Ihr eigenes HTML oder Ihren eigenen Code erhöhen also die Konversionsrate.

• —Die gehostete Seite unter url, eine eigene Seite, auf die Sie von überall verlinken können.
• —Das Einbettungsskript, das das Formular in einem Rahmen, der seine Größe selbst anpasst, auf Ihre Seite bringt.
• —Ihr eigenes HTML oder Ihr eigener Code, der die Antworten an subscribeUrl sendet.

<script src="https://openemail.uk/embed/form.js" data-openemail-form="frm_3b9d2e7a1c4f80d56e2a9b14" async></script>

<form action="https://api.openemail.uk/subscribe/frm_3b9d2e7a1c4f80d56e2a9b14" method="post">  <input type="email" name="email" required>  <div style="position:absolute;left:-9999px" aria-hidden="true">    <input type="text" name="oe_website" tabindex="-1" autocomplete="off">  </div>  <button type="submit">Subscribe</button></form>

Ein reines HTML-Formular wird auf die Dankeseite weitergeleitet oder auf settings.redirectUrl. Code, der JSON sendet, bekommt stattdessen eine JSON-Antwort, die auf der Seite zum Anmelde-Endpunkt beschrieben ist.

Ist settings.doubleOptIn eingeschaltet, wird eine Anmeldung als pending gespeichert, und die Person erhält per E-Mail einen Link von settings.senderAddress, einer Adresse dieses Workspace. Sie tritt den Audiences bei, wenn sie ihn öffnet. Der Link funktioniert sieben Tage lang. Eine Person, die sich früher von einer Audience abgemeldet hat, wird nur auf diesem Weg wieder angemeldet, nie über ein Formular mit Single-Opt-in. Wer sich vor der Bestätigung erneut anmeldet, aktualisiert die ausstehende Anmeldung, statt eine weitere anzulegen.

Zum Schutz der Personen, denen Sie schreiben, erhält eine Adresse höchstens eine Bestätigung pro Formular alle zehn Minuten und fünf pro Tag im ganzen Workspace. Sie können eine ausstehende Anmeldung selbst freigeben oder ihr einen neuen Link senden.

• —Lesen erfordert forms:read und Ändern erfordert forms:write. Das Freigeben einer Anmeldung erfordert außerdem contacts:write, weil es einen Kontakt hinzufügt.
• —Alles, wodurch ein Formular E-Mails sendet, erfordert außerdem emails:send: Double-Opt-in einschalten, den Absender oder die Bestätigungs-E-Mail festlegen, ein Formular mit Double-Opt-in veröffentlichen oder fortsetzen und eine Bestätigung erneut senden.
• —Ein API-Schlüssel und der Inhaber sehen jedes Formular im Workspace. Eine App, die ein Mitglied verbunden hat, sieht nur die Formulare, die dieses Mitglied erstellt hat, und nur die Audiences, die dieses Mitglied angelegt hat, sowie die eingebauten.
• —Das Erstellen, Aktualisieren, Veröffentlichen, Fortsetzen oder Duplizieren eines Formulars, dessen Absender oder zu benachrichtigende Adressen außerhalb dessen liegen, was ein beschränkter Schlüssel oder eine beschränkte App erreichen darf, wird mit 422 capability_unsupported beantwortet.
• —Ein Schlüssel oder eine App, die auf bestimmte Adressen beschränkt sind, dürfen als Absender und als zu benachrichtigende Adressen nur Adressen festlegen, die sie halten.
• —Das Löschen eines Formulars verlangt von einer OAuth-App einen Bestätigungscode, wie andere destruktive Änderungen auch. Ein API-Schlüssel braucht nie einen.

Die Webhooks form.submitted und form.confirmed informieren Ihre Systeme über jede Anmeldung. Ein auf bestimmte Adressen beschränkter Webhook erhält sie nie, weil Anmeldungen dem ganzen Workspace gehören.

• —Ein Feld namens oe_website ist eine Falle für Bots: Lassen Sie es leer und außerhalb des sichtbaren Bereichs, wie es das HTML oben tut. Eine Anmeldung, die es ausfüllt, bekommt eine normale Antwort und wird verworfen.
• —Die gehostete Seite und die Einbettung prüfen außerdem eine signierte Startzeit, und ein Formular, das schneller zurückgesendet wird, als ein Mensch es ausfüllen könnte, wird auf dieselbe Weise verworfen.
• —Ein Netzwerk kann in zehn Minuten 40 Anmeldungen senden, über alle Ihre Formulare hinweg und unabhängig vom Ergebnis. Danach erhalten JSON-Aufrufer 429 form_rate_limited, und ein reines HTML-Formular wird mit ?outcome=limited auf die gehostete Seite weitergeleitet.
• —Ein Workspace fasst standardmäßig 100 Formulare.

Alles hier gibt es auch im SDK als openemail.forms und in der CLI als openemail forms, und der MCP-Server hat Formular-Tools, sodass ein Agent ein Formular erstellen, veröffentlichen und im Blick behalten kann. Über MCP schreibt der Client das Design selbst und übergibt es als document.

Ein POST an subscribeUrl aus Ihrem eigenen Code braucht keine Zugangsdaten. Senden Sie die Antworten als JSON, geben Sie die Seite, auf der das Formular war, als oe_source mit, lassen Sie oe_started weg und senden Sie oe_website leer oder gar nicht. Alle Anmeldungen aus einem Netzwerk teilen sich das Limit von 40 alle zehn Minuten, ein Server, der Anmeldungen für viele Personen weiterreicht, erreicht es also schnell: Fügen Sie Personen, die Sie bereits kennen, stattdessen mit dem Import in eine Audience hinzu.