Skip to content
Sign inJoin waitlist

Forms reference — Metuo Next.js

Metuo for Next.js has one form: the booking form (“Tell us about you.”) in the booking section of Home and the Service page, and the main section of the Contact page. All three places post to the same server action.

Form Where Server action form in the payload Fields (name → label) Required
Booking Home, Service, Contact src/lib/actions-book.ts (sendBooking) book first-name First Name, last-name Last Name, email Email, phone Phone, service Preferred session type, date Preferred Date, time Preferred Time, message What would you like support with? email

“Preferred session type” is a group of checkboxes, one per service (the names in src/content/collections/services.ts), so the visitor can tick several or none. The e-mail is the only required field, and it must look like an e-mail address; every other field can be left empty.

<Form> (design system) → server action (src/lib/actions-book.ts) → deliver() → provider(s) chosen in FORM_PROVIDER

The form, its states (sending, “Thank you”, “Something went wrong”), the e-mail check and the spam honeypot work out of the box. Where the submissions go is a setting, not code. What the form asks, and how to edit it, is in Forms.

Copy .env.example to .env.local (or add the variables in your host, e.g. Vercel → Settings → Environment Variables) and set FORM_PROVIDER. Restart npm run dev after changing it.

FORM_PROVIDER What happens Variables
console (default) Printed to the server log. For development. —
webhook Posted as JSON to a URL — Zapier, Make, n8n, Pipedream, Formspree, Slack workflow, your own API. FORM_WEBHOOK_URL, optional FORM_WEBHOOK_SECRET (sent as Authorization: Bearer …)
mailchimp Sender added or updated in an audience, tagged with the form, the rest saved as a note. MAILCHIMP_API_KEY, MAILCHIMP_AUDIENCE_ID, optional MAILCHIMP_STATUS
resend Emailed to you; replying answers the sender. RESEND_API_KEY, FORM_EMAIL_TO, FORM_EMAIL_FROM

Use several at once with a comma: FORM_PROVIDER=resend,mailchimp emails you and adds the contact to Mailchimp. If any of them fails, the visitor sees “Something went wrong” (their input stays in the form) and the reason is logged on the server. The providers run at the same time, so when one fails the others have usually delivered already: sending again can duplicate. Each submission carries the form’s name (form: book) and its title (title: “New session request”), whichever page it was sent from.

Variable For Needed What it is
FORM_PROVIDER all no (console when missing) console, webhook, mailchimp, resend, or several, separated by commas
FORM_WEBHOOK_URL webhook yes The address that receives the POST
FORM_WEBHOOK_SECRET webhook no Sent as Authorization: Bearer <secret>; leave it empty to send no header
MAILCHIMP_API_KEY mailchimp yes Ends in your data center, e.g. …-us21
MAILCHIMP_AUDIENCE_ID mailchimp yes The audience that receives the contacts
MAILCHIMP_STATUS mailchimp no (transactional) The status of a new contact: transactional, pending or subscribed
RESEND_API_KEY resend yes Your Resend API key
FORM_EMAIL_TO resend yes The recipient, or several separated by commas
FORM_EMAIL_FROM resend yes A sender on a domain verified in Resend, e.g. Metuo <forms@yourdomain.com>

A provider that needs a variable and doesn’t find it stops that submission with Missing environment variable <NAME> (see .env.example) in the server log; a name in FORM_PROVIDER that doesn’t exist does the same with Unknown FORM_PROVIDER "<name>". The visitor sees “Something went wrong” in both cases.

  • console: [forms] <title> followed by the submitted values (data) as an object, for example [forms] New session request { 'first-name': 'Jane', 'last-name': 'Smith', email: 'jane@example.com', … }. In development it shows in the terminal that runs npm run dev; on a host, in its logs.
  • webhook: one POST of JSON (Content-Type: application/json) holding the whole submission, as in the payload below. An answer that isn’t a success is an error.
  • mailchimp: three calls. The sender is added or updated in the audience (email, in lower case, FNAME from first-name and LNAME from last-name, each only when filled in; MAILCHIMP_STATUS is the status of a new contact only), tagged with the form’s title, and a note is added to the profile: the title, then one “Label: value” line for each field that was filled in (the ticked session types joined with commas).
  • resend: one e-mail from FORM_EMAIL_FROM to FORM_EMAIL_TO. The subject is the title followed by the sender’s name, first and last name together (“New session request — Jane Smith”; the title alone if both are empty), the reply address is the sender’s e-mail, and the text is one “Label: value” line for each field that was filled in, then the time it was sent.
  • API key: Profile → Extras → API keys. It ends in your data center (…-us21); nothing else to configure.
  • Audience ID: Audience → Settings → Audience name and defaults.
  • Consent: new contacts are added as transactional — they can receive replies, not campaigns. Use pending to send a double opt-in email, or subscribed only if the form asks for marketing consent. Metuo’s form doesn’t.
  • Merge fields: the first name (first-name) → FNAME and the last name (last-name) → LNAME, a new audience’s defaults. Change mergeFields at the top of providers/mailchimp.ts if your audience uses other tags, for example phone: "PHONE".
  • Session types as tags: add "service" to tagFields in the same file to tag each contact with the session types they ticked, besides the form’s title.
{
"form": "book",
"title": "New session request",
"submittedAt": "2026-10-19T10:48:23.256Z",
"data": {
"first-name": "Jane", "last-name": "Smith", "email": "jane@example.com", "phone": "",
"service": ["Life coaching", "Mindset & resilience training"], "date": "2026-11-03", "time": "14:30",
"message": "I'd like help managing stress during a career change."
},
"labels": {
"first-name": "First Name", "last-name": "Last Name", "email": "Email", "phone": "Phone",
"service": "Preferred session type", "date": "Preferred Date", "time": "Preferred Time",
"message": "What would you like support with?"
}
}

data has a key for every field, in the order of the form, and labels the label of each. A text field left empty is ""; service is always a list of the ticked session types ([] when none). date is YYYY-MM-DD and time is HH:MM (24-hour), as the browser’s date and time inputs send them.

The form carries a hidden text field named fax (honeypotField in src/design-system/components/forms/form-state.ts): it is out of sight and out of the tab order, a person never fills it, and bots usually do. deliver() looks at it first: when it holds anything, the visitor is shown “Thank you” and nothing is sent, so the bot moves on. Keep it as it is, and don’t give a real field the name fax.

In the browser, <Form> checks the fields before sending: when the e-mail is empty or isn’t an e-mail address, the field gets the focus and shows “Please enter a valid email address.” (error of the field) until it is changed.

sendBooking checks again on the server, since a browser can be bypassed. It returns the error state when the e-mail isn’t empty and doesn’t look like an address, then lists the fields of the form (the copy: book.form.fields) and calls deliver(data, { form, title, fields, required, lists }) from src/lib/forms/deliver.ts, which:

  1. drops the submission if the honeypot is filled;
  2. reads each listed field from the submitted data (trimmed); the fields in lists (every checkboxes field, here service) are read as a list of all the ticked values;
  3. returns the error state when a required field (the e-mail) is empty;
  4. builds the submission (form, title, submittedAt, data, labels) and gives it to every provider named in FORM_PROVIDER;
  5. returns the success state, or the error state with the reason logged ([forms] <title> could not be delivered).

4. Add your own provider (HubSpot, Brevo, Airtable, a database…)

Section titled “4. Add your own provider (HubSpot, Brevo, Airtable, a database…)”
  1. Create src/lib/forms/providers/<name>.ts:

    import { env, valueOf, type FormProvider } from "../types";
    export const brevoProvider: FormProvider = {
    name: "brevo",
    async send(submission) {
    const response = await fetch("https://api.brevo.com/v3/contacts", {
    method: "POST",
    headers: { "api-key": env("BREVO_API_KEY"), "Content-Type": "application/json" },
    body: JSON.stringify({
    email: valueOf(submission, "email"),
    attributes: { FIRSTNAME: valueOf(submission, "first-name"), LASTNAME: valueOf(submission, "last-name") },
    updateEnabled: true,
    }),
    });
    if (!response.ok) throw new Error(`Brevo responded ${response.status}: ${await response.text()}`);
    },
    };
  2. Register it in providers/index.ts (brevo: brevoProvider).

  3. Set FORM_PROVIDER=brevo and its variables in .env.example / your host.

Helpers from types.ts: valueOf(submission, name) returns one field as text (a list joined with “, “), toLines(submission) returns "Label: value" lines for every filled field, and env(name) reads a required variable with a clear error. The form always delivers an email; the names (first-name, last-name) may be empty.

  • Fields and labels live in the copy: book.form.fields in src/content/pages/book.ts. name is the key providers receive, label is what people read above the field (and what the notification shows), placeholder is what the empty field shows, type picks the control (text, email, tel, date, time, textarea, checkboxes), required makes the field checked before sending (no asterisk is shown), error is the message shown when the check fails. The form’s title (formTitle), the button’s three texts and the title of the notification (notification) are there too.
  • The session types are the services’ names: add, rename or remove a service in src/content/collections/services.ts and the checkboxes follow.
  • Required fields come from the same required flags: the server action checks them again before it sends anything. Only the e-mail is required. To require another field, set required: true on it and give it an error message.
  • A new field: add it to book.form.fields, then place it in the form in src/components/sections/BookSection.tsx (<FormField {...fields.<key>} />; the form lays out its fields by hand, two columns from tablets up — add className="md:col-span-2" for a full row). A new checkboxes field takes its choices from options and is sent as a list on its own.
  • A new form: lay it out with <Form> and <FormField>, add a server action next to the other (src/lib/actions-<form>.ts, “use server”) that calls deliver(data, { form, title, fields, required }), and add the form name to FormKind in types.ts.