Forms reference — Metuo Astro
Metuo for Astro 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 (src/components/sections/BookSection.astro). All three places are the same
<Form name="book"> and send to the same place. It works in one of three ways, chosen with environment variables (copy
.env.example to .env, or set them in your host’s dashboard); no code changes.
| Form | Where | name of the <Form> / form in the payload |
Fields (name → label) |
Required |
|---|---|---|---|---|
| Booking | Home, Service, Contact | 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.json),
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.
| Mode | Set | Hosting | Where submissions go |
|---|---|---|---|
| Demo (default) | nothing | any static host | Nowhere: the form shows “Thank you” and logs the fields in the browser console. |
| Static | PUBLIC_FORM_ENDPOINT |
any static host | Posted from the browser to a form service or webhook. |
| Server | PUBLIC_FORM_MODE=server + FORM_PROVIDER |
a host with an Astro adapter | Delivered by the site’s own route to console, webhook, Mailchimp or Resend. |
Every mode shows the same states on the Submit button (spinner, “Thank you”, “Something went wrong”), keeps the typed
values after an error, resets the form after success and drops spam caught by the hidden honeypot field. The PUBLIC_
variables are read when the site is built: rebuild (or restart npm run dev) after changing them.
<Form> (design system) → browser: PUBLIC_FORM_ENDPOINT, or the demo → server mode: POST /api/forms/book → deliver() → provider(s) chosen in FORM_PROVIDERformEndpoint("book") in src/lib/forms/endpoint.ts decides where the form posts: /api/forms/book in server mode, else
PUBLIC_FORM_ENDPOINT, else nothing (demo mode). The browser part is src/design-system/scripts/form.ts.
1. Before sending: the check
Section titled “1. Before sending: the check”<Form> checks the fields when Submit is pressed: when the e-mail is empty or isn’t an e-mail address, the field gets the
focus, is marked invalid and shows “Please enter a valid email address.” (error of the field) until it is changed. Nothing
is sent until the check passes. Without JavaScript the browser’s own check runs and the form posts to the endpoint as an
ordinary form.
2. Static mode: form services and webhooks
Section titled “2. Static mode: form services and webhooks”Set PUBLIC_FORM_ENDPOINT to the URL the service gives you. The form posts multipart/form-data with
Accept: application/json, and the service must answer with a 2xx status; any other answer (or no answer) shows “Something
went wrong”.
| Service | PUBLIC_FORM_ENDPOINT |
Notes |
|---|---|---|
| Formspree | https://formspree.io/f/<form id> |
Emails you each submission. |
| Web3Forms | https://api.web3forms.com/submit |
Also set PUBLIC_FORM_ACCESS_KEY (sent as the hidden field access_key). |
| Getform, Basin | the form’s endpoint URL | |
| Zapier, Make, n8n, Pipedream | the webhook (“catch hook”) URL | Route submissions anywhere: Mailchimp, Google Sheets, Slack, a CRM. |
Fields sent: every field by its name (see the table above) — service once for each ticked session type, nothing when
none is ticked — plus form (book) and subject (“New session request”, for services that e-mail the submission). date
is YYYY-MM-DD and time HH:MM (24-hour), as the browser’s date and time inputs send them.
The endpoint is public (it is in the page), which is how these services are designed to work; they filter spam themselves.
A build with PUBLIC_FORM_ENDPOINT set sends the style guide’s sample forms nowhere: they are marked demo.
3. Server mode: your own route
Section titled “3. Server mode: your own route”For Mailchimp or Resend without a third-party service, run the form on your server:
- Add the adapter for your host:
npx astro add vercel(ornetlify,node, …). - Set
PUBLIC_FORM_MODE=serverand choose providers withFORM_PROVIDER.
The form then posts to POST /api/forms/book (src/lib/forms/route.ts, added by src/integrations/forms.ts; every other
page stays prerendered). Without an adapter the build stops with NoAdapterInstalled. Astro rejects cross-site posts to the
route, so only your own pages can submit. The route answers JSON: 200 { "status": "success" }, or 500 { "status": "error" } (404 for an unknown form, 400 when the body isn’t form data). Environment variables are read when the server
runs (process.env, then the values of the build).
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.
The variables of .env.example
Section titled “The variables of .env.example”| Variable | For | Needed | What it is |
|---|---|---|---|
PUBLIC_FORM_ENDPOINT |
static mode | no (demo mode when empty) | The form service’s or webhook’s URL |
PUBLIC_FORM_ACCESS_KEY |
static mode, Web3Forms | for Web3Forms | Your Web3Forms access key |
PUBLIC_FORM_MODE |
server mode | no | server adds the route and sends there (needs an adapter) |
FORM_PROVIDER |
server mode | 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.
What the route checks
Section titled “What the route checks”deliver() (src/lib/forms/deliver.ts) checks again on the server, since a browser can be bypassed. With the form’s
definition from src/lib/forms/definitions.ts (made from the copy, book.form in src/content/pages/book.json) it:
- drops the submission if the honeypot is filled (and answers success);
- reads each field of the form from the submitted data (trimmed);
service(everycheckboxesfield) is read as a list of all the ticked values; - answers the error state when a required field (the e-mail) is empty, or when a filled-in e-mail field doesn’t look like an address;
- builds the submission (
form,title,submittedAt,data,labels) and gives it to every provider named inFORM_PROVIDER; - answers success, or the error state with the reason logged (
[forms] <title> could not be delivered).
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 session request { 'first-name': 'Jane', 'last-name': 'Smith', email: 'jane@example.com', … }. 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,FNAMEfromfirst-nameandLNAMEfromlast-name, each only when filled in;MAILCHIMP_STATUSis 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 fromFORM_EMAIL_FROMtoFORM_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.
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. Metuo’s form doesn’t. - Merge fields: the first name (
first-name) →FNAMEand the last name (last-name) →LNAME, a new audience’s defaults. ChangemergeFieldsat the top ofproviders/mailchimp.tsif your audience uses other tags, for examplephone: "PHONE". - Session types as tags: add
"service"totagFieldsin the same file to tag each contact with the session types they ticked, besides the form’s title.
Webhook payload
Section titled “Webhook payload”{ "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).
4. Spam: the honeypot
Section titled “4. 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. When it holds anything the form shows “Thank you” without sending anything (and deliver() does
the same on the server), so the bot moves on; in static mode the field is left out of what is posted. Keep it as it is, and
don’t give a real field the name fax.
5. Your own provider (HubSpot, Brevo, Airtable, a database…)
Section titled “5. Your own provider (HubSpot, Brevo, Airtable, a database…)”-
Create
src/lib/forms/providers/<name>.tsexporting aFormProvider— throw to show the error state: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()}`);},}; -
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 “, “),
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.
6. Change the form
Section titled “6. Change the form”- Fields and labels live in the copy:
form.fieldsinsrc/content/pages/book.json(synced from the template’s content).nameis the key services and providers receive,labelis what people read above the field (and what the notification shows),placeholderis what the empty field shows,typepicks the control (text,email,tel,date,time,textarea,checkboxes),requiredmakes the field checked before sending (no asterisk is shown),erroris 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.jsonand the checkboxes follow. - Required fields come from the same
requiredflags: in server modedefinitions.tsreads them and the route checks them again before it sends anything. Only the e-mail is required. To require another field, setrequired: trueon it and give it anerrormessage. - A new field: add it to
form.fields, then place it in the form insrc/components/sections/BookSection.astro(<FormField {...fields.<key>} />; the form lays out its fields by hand, two columns from tablets up — addclass="md:col-span-2"for a full row). A newcheckboxesfield takes its choices fromoptionsand is sent as a list on its own. - A new form: lay it out with
<Form name="…" endpoint={formEndpoint("…")} hidden={formServiceFields()}>and<FormField>, add its definition toformsindefinitions.tsfor server mode and its name toFormKindintypes.ts.