Formular-API

Abonnentinnen und Abonnenten über öffentliche Formular-Endpunkte erfassen.

Endpunkt

Unterstützte Content-Types

• application/json
• application/x-www-form-urlencoded
• multipart/form-data

Verhalten

• Der Formular-Endpunkt muss existieren und aktiv sein — eine unbekannte Formular-ID liefert 404, ein inaktives Formular liefert 403
• Ein Honeypot-Feld wird geprüft, um Spam zu blockieren
• Feldanforderungen werden anhand der Formularkonfiguration validiert (ein Fehlschlag liefert 400)
• Rate-Limiting erfolgt pro IP
• Der Request-Body ist auf 100 KB begrenzt; ein größerer Body liefert 400
• Eine optionale Weiterleitung nach dem Absenden wird unterstützt

Beispielanfrage

curl -X POST "https://<deployment>.convex.site/forms/<formId>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "lead@example.com",
    "firstName": "Avery",
    "company": "Acme"
  }'

Typische Antworten

Erfolg (HTTP 200). Der Formular-Endpunkt läuft durch die Hülle des öffentlichen Token-Endpunkts, daher trägt der Body ein ok auf oberster Ebene und verschachtelt message unter data:

{ "ok": true, "data": { "message": "Form submitted successfully" } }

Ist für das Formular eine Weiterleitungs-URL konfiguriert, liefert ein erfolgreiches Absenden statt dieses JSON-Bodys ein 302 auf diese URL.

Double Opt-in / ausstehende Bestätigung

Wenn das Thema, für das sich das Formular anmeldet, eine Bestätigung erfordert, wird der Kontakt erst hinzugefügt, nachdem er per E-Mail bestätigt hat. Das Absenden liefert weiterhin HTTP 200, allerdings mit einem eigenen Body, der signalisiert, dass eine Bestätigungs-E-Mail versendet wurde:

{
  "ok": true,
  "data": {
    "message": "Please check your email to confirm your subscription",
    "confirmationRequired": true
  }
}

Ist eine Weiterleitungs-URL konfiguriert, führt dieses Ergebnis dorthin mit angehängtem ?confirmation=pending, sodass die Erfolgsseite ihren Text anpassen kann.

Double Opt-in ist die Vereinigung des Formular-Schalters doubleOptIn und der Einstellung requireDoubleOptIn des Themas — wird eines von beiden aktiviert, erzwingt das den Ablauf mit ausstehender Bestätigung. Unter Themen erfahren Sie, wie Sie es am Thema aktivieren.

Validierungsfehler

Ein Validierungsfehler liefert HTTP 400 mit dem Standard-Fehler-Envelope. Die category ist invalid_input; der maschinenlesbare reason steht in data:

{
  "error": {
    "category": "invalid_input",
    "message": "Email is required",
    "data": { "reason": "validation_error" }
  }
}