Forms reference — Marai Neesu Next.js
Marai Neesu for Next.js has two forms, the inquiry on the Contact page and the newsletter on the Blog page:
| Form | Where | Server action | form in the payload |
Fields (name → label) |
|---|---|---|---|---|
| Inquiry | Contact page | src/lib/actions-contact.ts |
contact |
firstName First Name, lastName Last Name, email Email, phone Phone Number, interests I’m interested in … (a list), budget Project Budget (USD), message Message |
| Newsletter | Blog page | src/lib/actions-newsletter.ts |
newsletter |
email Email (required; Framer’s isn’t) |
The options of interests are the titles of the services (src/content/collections/services.ts): add, rename or remove
a service and the checkboxes follow.
<Form> (design system) → server action (src/lib/actions-contact.ts) → deliver() → provider(s) chosen in FORM_PROVIDERThe form, its states (sending, “Thank you”, “Something went wrong”) and the spam honeypot work out of the box. Where the submissions go is a setting, not code.
1. Pick a provider
Section titled “1. Pick a provider”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 and the services they picked, the rest saved as a note. | MAILCHIMP_API_KEY, MAILCHIMP_AUDIENCE_ID, optional MAILCHIMP_STATUS, MAILCHIMP_NEWSLETTER_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 (form) and the title of the notification (title, “New contact
inquiry”).
The variables of .env.example
Section titled “The variables of .env.example”| 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 from the contact form: transactional, pending or subscribed |
MAILCHIMP_NEWSLETTER_STATUS |
mailchimp | no (pending) |
The status of a new newsletter subscriber: pending (Mailchimp sends a confirmation email) 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. Marai Neesu <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.
What each provider receives
Section titled “What each provider receives”console:[forms] <title>followed by the submitted values (data) as an object, for example[forms] New contact inquiry { firstName: 'Jane', lastName: 'Smith', email: 'jane@example.com', interests: [ 'Web Design' ], … }. In development it shows in the terminal that runsnpm run dev; on a host, in its logs.webhook: onePOSTof 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,FNAMEfromfirstNameandLNAMEfromlastName;MAILCHIMP_STATUSis the status of a new contact only), tagged with the form’s title and each service they ticked, and a note is added to the profile: the title, then one “Label: value” line for each field that was filled in.resend: one e-mail fromFORM_EMAIL_FROMtoFORM_EMAIL_TO. The subject is the title followed by the sender’s name (“New contact inquiry — Jane Smith”; the title alone if the name is 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 (the services joined with commas), then the time it was sent.
Mailchimp notes
Section titled “Mailchimp notes”- 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. Usependingto send a double opt-in email, orsubscribedonly if the form asks for marketing consent. Marai Neesu’s form doesn’t. - Merge fields:
firstName→FNAME,lastName→LNAME(a new audience’s defaults). ChangemergeFieldsat the top ofproviders/mailchimp.tsif your audience uses other tags, for examplephone: "PHONE". The fields whose choices become tags are intagFields(interests).
Webhook payload
Section titled “Webhook payload”{ "form": "contact", "title": "New contact inquiry", "submittedAt": "2026-10-12T10:48:23.256Z", "data": { "firstName": "Jane", "lastName": "Smith", "email": "jane@example.com", "phone": "+1 555 0100", "interests": ["Product Design", "Web Design"], "budget": "5000", "message": "We need a new website." }, "labels": { "firstName": "First Name", "lastName": "Last Name", "email": "Email", "phone": "Phone Number", "interests": "I'm interested in ...", "budget": "Project Budget (USD)", "message": "Message" }}data has a key for every field (the names in the table above): text as "" when left empty, interests as a list
([] when nothing is ticked). labels has the label of each, in the order of the form.
2. Spam: the honeypot
Section titled “2. Spam: the honeypot”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.
3. The server action
Section titled “3. The server action”submitContact lists the fields of the form (the copy: contactForm) and calls
deliver(data, { form, title, fields, required, lists }) from src/lib/forms/deliver.ts, which:
- drops the submission if the honeypot is filled;
- reads each listed field from the submitted data (trimmed; the fields in
lists— the checkboxes — as a list); - returns the error state when a required field is empty;
- builds the submission (
form,title,submittedAt,data,labels) and gives it to every provider named inFORM_PROVIDER; - returns the success state, or the error state with the reason logged (
[forms] <title> could not be delivered).
On success the form empties and the button says “Thank you”; on an error the button says “Something went wrong” and the fields keep what was typed. In the browser the required fields and the e-mail’s format are checked before anything is sent (the browser’s own messages).
4. Add your own provider (HubSpot, Brevo, Airtable, a database…)
Section titled “4. Add your own provider (HubSpot, Brevo, Airtable, a database…)”-
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, "firstName"), LASTNAME: valueOf(submission, "lastName") },updateEnabled: true,}),});if (!response.ok) throw new Error(`Brevo responded ${response.status}: ${await response.text()}`);},}; -
Register it in
providers/index.ts(brevo: brevoProvider). -
Set
FORM_PROVIDER=brevoand its variables in.env.example/ your host.
Helpers from types.ts: valueOf(submission, name) returns one field as text (a list joined with commas),
senderName(submission) the first and last name together, toLines(submission) returns "Label: value" lines for
every filled field, and env(name) reads a required variable with a clear error.
5. Change the form
Section titled “5. Change the form”- Fields and labels live in the copy:
contactForminsrc/content/pages/contact.ts.nameis the key providers receive,labelis what people read,requiredadds the browser’s check (the server checks it again),placeholderis the grey hint. The button’s three texts and the title of the notification are there too. - Required fields: first name, last name, e-mail, phone and budget, as on the Framer site; the checkboxes and the
message are optional. Change a
requiredflag to change that. - A new field: add it to
contactForm.fields, then place it insrc/components/sections/ContactSection.tsx(<FormField {...fields.<name>} />, passed in bysrc/app/contact/page.tsx) — the form lays its fields out by hand. For another group of checkboxes give ittype: "checkboxes"and render a<CheckboxGroup>; the action sends everycheckboxesfield as a list. - A new form (a quote request, say): lay it out with
<Form>and<FormField>, add a server action next to this one (src/lib/actions-<form>.ts, “use server”) that callsdeliver(data, { form, title, fields, required }), and add the form name toFormKindintypes.ts.