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": "…" }
urlmust be a publichttps://address. Redirects are not followed.- Optional
method:POST(the default),PUTorPATCH. - Optional
headers:Authorizationor names startingX-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
requiredon 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 |
Related pages
Something wrong on this page? Email support@siteship.ai. Checked on November 14, 2026.