# Build your own signup form > A signup form on your own site, in your own design and your own language, sends Commune one request. This is that request in both of its shapes, every answer it can get back and what each one means, and a complete form that handles all of them. Guide 4 of 4 in the Commune developer documentation at https://usecommune.dev. ## One address, two ways to post to it Every form takes signups at its own address on Commune, the same address as its hosted page: the form's address: ``` POST https://usecommune.com/f/{public_id} ``` `public_id` is the short id in the form's embed code (`k7x2p9` in `https://usecommune.com/f/k7x2p9`), six to sixteen lowercase letters and digits. Commune shows it with the code under “Put it on your site” on the form's page, and the API returns it as `public_id` on every form. Making and changing the form itself (its tags, its emails, where readers go afterwards) is in [the Forms reference](https://api-reference.usecommune.dev/operation/operation-getform). **This is not part of the API.** It takes no key and no `Commune-Version`, it is on `usecommune.com` rather than the API's host, and it is meant to be called from a reader's browser, by anybody, from any page. The address is permanent: once a form is pasted somewhere, it keeps answering for as long as the form exists. The same address takes two shapes of request, and answers each in kind: - **A plain form post**, which is what the HTML embed is. No JavaScript, and the reader's browser follows a redirect. - **JSON**, which is what the script embed sends, and what your own form should send. It answers with JSON and a status code, and the page stays where it is. ## As a plain form post A `
``` The fields it reads: - `email`, the address. Required. - `name`, optional unless the form is set to require one: the reader's name. The embed includes it when the form asks for a name, and it is kept even when the form does not. - `consent`, the consent checkbox, when the form asks for consent: a checkbox named `consent`, which posts its `value` when ticked and nothing when not. Required whenever the form has it on. [What is recorded](https://usecommune.dev/guides/forms#consent). - `website`, the honeypot. Keep it in the form, hidden, and empty. A bot fills in every field it finds, so a signup with anything in `website` is dropped, and answered as though it worked. - `page_url`, optional: the page the form is on. Leave it out and Commune uses the browser's `Referer` header instead, which for a post from another site is usually just the site's origin. [What it is for](https://usecommune.dev/guides/forms#page-url). - `keep_as_typed`, optional: `1` keeps an address Commune asked about. See [Did you mean](https://usecommune.dev/guides/forms#suggestions). ### What a form post gets back A redirect, `303 See Other`, wherever one makes sense, so the reader always lands on a page: - **Signed up:** to the form's own after-signup page when it has one (`after_signup.action` set to `redirect`), and otherwise to the hosted page with `?sent=1`, which shows the form's after-signup message. - **An address Commune will not take:** to the hosted page with `?error=` and the [reason](https://usecommune.dev/guides/forms#reasons), plus `&suggestion=` and the corrected address when there is one. A near miss Commune is asking about comes back as `?error=suggestion` with its `suggestion`. The hosted page says what was wrong and lets the reader try again there. - **A name Commune will not take:** to the hosted page with `?error=name_required` or `?error=name_too_long`. - **A consent box left unticked:** to the hosted page with `?error=consent_required`. - **A form that cannot take signups yet:** to the hosted page with `?error=not_ready`. - **No such form:** `404`, and a deleted one `410`, each with one line of plain text. - **A body that is not form data:** `400`, in plain text. That is the whole of it, and it is the right choice when there is no JavaScript to run. Everything below is for a form that wants to stay on its page and say what happened in its own words. ## As JSON, from your own script Send `Content-Type: application/json` and a JSON object. The content type is what tells the two shapes apart, so a request without it is read as a form post, and a `FormData` body from `fetch` is a form post too: it gets a redirect, not JSON. request: ``` POST /f/k7x2p9 HTTP/1.1 Host: usecommune.com Content-Type: application/json { "email": "reader@example.com", "name": "Ana", "consent": true, "website": "", "page_url": "https://example.com/newsletter", "keep_as_typed": false } ``` - `email`, string, required. Trimmed, and stored in lowercase. Over 320 characters it is refused as `invalid_syntax` without being checked further. - `name`, string, optional unless the form requires one. Cleaned to one line and trimmed; anything that is not a string is read as no name. Over 100 characters it is refused as `name_too_long` rather than cut. - `consent`, boolean: `true` when the reader ticked the form's consent checkbox. Required, and `true`, whenever the form asks for consent; ignored when it does not. - `website`, string: the honeypot, as above. Send it empty, or leave it out. Anything else and the signup is dropped while the answer says it worked. - `page_url`, string, optional: the page the form is on, usually `location.href`. An `http` or `https` URL of up to 2000 characters. The `#fragment` is removed, and a value that is not such a URL is ignored rather than refused. - `keep_as_typed`, boolean, optional, `false` when left out. Only `true` counts; the string `"true"` does not. Any other field is ignored. There is nothing else to send: the form already knows its newsletter, its tags and its emails. You can try it from a terminal without signing anybody up, because a misspelt address is refused before anything is written: shell: ``` curl -i https://usecommune.com/f/k7x2p9 \ -H "content-type: application/json" \ -d '{"email": "jane@gmial.com", "website": ""}' ``` ### Cross-origin requests CORS is open on this address and only this one, because posting a signup from any page is the point of a form. A JSON post is not a simple request, so the browser sends a preflight `OPTIONS` first, and gets: preflight response: ``` HTTP/1.1 204 No Content Access-Control-Allow-Origin: * Access-Control-Allow-Methods: POST, OPTIONS Access-Control-Allow-Headers: content-type Access-Control-Max-Age: 86400 ``` Every answer to the `POST`, errors included, carries the same `Access-Control-Allow-Origin: *`, so your script can read the body of a `422` as well as a `200`. Send no credentials (`credentials: "omit"`): the endpoint reads no cookie and no session, and a browser refuses to send them to a wildcard origin anyway. ## Every response Every JSON answer is an object. A success is `{ "status": "ok" }`; everything else has `error` and `code`, and some have `reason` and `suggestion`. > **Branch on code, show your own words** > > `error` is a sentence in English, written to be shown to a reader as it is, and it can change. Don't match on it, and if your form is not in English, don't show it. Decide what to do from `code` (and `reason`, for a refused address), say it in your own words, and treat a `code` you do not recognise like an error you can retry. ### 200: signed up 200 OK: ``` { "status": "ok" } ``` Say so, or send the reader to a page of your own. What happened behind it depends on who the address belongs to, and on purpose the answer does not tell you: [a 200 is not a receipt](https://usecommune.dev/guides/forms#same-answer). ### 422 `invalid_email`: Commune will not take the address `reason` says why, and is one of the [seven below](https://usecommune.dev/guides/forms#reasons). Ask the reader to fix it. Some reasons come with a `suggestion`, the corrected address, and then you can offer it: “Use jane@gmail.com”. The address as typed is refused either way, so there is nothing to keep. 422 Unprocessable Content: ``` { "error": "Enter your email address.", "code": "invalid_email", "reason": "empty" } ``` 422, with a correction: ``` { "error": "gmial.com looks like a typo. Did you mean jane@gmail.com?", "code": "invalid_email", "reason": "typo", "suggestion": "jane@gmail.com" } ``` ### 422 `email_suggestion`: did you mean The address is valid and receives mail, but its domain is one letter away from a big provider's, so Commune asks before it sends a confirmation email to it. `suggestion` is the address with the provider's domain. Offer both: send `suggestion` as the `email`, or send the same address again with `keep_as_typed: true`. 422 Unprocessable Content: ``` { "error": "Did you mean pat@icloud.com?", "code": "email_suggestion", "suggestion": "pat@icloud.com" } ``` ### 422 `name_required` and `name_too_long`: the name `name_required` is a form set to require a name, sent none. `name_too_long` is a name over 100 characters. Neither has a `reason`. Ask the reader to fix the name; the address was not looked at yet. 422 Unprocessable Content: ``` { "error": "Enter your name.", "code": "name_required" } ``` ### 422 `consent_required`: the box was not ticked 422 Unprocessable Content: ``` { "error": "Tick the box to sign up.", "code": "consent_required" } ``` Only from a form that asks for consent, when the signup did not carry `consent: true`. Nothing is stored. Ask the reader to tick the box. ### 503 `not_ready`: the form is not taking signups yet 503 Service Unavailable: ``` { "error": "This form isn't taking signups right now. Try again later.", "code": "not_ready" } ``` The newsletter has no verified sender yet, and the confirmation email can only come from that sender. It is about the form, not the address, so every address gets it until the creator verifies their sender in Commune. Tell the reader to try again later. ### 404 `not_found` and 410 `gone`: no form here 404 Not Found: ``` { "error": "This form doesn't exist.", "code": "not_found" } ``` 410 Gone: ``` { "error": "This form no longer exists.", "code": "gone" } ``` `not_found` is a `public_id` that never existed, usually a typo in the address. `gone` is a form that was deleted, or whose newsletter Commune no longer sends. Neither comes back, so hide the form rather than retry. ### 400 `bad_request`: the body is not a JSON object 400 Bad Request: ``` { "error": "Send the email address as JSON.", "code": "bad_request" } ``` The content type said JSON and the body did not parse as an object. This one is a bug in the form, not something a reader did. **And anything else.** A server error, or a network that drops the request, can reach your script as a `fetch` that throws rather than as a response, because only the answers above carry CORS headers. Treat it like a `code` you do not know: say something went wrong, keep what the reader typed, and let them press the button again. ### Why an address is refused The `reason` on an `invalid_email`, and the value of `?error=` after a plain form post. The checks run in this order, cheapest first, and the first one that fails decides. - `empty`: no address, or only spaces. - `invalid_syntax`: not an address at all. No `@`, two of them, spaces, an empty part, or too long. - `invalid_tld`: shaped like an address, but the domain does not end in a real top-level domain (`company.con`). Comes with a `suggestion` when the ending is one key away from `.com`, `.net` or `.org`. - `noreply`: an address that exists to send mail and never reads it, like `noreply@`. - `typo`: a known misspelling of a big provider (`gmial.com`), or a near miss of one whose domain takes no mail. Always comes with a `suggestion`. - `disposable`: a throwaway inbox service, which stops receiving mail soon after. - `no_mail_server`: the domain does not exist, or publishes no way to deliver mail to it. If the lookup does not answer in time, the address is let through rather than refused. These are the checks Commune's own subscribe pages make, so an address your form accepts is one the newsletter can send to. ### Did you mean Two answers carry a `suggestion`, and the difference is whether the reader may keep what they typed: - `email_suggestion`: yes. The address works, Commune is only asking. Offer “Use pat@icloud.com” and “Keep what I typed”, and send the second with `keep_as_typed: true`. - `invalid_email` with a `suggestion` (a `typo`, or an `invalid_tld`): no. Offer the correction only. `keep_as_typed` does not change a refusal. ## A 200 is not a receipt A form must never reveal who is on a creator's list. If it answered “you are already subscribed”, anybody could test addresses against it. So every one of these gets the same `{ "status": "ok" }`, and the confirmation email is sent after the answer, so not even its timing differs: - a new address, which is sent a confirmation email; - somebody already subscribed, who joins the form with no email; - an address that bounced, complained, or is suppressed, which Commune will not email and does nothing with; - a post with the honeypot filled in; - a post over a [rate limit](https://usecommune.dev/guides/forms#limits). So “check your inbox” is the right thing to say after a `200`, and “you're subscribed” is not. Test with an address you can read. The order of the checks explains the rest. The form is looked at first (`404`, `410`, `503`), then the honeypot, then the rate limits, and only then the address. A post with the honeypot filled, or over a limit, gets a `200` even when its address would have been refused. ## Rate limits A form is the one place where somebody with no account makes Commune send an email to an address they typed, so it is limited three ways: - **20 posts from one IP address every 10 minutes**, across every form on Commune. A reader correcting a typo uses two or three. - **600 posts to one form every 10 minutes**, from everywhere together. - **3 confirmation emails to one address, for one newsletter, every hour**. Counted only for signups that would send one. Each window starts at the first request in it. The first two are counted on every post, before the address is checked, so refused addresses use them too. **A post over a limit is not refused:** it gets a `200` and nothing happens. There is no `429` and no `Retry-After`, because an answer that only some posts got would tell a script where the limits are. > **Post from the reader's browser, not from your server** > > The per-IP limit counts the address the request comes from. Relay signups through your own server (a server action, an API route, a serverless function) and every reader shares your server's address. Past 20 signups in 10 minutes, every one after is answered `200` and dropped, silently. Call this address from the page, with `fetch`, as the example below does. CORS is open so that you can. ## The name, when the form asks for one A form can ask for a name next to the address, off, optional or required. The name is held with the signup and written onto the subscription when the reader confirms, and only into an empty one: a signup never replaces a name the subscriber already has, and somebody already subscribed, who proves nothing by posting, does not get one from a form at all. It is what `{{ subscriber.display_name }}` says in the creator's emails. ## Consent, and what is recorded A form can draw a consent checkbox (`consent` on the form, off by default). When it is on it is required, and every signup that ticks it leaves a record on the subscriber: the checkbox's words exactly as they were shown, the privacy policy they link to, the page the form was on, when and from which IP address the box was ticked, and when and from which IP address the reader confirmed by email. A later signup adds a record and never replaces one. That is the evidence a creator shows when asked whether somebody agreed to be on the list, and it is on the subscriber in Commune, in the API and in the subscriber export. The words recorded are the form's own, from Commune, not whatever your page drew. So in a form of your own, put the same words next to your checkbox as the form has in Commune, and change them there when you change them on your page. The IP address is the one your reader's browser posted from, so a form that posts from your own server records your server's instead. Commune keeps no user agent. ## What happens after a signup Every signup is double opt-in. Behind a `200` for a signup that got past the honeypot and the limits, one of three things happened: - **Somebody new** (or who unsubscribed before) gets an email from the newsletter's own sender, “Confirm your subscription to” and the newsletter's name, with a link that lasts 48 hours. Replies go to the creator. Nothing else happens until they confirm. - **Somebody already subscribed** joins the form straight away: they get its tags and the newsletter publishes `subscriber.joined_form` with `new_subscriber: false`. No email, because their subscription did not change. - **An address that bounced, complained, or is suppressed** is left alone. The link opens a page with a “Confirm subscription” button, and only pressing it confirms. Opening the link does nothing, because mail scanners open every link in an email. Pressing it puts the reader on the list with the form's tags, publishes `subscriber.created` and `subscriber.joined_form` with `new_subscriber: true`, and sends them where the form says: the creator's own page (`after_confirm.action` `redirect`) or Commune's thank-you page. That part is the same however the signup arrived, because it happens on Commune. Signing up again before confirming sends a fresh email (within the per-address limit) and gives the link another 48 hours. The earlier email's link still works, and the signup now counts for the latest form and page. An automation can start on either event; the [automations guide](https://usecommune.dev/guides/automations) covers triggers. ### What the reader sees next is up to you A form's `after_signup` setting, a message or a redirect to the creator's page, is applied by the two embeds: the script shows the message or follows the redirect, and a plain form post is redirected by Commune. **A JSON answer does not carry it.** Your form decides what comes after a `200`: show your own message, or set `location.href` to your own page. If you want what the creator wrote in Commune, copy it into your form. ### What `page_url` is for `page_url` tells Commune which page the reader signed up on, and nothing checks it, so it is for showing, never for trusting. It is used in three places: - the confirmation email names its host: “You signed up for The Weekly Build on example.com”, which is how a reader recognises an email they asked for; - Commune's thank-you page, after confirming, offers a “Back to example.com” button that returns to it; - it is recorded with the signup and sent as `page_url` on `subscriber.joined_form`, to webhooks and to automations, so a creator can tell which page a form on several pages is working on. Leave it out and all three simply go without: the email does not say where, the thank-you page has no button, and the event carries `null`. ## A complete form A form in your own markup that posts JSON with `fetch` and handles every answer above: the success, the refusals in your own words, both kinds of suggestion, a form that is not ready or is gone, and a request that never got an answer. Replace the address with your form's, put the words in your readers' language, and style it however you like. signup.html: ```Almost there. Check your inbox and click the link to confirm.
``` It needs nothing else: no library, no key, no server of your own. If you would rather not write any of this, the script embed in Commune does the same in the form's own design, and the plain HTML embed does it without JavaScript. --- Next: [Use cases](https://usecommune.dev/use-cases.md) - Whole jobs done end to end, with an agent, with the API, or with both: win back readers, publish from anywhere, react in real time. - This guide as a page: https://usecommune.dev/guides/forms - Every guide on this origin has a Markdown twin at its own path with `.md` appended. - The whole API reference as one Markdown document: https://usecommune.dev/llms-full.txt - The index of everything here: https://usecommune.dev/llms.txt