Feedbackformular Next.js-Beispiel

Diese Seite zeigt, wie Sie einen Kontakt-/Feedbackformular-Webhook in eine Next.js-App über eine BFF-Route integrieren: Der Browser sendet an Ihre App, die Mailoo mit serverseitig gespeicherten Zugangsdaten aufruft. Kein API-Schlüssel auf dem Client.

Dies ist nicht dasselbe wie eine Form-Integration (Newsletter): Feedback verwendet POST /api/v1/webhooks/feedback/... und eine CONTACT_FORM-Integration. Für Anmeldeformulare siehe website-forms{.interpreted-text role="doc"} und website-forms-nextjs-example{.interpreted-text role="doc"}. Für die rohe API (Header, Body, CORS) siehe contact-feedback-form{.interpreted-text role="doc"}.

Voraussetzungen

Ein Mailoo-Projekt mit einer Kontakt-/Feedbackformular-Integration
Allowed origins (optional) in der Integration --- wenn gesetzt und CORS für Anfragen mit Origin durchgesetzt wird
Ein API-Schlüssel mit Feedback form submissions (webhook.feedback-submission) bei RESTRICTED oder Full Access

Umgebung (nur serverseitig)

Fügen Sie Folgendes zu .env.local (oder Ihrer Deployment-Umgebung) hinzu. Alle vier Kernvariablen sind erforderlich, damit das BFF Anfragen akzeptiert.

MAILOO_FEEDBACK_INTEGRATION_API=https://api.mailoo.app
MAILOO_FEEDBACK_INTEGRATION_API_KEY=your-api-key-here
MAILOO_FEEDBACK_INTEGRATION_PROJECT_UID=your-project-uid-here
MAILOO_FEEDBACK_INTEGRATION_ID=your-contact-form-integration-id-here

Optional (wird in metadata jeder Übermittlung auf dem Server eingefügt):


# MAILOO_FEEDBACK_INTEGRATION_FORM_NAMESPACE=production-site


# MAILOO_FEEDBACK_INTEGRATION_SITE_ID=my-brand

Optionale Allowlist: wenn gesetzt, lehnt das BFF Übermittlungen ab, deren metadata.formKey (oder Top-Level formKey) nicht in der Liste enthalten ist (kommagetrennt). Nehmen Sie jeden formKey auf, den Ihre UIs senden (z. B. web-contact-page).


# MAILOO_FEEDBACK_INTEGRATION_ALLOWED_FORM_KEYS=web-contact-page,support-widget

Nur serverseitig verwenden; kein NEXT_PUBLIC_* für API-URL oder Schlüssel.

Mehrere Formulare, eine Integration

Normalerweise konfigurieren Sie eine Feedback-Integration in der Umgebung, haben aber mehrere UIs (Kontaktseite, Support-Widget usw.). Unterscheiden Sie diese im JSON-Body über metadata --- z. B. formKey (stabiler String pro Formular) und entryPoint (z. B. contact_page, support_widget). Die Mailoo-API speichert dieses Objekt auf dem Nachrichten- und Feedback-Datensatz; siehe contact-feedback-form{.interpreted-text role="doc"}.

Mehrere Integrationen, mehrere BFF-Routen

Wenn Sie separate CONTACT_FORM-Integrationen benötigen (verschiedene API-Schlüssel, Posteingänge oder Allowlists), erstellen Sie eine BFF-Route pro Integration und übergeben Sie ein eigenes prefix (oder getConfig). Weisen Sie nicht mehrere Integrationen auf MAILOO_FEEDBACK_INTEGRATION_* um.

// app/api/v1/webhooks/team-subscription/submit/route.ts
import { createFeedbackSubmitHandler } from '@mailoo/forms/routes'

export const POST = createFeedbackSubmitHandler({
  prefix: 'MAILOO_TEAM_SUBSCRIPTION_FORM',
})

Umgebung für diese Route (gleiches Suffix-Muster wie das Standard-Feedback-Präfix):

MAILOO_TEAM_SUBSCRIPTION_FORM_API=https://api.mailoo.app
MAILOO_TEAM_SUBSCRIPTION_FORM_API_KEY=...
MAILOO_TEAM_SUBSCRIPTION_FORM_PROJECT_UID=...
MAILOO_TEAM_SUBSCRIPTION_FORM_INTEGRATION_ID=...

# Optional:


# MAILOO_TEAM_SUBSCRIPTION_FORM_ALLOWED_FORM_KEYS=pricing-team-request

Client-Hooks verwenden einen endpoint, der auf diesen BFF-Pfad zeigt.

BFF-Routenhandler

Verwenden Sie bevorzugt @mailoo/forms/routes --- implementieren Sie Validierung oder den Webhook-Proxy nicht neu.

Erstellen Sie app/api/v1/webhooks/feedback/submit/route.ts:

import { createFeedbackSubmitHandler } from '@mailoo/forms/routes'

export const POST = createFeedbackSubmitHandler()
// Optional: { prefix, getConfig, logger }
// Standard-Präfix: MAILOO_FEEDBACK_INTEGRATION

Die Fabrik:

Gibt 503 zurück, wenn Zugangsdaten für das gebundene Präfix (oder getConfig) fehlen.
Validiert email / message, fügt formKey in metadata ein, wendet ${prefix}_FORM_NAMESPACE, ${prefix}_SITE_ID und ${prefix}_ALLOWED_FORM_KEYS an.
Leitet an ${api}/api/v1/webhooks/feedback/${projectUid}/${integrationId} mit X-API-Key und Origin / Referer über @mailoo/next-core weiter.

Bevorzugter Konfigurationshelfer für Layout-Gating:

import {
  getMailooFormsIntegrationConfig,
  MAILOO_FEEDBACK_INTEGRATION_PREFIX,
} from '@mailoo/forms'

const config = getMailooFormsIntegrationConfig({
  prefix: MAILOO_FEEDBACK_INTEGRATION_PREFIX,
})

Veraltet (weiterhin exportiert; nicht erweitern): getMailooFeedbackIntegrationConfig, getMailooFormIntegrationConfig, isMailooFeedbackIntegrationConfigured.

Client: POST an das BFF

Senden Sie von einer Client-Komponente JSON per POST an /api/v1/webhooks/feedback/submit mit mindestens email und message. Fügen Sie metadata.formKey (und weiteren Kontext) hinzu, damit Sie im Dashboard erkennen können, welches Formular verwendet wurde. Oder nutzen Sie useMailooFeedbackSubmit aus @mailoo/forms/hooks.

'use client'

async function submitFeedback() {
  const res = await fetch('/api/v1/webhooks/feedback/submit', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email: 'user@example.com',
      message: 'The checkout button does nothing on mobile.',
      subject: 'Bug report',
      name: 'Jane',
      metadata: {
        formKey: 'web-contact-page',
        pageUrl: typeof window !== 'undefined' ? window.location.href : '',
      },
    }),
  })
  const data = await res.json()
  if (!res.ok) throw new Error(data.message || 'Submit failed')
  return data
}

Behandeln Sie 503 (Integration nicht konfiguriert) und 400 (Validierung oder unzulässiger formKey) in Ihrer Benutzeroberfläche.

Paketreferenz

Paket: @mailoo/forms (createFeedbackSubmitHandler aus @mailoo/forms/routes, useMailooFeedbackSubmit aus @mailoo/forms/hooks) --- siehe nextjs-packages{.interpreted-text role="doc"}

Siehe auch

contact-feedback-form{.interpreted-text role="doc"} --- Endpunkt und JSON-Felder
website-forms-nextjs-example{.interpreted-text role="doc"} --- Form-(Newsletter-)BFF-Muster
nextjs-packages{.interpreted-text role="doc"} --- @mailoo/forms-Übersicht
OpenAPI: https://api.mailoo.app/docs/v1

Kontakt / Feedback: Next.js-Beispiel