zdeploy

Docs
PricingConsole

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

  1. Switch Forms on. A new app has it off, and the endpoint answers 403 with Forms 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.

  2. Get the app's id. It is data.app.id from creating the app, and GET /api/v1/services returns it as data.app.id. Inside the running app it is ZDEPLOY_AUTH_CLIENT_ID. The form's address is https://zdeploy.tech/api/v1/forms/<app id>.

  3. No key. Unlike every other service, this endpoint takes no API key: the browser posts to it directly. Never put ZDEPLOY_API_KEY in 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:

FieldTypeRequiredNotes
_formstringyesThe 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
_redirectstringnoWhere 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
_gotchastringnoA 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 namestringKept 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:

StatusWhenDo this
400Name 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 textFix the form. Do not retry the same post
403Forms are not switched on for this app.Switch Forms on (Before you start)
404No form is set up at this address.: no active app has this idCheck the app id in the form's action
411A multipart post without Content-LengthSend it with a length, or post urlencoded or JSON
413Over 64 KB, or over 50 fieldsSend less
415Any other Content-Type, including text/plainPost urlencoded, multipart or JSON
429Too many posts from one connection (5 a minute, 30 an hour), or the app took 1,000 today. Retry-After says whenShow the error to the person. Do not retry in a loop
400Double 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
429Double opt-in forms only: 3 confirmation emails to one address today, or 30 from the app this hourShow the error to the person
502Double opt-in forms only: We could not send the confirmation email. Try again shortly. Nothing was keptLet 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 _redirect as before, so point it at a page that says to check their email. Without _redirect the 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.