Forms

A form lets a visitor send a message to the owner.

A form has two halves, and both are in the site's source:

• the declaration, in clave.site.json: what fields the form has, and where mail about it goes;
• the page: the HTML the visitor fills in.

{ "forms": { "contact": { "fields": ["name", "email", "message"], "notify": "you@example.com" } } }

A publish makes the form, or changes it to match. A form that leaves the file takes no more messages, and keeps the ones it has. A draft makes a form it is the first to declare, and that form takes messages from drafts only until a live publish declares it.

The page posts to Clave at POST /f/{public_id}. For a form in the file, the public id comes from the site and the name, so the page can carry it before the first publish. Keep the name, and the address keeps working. A form made before forms were in the file keeps the public id it was given. Clave gave each such form a name in the file, so it is declared like any other.

Enquiries

What comes through a form is an enquiry. Clave stores every one and can mail it.

• GET /v1/forms/{id}/submissions lists them, newest first.
• ?format=csv exports them.

Submissions are kept for 180 days. They are somebody else's contact details, and Clave is not an indefinite store of those.

On a draft

A form works on the site's draft too. A message sent there is a draft message:

• it is kept apart from the live site's messages;
• its mail goes to the owner only, with [Draft] in the subject;
• it uses none of the live form's limits, and has lower ones of its own: 3 a minute and 50 a day.

?slot=1 on the list reads the draft's messages. See Drafts and slots.

Where mail goes

notify must be an address on the account: the owner's, or a collaborator's. A publish that names any other address stops, and says which form.

Without that rule an account could point a form at a stranger and have Clave deliver a visitor's words there, on the same mail stream every other customer's form mail uses.

Clave reports notify_options on every surface, so the legal values are learned by lookup. A solo owner has exactly one: the address they sign in with.

The rule is checked when the form is written. A form written before the rule keeps the address it has.

What a form needs to exist

Forms need a Turnstile key on the deployment. Without one, Clave advertises no form tools at all: a tool that fails is worse than an absent one.

Mail needs a configured sender. Without one, an enquiry is stored and not mailed.

Read Forms.