Forms
Point any HTML form at one URL, with no key and no backend. Every submission is kept for the app and its owner gets an email for each one. Free.
What it is
Forms keeps what people type into your site's forms. Point any HTML form at one URL and every submission is stored for your app, and the app's owner gets an email for each one. There is no key, no backend to write and no database table to make: the URL is meant to sit in your page's source.
Use it for contact forms, applications, sign-up requests, feedback: anything where a person fills in fields and someone reads them later. The owner reads submissions in the console, under the app's Forms tab, where they can also delete them.
Forms is free: switching it on adds nothing to the app's price.
Every form names itself. Each form sends a _form field with a name of its own, such as contact or community. Two forms on one site send two names, and the console shows them apart. A post without a name is refused.
Before you start
-
Switch Forms on. A new app has it off, and the endpoint answers
403withForms are not switched on for this app.until you do. Run this once, from your own shell, with your deploy credential (zda_...):curl -s -X POST "https://zdeploy.tech/api/v1/services/enable" \ -H "Authorization: Bearer zda_..." \ -H "Content-Type: application/json" \ -d '{"service":"forms"}'The person can also switch it on in the console, under the app's services.
-
Get the app's id. It is
data.app.idfrom creating the app, andGET /api/v1/servicesreturns it asdata.app.id. Inside the running app it isZDEPLOY_AUTH_CLIENT_ID. The form's address ishttps://zdeploy.tech/api/v1/forms/<app id>. -
No key. Unlike every other service, this endpoint takes no API key: the browser posts to it directly. Never put
ZDEPLOY_API_KEYin a page.
Your first call
A plain HTML form. It works with JavaScript off:
<form method="post" action="https://zdeploy.tech/api/v1/forms/APP_ID">
<input type="hidden" name="_form" value="contact">
<input type="hidden" name="_redirect" value="https://your-app.example/thanks">
<!-- Bots fill this in; people never see it. -->
<input type="text" name="_gotcha" tabindex="-1" autocomplete="off" hidden>
<label>Email <input type="email" name="email" required></label>
<label>Message <textarea name="message" required></textarea></label>
<button>Send</button>
</form>
After the post the browser goes to _redirect. Without one, or when it is on another site, the browser gets a short "Thanks, we got it" page with a link back.
The same post from JavaScript, which keeps the person on the page:
const res = await fetch('https://zdeploy.tech/api/v1/forms/APP_ID', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
body: JSON.stringify({ _form: 'contact', email, message }),
});
const out = await res.json();
if (!out.success) showError(out.error);
Reference
POST /api/v1/forms/:appId
Keep one form submission for the app, and email the app's owner about it. Public and keyless: call it from the browser.
Auth: none. The app must be active and have Forms switched on.
Request: application/x-www-form-urlencoded or multipart/form-data from a plain <form>, or a JSON object from code. A post with no Content-Type is read as urlencoded. Any field names you like. Fields that start with _ are instructions, not data, and are never stored:
| Field | Type | Required | Notes |
|---|---|---|---|
_form | string | yes | The form's name, unique to this form on your site, such as contact. Lowercased, and anything other than letters, digits, - and _ becomes -. Up to 40 characters |
_redirect | string | no | Where to send the browser after a plain HTML post. Used only when it is on the same site as the page that posted the form, so nobody can bounce visitors through zdeploy. Ignored for JSON |
_gotcha | string | no | A hidden trap for bots. Leave it empty and hidden. A post that fills it gets a normal success answer, and nothing is kept or sent |
| any other name | string | Kept as text. Up to 50 fields, names up to 100 characters, values up to 10,000. A name sent twice (checkboxes) is kept once, its values joined with , . Other names starting with _ are dropped |
Files are not kept: a file field is dropped, and the owner's email says which ones were. Nested JSON objects are refused; arrays are joined like repeated names. The page that posted is kept with the submission, without its query string.
Response: 200 for a JSON post (or an Accept: application/json post), not wrapped in data.
{ "success": true }
Response (plain HTML post): 303 to _redirect when it is on the posting site; otherwise 200 with a small "Thanks, we got it" HTML page that links back to the posting page. Errors come back as an HTML page too, with the same status codes as below.
Errors:
| Status | When | Do this |
|---|---|---|
400 | Name the form: send a "_form" field with a name unique to this form, such as "contact". Every form on a site needs its own.; The form was empty.; Invalid JSON body.; Send a JSON object of field names to values.; a field that is not text | Fix the form. Do not retry the same post |
403 | Forms are not switched on for this app. | Switch Forms on (Before you start) |
404 | No form is set up at this address.: no active app has this id | Check the app id in the form's action |
411 | A multipart post without Content-Length | Send it with a length, or post urlencoded or JSON |
413 | Over 64 KB, or over 50 fields | Send less |
415 | Any other Content-Type, including text/plain | Post urlencoded, multipart or JSON |
429 | Too many posts from one connection (5 a minute, 30 an hour), or the app took 1,000 today. Retry-After says when | Show the error to the person. Do not retry in a loop |
400 | Double opt-in forms only: This form needs your email address: we send a link to it, and the form is kept only once you click it. | Give the form an email field and make it required |
429 | Double opt-in forms only: 3 confirmation emails to one address today, or 30 from the app this hour | Show the error to the person |
502 | Double opt-in forms only: We could not send the confirmation email. Try again shortly. Nothing was kept | Let the person try again |
curl -s -X POST "https://zdeploy.tech/api/v1/forms/APP_ID" \
-H "Content-Type: application/json" \
-d '{"_form":"contact","email":"ann@example.com","message":"Hello"}'
GET /api/v1/forms/confirm
The link in a double opt-in form's confirmation email. Shows the person a page with one Confirm button; opening it changes nothing.
Auth: none. The token in the query is the proof.
Request: ?token= from the email. Never build this link yourself: only zdeploy has the token.
Response: 200 HTML page with a Confirm button that posts to the endpoint below. 404 HTML page when there is no token.
POST /api/v1/forms/confirm
The Confirm button. Confirms the submission, then emails the app's owner about it. Each link works once.
Auth: none. The token is the proof.
Request: application/x-www-form-urlencoded with one field, token.
Response: an HTML page. 200 "Confirmed"; 410 "This link has expired" (over 12 hours, and the submission is deleted); 404 "Link not found" (wrong, or already used).
Double opt-in
For a form that draws spam, the owner can make it double opt-in: the console, the app's Forms tab, Set up, Double opt-in, where they list the form names (the _form values) it applies to.
A post to a double opt-in form is kept but held. We email the address in its email field (or the first field whose name says email, such as work_email) a link, and the submission counts only once that person clicks it and presses Confirm. Then the owner gets their email and the submission shows in the console, marked "Email confirmed". A submission not confirmed within 12 hours is deleted. The confirmation email says only which form and app it is for: none of what was posted is in it.
What changes for the page that posts:
- The form needs an email field. A post without a valid address is refused with
400. - A JSON post answers
{ "success": true, "confirm": true }. Tell the person to check their email, not that you have their message. - A plain HTML post goes to
_redirectas before, so point it at a page that says to check their email. Without_redirectthe browser gets a "Check your email" page. - The person confirms on zdeploy, at
https://zdeploy.tech/api/v1/forms/confirm. Opening the link shows a Confirm button; the click confirms. That is deliberate: mail scanners open every link in an inbox, and a link that confirmed when opened would let them confirm a bot's post.
Turning a form off double opt-in stops new posts being held. Ones already waiting still need confirming, or go after 12 hours.
Limits and errors
Free, with no tiers. Per post: 64 KB, 50 fields, 10,000 characters per value. Per connection: 5 posts a minute and 30 an hour. Per app: 1,000 posts a day. The owner gets at most 30 notice emails an hour per app; past that, submissions are still kept, and the console shows them all.
Errors from a JSON post are JSON, { "success": false, "error": "..." }. Errors from a plain HTML post are a small HTML page carrying the same message.
The endpoint answers browsers from any site (CORS is open), because it has no key to protect.
Gotchas
Give every form its own _form. It is how the console tells your contact form from your application form. Reusing one name on two forms puts both in one list, with different fields mixed together.
Keep the trap hidden, and do not call it website. Bots fill in every field they see. _gotcha must be hidden with the hidden attribute, tabindex="-1" and autocomplete="off", so no person or password manager fills it in.
The notice goes to the app's owner. If the form has a valid email field, replying to the notice goes to that address. The only mail the person who filled in the form ever gets is the confirmation link of a double opt-in form, which has fixed wording. To send them a receipt or a reply, use Email.
_redirect must be on your own site. A redirect to another site is ignored, and the browser gets the thanks page instead. For a JSON post it is ignored either way: your code decides what to show.
Do not post from your server with the app key. The endpoint takes no key. A post from your server works, but every post from one server counts against one connection's limit, so the 5-a-minute cap will refuse your visitors. Let the browser post.
There is no read API yet. Submissions are read in the console. If the app itself needs the data, store it in your own database as well.