Add or update a form on a site
upsert_site_formDeclares a built-in form on a site you own: its fields (text, email, textarea, checkbox, month, date, tel, select), the recipient email (kept on the server, never in the page), the button label and the thank-you message. Entries are saved and emailed from Pagetool, behind Turnstile, a honeypot, a minimum fill time, rate limits and field validation. Returns form_key and placeholder_html: put placeholder_html in the page HTML where the form should appear (replace_page_html, or stage then publish_staged). Pass form_key to update an existing form. For any date or month question use a month/date field here (past dates are never offered, and recurring events via occurs drop off once they pass) rather than a raw in page HTML, which the server cannot check. Free.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"site_key": "<site_key>",
"name": "<name>",
"recipient_email": "<recipient_email>",
"fields": "<fields>"
},
"name": "upsert_site_form"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The form's name, used in the notification subject "<Site name>: new <name>", e.g. "Open mic sign-up". 1-120 characters. | |
| stage | No | true = stage this form change with the page: visitors keep the live form until publish_staged (discard_staged drops it); preview at staged_preview_url. The operator token always stages on a published site. Omit for an immediately live change. | |
| fields | Yes | 1-20 fields, in display order. | |
| classes | No | Optional Tailwind/CSS class strings to style the form to match the page. | |
| form_key | No | Omit to create a new form; pass an existing form_key (from a previous call) to update that form. | |
| site_key | Yes | The site the form belongs to. Must be yours. | |
| submit_label | No | Button text. Default "Send". Max 60. | |
| recipient_email | Yes | Where entries are emailed. Stored on the server only; never appears in the page. | |
| success_message | No | Shown after a successful entry. Default "Thanks! Your entry was sent." Max 300. May include {field_name} for a text, select, email or tel field, e.g. "Thanks, {name}!" |