Benutzen

Formular in die Website einbauen

Die Website schickt ihr Formular an die Adresse des Endpunkts (Detailseite → Karte „Einbauen"). Sie hat die Form https://<installation>/f/<token>.

Als HTML-Formular

<form method="post" action="https://formrelay.example.org/f/<token>">
  <label for="name">Name</label>
  <input id="name" name="name" autocomplete="name" required>

  <label for="email">E-Mail</label>
  <input id="email" name="email" type="email" autocomplete="email" required>

  <label for="nachricht">Nachricht</label>
  <textarea id="nachricht" name="nachricht" required></textarea>

  <!-- Nicht entfernen: bleibt leer, Bots füllen es aus. -->
  <input name="_fr_hp" tabindex="-1" autocomplete="off" aria-hidden="true"
         style="position:absolute;left:-10000px">

  <button type="submit">Senden</button>
</form>

Die Detailseite zeigt dieses Beispiel mit der richtigen Adresse zum Kopieren.

  1. action auf die Adresse des Endpunkts setzen.
  2. Felder frei wählen. Das Feld, dessen Adresse als Antwortadresse dienen soll, heißt email — oder so, wie unter „Feld für die Antwortadresse" eingetragen.
  3. Das Feld _fr_hp unverändert übernehmen.
  4. Einmal von der echten Website aus abschicken und die Mail prüfen.

Nach dem Absenden kommt der Besucher auf die Danke-Seite des Formulars, ohne Danke-Seite auf eine Bestätigungsseite von Formrelay.

Regeln für die Felder

Regel Grenze
Größe der ganzen Einsendung 64 KB
Zahl der Felder 50
Länge eines Werts 10.000 Zeichen
Länge eines Feldnamens 100 Zeichen
Mehrfachauswahl name="themen[]" oder name="adresse[ort]", eine Ebene tief, höchstens 50 Werte
Dateien nicht möglich — eine angehängte Datei wird abgewiesen
Namen, die mit _fr_ beginnen für Formrelay reserviert, werden nicht weitergegeben

Mindestens ein Feld muss ausgefüllt sein. Parameter in der action-Adresse (?utm_source=…) werden ignoriert. Punkte und Leerzeichen in Feldnamen werden bei HTML-Formularen zu _ (vor.name → vor_name).

Mit JavaScript (fetch)

const antwort = await fetch('https://formrelay.example.org/f/<token>', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
  body: JSON.stringify({ name: 'Erika Mustermann', email: 'erika@example.org', nachricht: 'Hallo' }),
});
const ergebnis = await antwort.json(); // { ok: true } oder { ok: false, error: '…' }

Formrelay antwortet mit JSON, sobald die Anfrage Accept: application/json trägt oder der Rumpf JSON ist. Ein FormData-Rumpf funktioniert ebenso (body: new FormData(form) mit Accept: application/json). Das Feld _fr_hp gehört auch hier dazu, leer.

Status error Bedeutung
200 — angenommen ({"ok": true})
403 origin_missing Der Browser hat keine Herkunft geschickt (siehe unten)
403 origin_not_allowed Die Website steht nicht in den Domains des Formulars
404 not_found Diese Adresse gibt es nicht (mehr) — Token erneuert?
410 inactive pausiert oder stillgelegt
413 too_large größer als 64 KB
415 files_not_supported eine Datei angehängt
415 unsupported_type anderer Inhaltstyp als Formular oder JSON
422 empty, too_many_fields, value_too_long, invalid_fields, invalid_json Inhalt passt nicht zu den Regeln oben
429 rate_limited zu viele Einsendungen, retry_after nennt die Sekunden bis zum nächsten Versuch
503 not_configured Das Formular hat keinen bestätigten Empfänger

Die Antworten tragen CORS-Kopfzeilen nur für die Domains des Formulars.

Herkunft und Referrer-Policy

Formrelay nimmt nur Einsendungen an, deren Browser als Herkunft (Origin) eine der Domains des Formulars meldet — mit https://, für localhost und .test auch http://.

Meldet eine Seite „Die Nachricht ließ sich keiner Website zuordnen", prüfen Sie:

  • Referrer-Policy der Seite mit dem Formular: no-referrer und same-origin verhindern die Herkunftsangabe. Die Vorgabe der Browser, strict-origin-when-cross-origin, genügt.
  • Die Adresse im action-Attribut beginnt mit https://. Eine Weiterleitung von http auf https löscht die Herkunft.

Drosselung

Formrelay nimmt je Formular höchstens 5 Einsendungen in 10 Minuten aus demselben Netz und 60 Einsendungen in der Stunde insgesamt an. Darüber hinaus erscheint „Zu viele Einsendungen in kurzer Zeit" mit der Wartezeit.

Spam

Ein ausgefülltes Feld _fr_hp gilt als Spam: Der Absender sieht eine Erfolgsmeldung, nichts wird gespeichert, nur gezählt. Weitere Abwehr sind die Bindung an die Domains, die Drosselung und die Grenzen oben. Ein Captcha gibt es nicht.

Quelle dieser Seite: docs/benutzen/einbauen.md im Repository. Sie wird beim Bauen daraus erzeugt — Änderungen gehören in die Markdown-Datei, nicht in diese Seite.