Contact / feedback form

Use a Contact / feedback form integration to collect messages from your site (contact, support, feedback). Each submission creates a message in Mailoo and a linked feedback record with structured fields.

:::: important ::: title Important :::

Server-side only: Post from your backend or BFF; call Mailoo with X-API-Key from environment variables. Do not expose the key in browser JavaScript or public bundles. ::::

:::: note ::: title Note :::

Legacy: Calling the feedback webhook directly from the browser can work if CORS and allowed origins match, but it exposes the API key. Use a backend or BFF for new integrations. ::::

Quick start

In the dashboard, open your project → Create New Integration → Contact / feedback form.
Set allowed origins for the Origin header your server sends when forwarding (and for any legacy browser clients).
Create an API key with scope Feedback form submissions (webhook.feedback-submission) if you use a RESTRICTED key, or use Full Access. Store the key on the server only.
From your server, POST to the feedback webhook (see API reference below).
View submissions under Messages for that integration.

API reference

Endpoint

POST /api/v1/webhooks/feedback/{projectUid}/{integrationId}

Headers

Header Required Description

Content-Type Yes application/json

X-API-Key Yes Project API key with webhook.feedback-submission (or FULL)

Origin Recommended Must match an allowed origin when origins are configured

JSON body

Field Required Description

email Yes Sender email

message Yes Message body (plain text)

name No Sender name

subject No Subject line (defaults to a generic title if omitted)

metadata No Object with extra key/value data (stored with the submission)

Success response (200)

{
  "success": true,
  "messageId": "...",
  "feedbackId": "...",
  "message": "Feedback submission processed successfully"
}

Dashboard

Open Project → Integration → View Messages to list and open individual messages. Feedback integrations do not use the newsletter subscribers/campaigns tabs.

First-party Mailoo web app (`apps/web`)

The marketing / dashboard web application in the Mailoo monorepo uses the same integration type. With server-only environment variables MAILOO_FEEDBACK_INTEGRATION_API, MAILOO_FEEDBACK_INTEGRATION_API_KEY, MAILOO_FEEDBACK_INTEGRATION_PROJECT_UID, and MAILOO_FEEDBACK_INTEGRATION_ID set, the app:

Exposes POST /api/v1/webhooks/feedback/submit (BFF): the browser never sees the API key; the handler forwards to POST /api/v1/webhooks/feedback/{projectUid}/{integrationId}.
Enables a Report a problem control in the site footer and a global shortcut (⌘⇧B on macOS, Ctrl+Shift+B on Windows and Linux) that opens a localized feedback dialog.
Persists unfinished dialog fields in localStorage under a key derived from the integration ID (so drafts from different integrations or environments do not collide).

The integration ID is passed from the server layout to the client only to namespace that storage key; it is not a secret (it already appears in the webhook URL). API URL, project UID, and key remain on the server.

If you use MAILOO_FEEDBACK_ALLOWED_FORM_KEYS, include web-bug-report so the built-in dialog is accepted.

Full walkthrough, env options, and client/BFF patterns: feedback-form-nextjs-example{.interpreted-text role="doc"}.

Contact / feedback form

Quick start

API reference

First-party Mailoo web app (apps/web)

See also

First-party Mailoo web app (`apps/web`)