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.
On this page(24)
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:
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.
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 <form method="post"> whose action is the form's address. This is the HTML embed exactly, and its markup is yours to style:
<form action="https://usecommune.com/f/k7x2p9" method="post">
<label for="commune-email-k7x2p9">Email</label>
<input id="commune-email-k7x2p9" type="email" name="email" placeholder="[email protected]" required>
<!-- Keep this hidden field. It catches spam bots. -->
<input type="text" name="website" tabindex="-1" autocomplete="off" aria-hidden="true" style="display:none">
<button type="submit">Subscribe</button>
</form>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 namedconsent, which posts itsvaluewhen ticked and nothing when not. Required whenever the form has it on. What is recorded.website, the honeypot. Keep it in the form, hidden, and empty. A bot fills in every field it finds, so a signup with anything inwebsiteis dropped, and answered as though it worked.page_url, optional: the page the form is on. Leave it out and Commune uses the browser'sRefererheader instead, which for a post from another site is usually just the site's origin. What it is for.keep_as_typed, optional:1keeps an address Commune asked about. See Did you mean.
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.actionset toredirect), 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, plus&suggestion=and the corrected address when there is one. A near miss Commune is asking about comes back as?error=suggestionwith itssuggestion. 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_requiredor?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 one410, 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.
POST /f/k7x2p9 HTTP/1.1
Host: usecommune.com
Content-Type: application/json
{
"email": "[email protected]",
"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 asinvalid_syntaxwithout 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 asname_too_longrather than cut.consent, boolean:truewhen the reader ticked the form's consent checkbox. Required, andtrue, 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, usuallylocation.href. AnhttporhttpsURL of up to 2000 characters. The#fragmentis removed, and a value that is not such a URL is ignored rather than refused.keep_as_typed, boolean, optional,falsewhen left out. Onlytruecounts; 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:
curl -i https://usecommune.com/f/k7x2p9 \
-H "content-type: application/json" \
-d '{"email": "[email protected]", "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:
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: 86400Every 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#
{ "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.
422 invalid_email: Commune will not take the address#
reason says why, and is one of the seven below. Ask the reader to fix it. Some reasons come with a suggestion, the corrected address, and then you can offer it: “Use [email protected]”. The address as typed is refused either way, so there is nothing to keep.
{
"error": "Enter your email address.",
"code": "invalid_email",
"reason": "empty"
}{
"error": "gmial.com looks like a typo. Did you mean [email protected]?",
"code": "invalid_email",
"reason": "typo",
"suggestion": "[email protected]"
}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.
{
"error": "Did you mean [email protected]?",
"code": "email_suggestion",
"suggestion": "[email protected]"
}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.
{
"error": "Enter your name.",
"code": "name_required"
}422 consent_required: the box was not ticked#
{ "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#
{
"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#
{ "error": "This form doesn't exist.", "code": "not_found" }{ "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#
{ "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 asuggestionwhen the ending is one key away from.com,.netor.org.noreply: an address that exists to send mail and never reads it, likenoreply@.typo: a known misspelling of a big provider (gmial.com), or a near miss of one whose domain takes no mail. Always comes with asuggestion.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 [email protected]” and “Keep what I typed”, and send the second withkeep_as_typed: true.invalid_emailwith asuggestion(atypo, or aninvalid_tld): no. Offer the correction only.keep_as_typeddoes 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.
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_formwithnew_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 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_urlonsubscriber.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.
<form id="signup">
<label for="signup-email">Email</label>
<input id="signup-email" type="email" name="email" autocomplete="email" required>
<!-- The honeypot. People never see it and bots fill it in. Send it as it is. -->
<input type="text" name="website" tabindex="-1" autocomplete="off" aria-hidden="true" style="display:none">
<button type="submit">Subscribe</button>
<p class="signup-error" role="alert" hidden></p>
<p class="signup-suggestion" hidden>
<span></span>
<button type="button" class="signup-use"></button>
<button type="button" class="signup-keep" hidden>Keep what I typed</button>
</p>
</form>
<p class="signup-done" role="status" hidden>
Almost there. Check your inbox and click the link to confirm.
</p>
<script>
// The form's address: its public_id, from the embed code Commune gave you.
const FORM_URL = "https://usecommune.com/f/k7x2p9";
// Your words, in your readers' language, keyed by `code` and, for a refused
// address, by `reason`. The server's `error` is English and is not shown.
const WORDS = {
empty: "Enter your email address.",
invalid_syntax: "That isn't a complete email address.",
invalid_tld: "That address doesn't end in a real domain.",
typo: "That domain looks like a typo.",
disposable: "Use an address you'll keep, not a throwaway inbox.",
noreply: "That's a no-reply address. Use the one you read.",
no_mail_server: "That domain can't receive email. Check it for typos.",
didYouMean: (address) => "Did you mean " + address + "?",
use: (address) => "Use " + address,
not_ready: "Signups are paused for now. Try again later.",
// Only when the form asks for a name, or for consent.
name_required: "Enter your name.",
name_too_long: "That name is too long.",
consent_required: "Tick the box to sign up.",
closed: "This form is closed.",
retry: "Something went wrong. Try again in a moment.",
};
const form = document.getElementById("signup");
const input = form.elements.email;
const submit = form.querySelector('button[type="submit"]');
const error = form.querySelector(".signup-error");
const suggestion = form.querySelector(".signup-suggestion");
const done = document.querySelector(".signup-done");
function reset() {
error.hidden = true;
suggestion.hidden = true;
input.removeAttribute("aria-invalid");
}
function fail(text) {
error.textContent = text;
error.hidden = false;
input.setAttribute("aria-invalid", "true");
}
// A correction to offer. "Keep what I typed" only when the address as typed
// is allowed, which is what email_suggestion means.
function offer(text, address, canKeep) {
suggestion.querySelector("span").textContent = text + " ";
const use = suggestion.querySelector(".signup-use");
use.textContent = WORDS.use(address);
use.onclick = () => {
input.value = address;
send(false);
};
const keep = suggestion.querySelector(".signup-keep");
keep.hidden = !canKeep;
keep.onclick = () => send(true);
suggestion.hidden = false;
input.setAttribute("aria-invalid", "true");
}
async function send(keepAsTyped) {
reset();
submit.disabled = true;
let response;
let body;
try {
response = await fetch(FORM_URL, {
method: "POST",
headers: { "content-type": "application/json" },
credentials: "omit",
body: JSON.stringify({
email: input.value.trim(),
website: form.elements.website.value,
page_url: location.href,
keep_as_typed: keepAsTyped,
}),
});
// Not every answer is JSON (a proxy's error page, for one).
body = (await response.json().catch(() => null)) || {};
} catch {
// Offline, or a server error, which carries no CORS headers.
submit.disabled = false;
return fail(WORDS.retry);
}
submit.disabled = false;
if (response.ok) {
// { "status": "ok" }. Say so here, or send them to a page of your own:
// location.href = "/thanks";
form.hidden = true;
done.hidden = false;
return;
}
switch (body.code) {
case "email_suggestion":
return offer(WORDS.didYouMean(body.suggestion), body.suggestion, true);
case "invalid_email":
if (body.suggestion) {
return offer(WORDS[body.reason] ?? WORDS.retry, body.suggestion, false);
}
return fail(WORDS[body.reason] ?? WORDS.retry);
case "not_ready":
case "name_required":
case "name_too_long":
case "consent_required":
return fail(WORDS[body.code]);
case "gone":
case "not_found":
return fail(WORDS.closed);
default:
// bad_request, a 5xx, anything new: never a dead end.
return fail(WORDS.retry);
}
}
form.addEventListener("submit", (event) => {
event.preventDefault();
send(false);
});
</script>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.