Skip to main content

For your AI and the curious

Forms reference

A form is plain HTML that posts to /api/forms/<id>. SiteShip reads its fields, checks each submission, blocks spam, stores it and emails it.

On this page

A form is its HTML. You write a plain form that posts to /api/forms/<id>. SiteShip reads the fields from the page, checks every submission against them, blocks spam, stores the submission and emails the site owner.

This page is the forms topic of the connector's guide tool. For where submissions go afterwards, see Where your leads go.

Markup and action

<form action="/api/forms/quote" method="post" class="space-y-4">
  <label class="block">Name <input type="text" name="name" required></label>
  <label class="block">Email <input type="email" name="email" required></label>
  <label class="block">Phone <input type="tel" name="phone"></label>

  <label class="block">Service
    <select name="service" required>
      <option value="">Choose one</option>
      <option>Weekly cleaning</option>
      <option>Repair</option>
    </select>
  </label>

  <fieldset>
    <legend>Extras</legend>
    <label><input type="checkbox" name="extras" value="Salt system"> Salt system</label>
    <label><input type="checkbox" name="extras" value="Heater"> Heater</label>
  </fieldset>

  <label class="block">Message <textarea name="message" rows="4"></textarea></label>

  <p data-form-success hidden>Thanks! We'll call you within one business day.</p>
  <p data-form-error hidden></p>

  <button type="submit">Get my quote</button>
</form>

You write only the HTML. SiteShip adds the submit script, the messages and the spam protection. Don't write a submit handler, fetch code, a honeypot or a hidden field of your own.

The action is written out in full. SiteShip finds forms by it, so an action built with Liquid, such as /api/forms/{{ id }}, is refused. The <id> is letters, digits, hyphens and underscores. For the same form on many pages, write the opening form tag in each page and put the shared fields in a partial.

What the HTML says is what the server enforces:

In the HTML Enforced
required The field must be filled
type email, tel, url, number (with min and max), date, time and datetime-local are checked
maxlength Caps the length. Any field takes up to 5,000 characters, an email up to 320
<select> Takes only its options
Radios and checkboxes Take only their values. A checkbox group keeps every box ticked, stored as Salt system, Heater
<label>, aria-label or the placeholder The name the owner sees in the email

Success and error. data-form-success and data-form-error are optional. Give them hidden. After a submission SiteShip shows the success element and hides the rest of the form. Problems go in the error element. Without them, a plain message appears at the end of the form and the fields stay.

Prefill from the address. A field starts with a value from the page address when its name matches. A link to /contact?service=Repair opens the form with that option chosen. An option matches by its value or its text.

What SiteShip read. After a page with a form is written, the response includes an author.form_read note:

form "quote": name*, email* email, phone tel, service* select (Weekly cleaning | Repair), …

* means required. If that is not what you meant, fix the HTML.

Forms that post elsewhere. A form may post to a third party's absolute address, such as Mailchimp or Formspree. It does not submit inside a private preview, and works once the site is live. A form that posts nowhere is refused: use a button or a mailto: link.

Delivery file

Without a delivery file, each submission is emailed to the site owner. Add data/forms/<id>.json to name the form, choose who gets it, or send it to another service:

{
  "name": "Quote request",
  "notify": "office@example.com, owner@example.com",
  "webhook": { "url": "https://hooks.zapier.com/hooks/catch/1/abc/" }
}
Field Type What it does
name string What the owner calls the form. Used in the email subject. Defaults to the form id.
notify string Who gets each submission, comma-separated, at most 3. Defaults to the site owner.
webhook object Sends each submission to an outside address as JSON.

notify. An address that belongs to the site's account works right away. Any other address first gets a confirmation email and receives submissions only once confirmed. Until then, submissions are stored and the leads tool says who it is waiting for. Replying to a notification email answers the visitor.

webhook. SiteShip sends this body:

{ "formName": "Quote request", "data": { "name": "…", "email": "…" }, "submittedAt": "…" }
  • url must be a public https:// address. Redirects are not followed.
  • Optional method: POST (the default), PUT or PATCH.
  • Optional headers: Authorization or names starting X- only.
  • A webhook that will be refused when it is sent is reported at write time (author.form_webhook_refused).

A delivery file that is not valid JSON, or that does not fit this table, is refused (author.form_config_invalid_json, author.form_config_invalid).

Conditional and multi-step

Both work from data attributes. There is no script to write.

<div data-show-if="service=Other">
  <label>Tell us more <input type="text" name="other_service"></label>
</div>
Attribute Shows the block when
data-show-if="service=Other" service is Other
data-show-if="service" service has any answer
data-show-if="service!=Other" service is anything but Other
  • Several values are separated by a bar, for example party=9|10|11|12.
  • One field per block. > and < are not supported.
  • Fields in a hidden block are disabled, so they are not sent. The browser enforces required on them while they are shown. The server never requires them.

Multi-step forms use data-step blocks:

<div data-step>
  <label>Name <input type="text" name="name" required></label>
  <button type="button" data-next>Next</button>
</div>
<div data-step>
  <label>Email <input type="email" name="email" required></label>
  <button type="button" data-back>Back</button>
  <button type="submit">Send</button>
</div>

Next checks the step's fields first. The whole form posts at the end. Every field needs a fixed name.

Test submissions

A submission sent from a preview is stored as a test. It is never emailed or sent to the webhook, and it is kept for 7 days.

Read it back to check the form saved what you expected:

{ "site": "harbor-dental", "form": "quote", "status": "test" }

Spam handling

SiteShip blocks bots itself, with a hidden trap field and a timing check. There is no captcha.

Status What it is Kept
lead A real submission. Stored and emailed. Not removed by a limit
test Sent from a preview 7 days
spam Filled the trap field 30 days
unverified Sent without the page's script: a browser with JavaScript off, or a bot posting straight to the address 30 days

Spam and unverified submissions are never emailed. Unverified ones may be real people. When the leads tool shows an unverified count above 0, the AI is told to read them and tell the owner about any that look real.

Rate limits: 3 submissions a minute from one visitor, 60 a minute to one site, and 50 emailed leads a day for one site. See Limits for what happens at each.

Lint codes

These refuse the file until fixed:

Code Cause
author.form_action_missing The form has no action
author.form_action_invalid The action is #, javascript:, or a local path that is not /api/forms/<id>
author.form_custom_submit The form has its own @submit or onsubmit handler
author.form_dynamic_name A field uses :name. Write a fixed name
author.form_file_input An <input type="file">. Forms take text only: link to a hosted upload form, or ask visitors to email the file
author.form_password_input An <input type="password">. Link to the service that runs the login
author.form_no_fields The form has no named fields
author.form_reserved_name A field name starts with _, which is reserved for SiteShip

Advice, not blocking:

Code Cause
author.form_fields_without_form Named fields outside any form, so nothing sends them. Leave them if your own script reads them, as a calculator does
author.form_read Information: what SiteShip understood from each form

Something wrong on this page? Email support@siteship.ai. Checked on November 14, 2026.

Built in a chat

Home page of Low Tide Coffee, a coffee shop website built with SiteShip

Coffee shop

Low Tide Coffee

The prompt that built it

Build a website for Low Tide Coffee, a small coffee shop and roastery at 14 Harbor Street, Beaufort, SC. We roast our own beans in the back room. Open every day 7am to 3pm. Phone (843) 555-0114. A menu with prices (drip, cortado, cold brew, oat-milk latte, biscuits and pastries). Two house blends sold in the shop: Marsh Blend and Dock Street Dark. Catering for offices and events, with an enquiry form (name, email, date, number of people, message). Pages: Home, Menu, Our beans, Catering. Look: warm and moody. Dark roasted brown and cream with a burnt-orange accent, an elegant serif for headlines with a clean sans for text, a photo of coffee being poured in the hero, and a menu laid out like a printed cafe menu.

Swap in your own business details. Your AI will ask five quick questions if anything is missing.

Add SiteShip to your AI

SiteShip is a connector you add once. You'll create your free account when you connect. No card needed.

https://app.siteship.ai/mcp
ChatGPT
  1. Open ChatGPT on the web and go to Settings, then Apps and connectors.
  2. Choose Add custom connector (you may need to switch on Developer mode under Advanced).
  3. Name it SiteShip, paste the address above and choose OAuth.
  4. Sign in to SiteShip when asked, then start a new chat and say: Get started with SiteShip.

Custom connectors need a paid ChatGPT plan.

Claude
Add to Claude

This opens Claude with SiteShip filled in. Click Add, sign in to SiteShip, then say: Get started with SiteShip.

Or add it by hand

  1. Open Claude and go to Customize, then Connectors.
  2. Click Add, then Add custom connector.
  3. Name it SiteShip and paste the address above.
  4. Sign in to SiteShip when asked, then start a new chat and say: Get started with SiteShip.
Grok

Go to grok.com/connectors, choose New Connector, then Custom, and paste the address above.

Gemini

In the Gemini web app, open Apps/Connectors settings, add a custom connector and paste the address above. (US accounts only for now.)

Other AI apps and coding tools
  1. Open your AI app's settings and look for Connectors, Apps, Integrations or MCP servers.
  2. Add a custom (remote) connector and paste the address above.
  3. Sign in to SiteShip when asked, then start a new chat and say: Get started with SiteShip.

Works with any app that accepts a remote MCP server, including coding tools such as Claude Code, Cursor, VS Code and Codex.

Coding tools

Claude Code

claude mcp add --transport http siteship https://app.siteship.ai/mcp

Codex

codex mcp add siteship --url https://app.siteship.ai/mcp

Then say: Get started with SiteShip.