Add a contact form

A form needs no configuration: post to /_cactal/forms/{name} and Cactal stores the submission, emails the recipients, and lists it in the Forms tab. See Forms for the full contract.

Prerequisites

A website and an API key with any access role on it, see Create an API key
Familiarity with editing pages, see Edit source code

Write the form

Use a literal action path and a visible label on every input. This baseline works without JavaScript: the endpoint redirects back to the page with ?submitted=contact.

<form method="post" action="/_cactal/forms/contact" className="grid max-w-md gap-4">
  <label className="grid gap-1">
    Name
    <input name="name" autoComplete="name" required />
  </label>
  <label className="grid gap-1">
    Email
    <input name="email" type="email" autoComplete="email" required />
  </label>
  <label className="grid gap-1">
    Message
    <textarea name="message" rows={5} required />
  </label>
  <button type="submit">Send message</button>
</form>

Enhance it with fetch

Submit with fetch and Accept: application/json so visitors keep what they typed when something fails, and show a pending state, a thank-you, and field errors.

onSubmit={async event => {
  event.preventDefault()
  const form = event.currentTarget
  const response = await fetch(form.action, {
    method: 'POST',
    headers: { Accept: 'application/json' },
    body: new FormData(form)
  })
  const result = await response.json()
  if (result.ok) {
    // replace the form with a thank-you
  } else {
    // result.error.message, and result.error.fields[name] per input
  }
}}

429 means the visitor should retry shortly; 403 with code limit_reached means the site used its Free plan allowance for the month.

Test on the draft preview

Submit the form on the draft host. Draft submissions are stored as test submissions and never count toward limits.

Read test submissions

curl -G 'https://api.cactal.ai/v1/websites/V1StGXR8_Z5jdHi6B-myT/forms/submissions' \
  -H "Authorization: Bearer $CACTAL_API_KEY" \
  --data-urlencode 'source=draft'

Response

{
  "items": [
    {
      "id": "sub_7Hk2",
      "formName": "contact",
      "status": "inbox",
      "source": "draft",
      "data": [
        { "name": "name", "value": "Ada" },
        { "name": "email", "value": "ada@example.com" },
        { "name": "message", "value": "Testing the form" }
      ],
      "submitterEmail": "ada@example.com",
      "submitterName": "Ada",
      "pagePath": "/contact",
      "createdAt": "2026-09-11T14:02:11.000Z"
    }
  ],
  "nextCursor": null
}

Choose who gets the email

Each form emails its own recipients, starting with the organization owners. Add the business address to the form; addresses outside the organization confirm by email before they receive anything.

Add a recipient

curl -X POST 'https://api.cactal.ai/v1/websites/V1StGXR8_Z5jdHi6B-myT/forms/contact/recipients' \
  -H "Authorization: Bearer $CACTAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "email": "hello@northwinddental.com" }'

The notification subject uses the form name from the action path, so quote-request reads as “Quote Request”.

Next steps

Export submissions as CSV from the Forms tab, or filter the API by form, status, and source.
Restore a false positive from the Spam folder with Not spam; the missed notification is sent.

Get started

Core concepts

Guides

Build with agents

Platform

Add a contact form

Prerequisites

Next steps

​Prerequisites

​Next steps

Prerequisites

Next steps