Create a signup form Run in API Explorer
Makes a signup form for this newsletter's list. Needs
audience: write, and is a write. Only for a newsletter Commune sends:
anything else answers 422.
Only name is required, and it is the form's name in Commune, which
readers never see. Everything left out takes the default a new form
gets in Commune: a heading naming the newsletter, Subscribe on the
button, no name field, a message after signing up and Commune's
thank-you page after confirming.
Making a form subscribes nobody. Somebody who signs up through it
gets an email asking them to confirm, and joins the list only once they
click it; somebody already on the list joins the form straight away,
with no email from it. Either way they get tag_ids and the newsletter
publishes subscriber.joined_form, which an automation can start on.
No request through this API can put anybody on the list through a form:
only the reader can.
confirmation_email is the email that asks a new signup to confirm:
its subject, the text above the button, the button's label and colour
and the small print under it. Every setting left null falls back to
the newsletter's default (PATCH /newsletters/{newsletter}/form-defaults)
and from there to Commune's own email, so a form that sets none of
them sends what every form does. The confirm button is always in it.
embed in the response is the code to paste. The script renders the
form with the settings saved here and picks up later changes by itself.
Publishes no event.
Headers
-
A value of your choosing naming the change this request is making.
Send the same value again to retry the same request. Commune replays the answer the first attempt gave instead of making the change twice, and marks the replay with an
Idempotent-Replay: trueresponse header. Send a different value for a different change: a key reused for a request that differs in any way answers409, because replaying an answer to a question you did not ask is a wrong answer you could not detect.A UUID per change is the usual choice. Remembered for 24 hours, per credential, so two credentials choosing the same value never see each other's answers.
Required, not optional.
Minimum length is
1, maximum length is255. -
The contract version this request is written against. Every version published so far is a release date (
YYYY-MM-DD), which is why the examples look like one, but the value is an opaque identifier: match it against the versions this API publishes rather than parsing it, because a future one may not be only a date. An unknown value answers400withinvalid_version.Omitting the header pins the request to the version that was current when the API key was issued, so an integration keeps working when a newer version ships.
Minimum length is
1.
Body
Required
-
What the form is called in Commune. Readers never see it.
Minimum length is
1, maximum length is100. -
Defaults to "Subscribe to" and the newsletter's name.
Maximum length is
150. -
Maximum length is
500. -
Defaults to
you@example.com.Maximum length is
80. -
Any of a form's name field settings. Only what is named changes.
Additional properties are NOT allowed.
-
Any of a form's consent settings. Only what is named changes.
Additional properties are NOT allowed.
-
Any of a form's style settings. Only what is named changes.
Additional properties are NOT allowed.
-
Live tags of this newsletter, from
GET /newsletters/{newsletter}/tags. Any other id answers422.Not more than
20elements. -
Any of what happens right after a signup. Only what is named changes.
Additional properties are NOT allowed.
-
Any of where a confirmed reader goes. Only what is named changes.
Additional properties are NOT allowed.
-
Any of the confirmation email's settings. Only what is named changes, and null hands a setting back to the level below it.
Additional properties are NOT allowed.
Responses
-
The form, as created, with nobody in it yet and the code to embed it.
-
The request was malformed, and the same request will fail the same way until it is changed.
paramnames the parameter or header at fault when there is exactly one, andallowed_valueslists what it accepts when that is a finite set. The code isbad_requestfor every case below except the last.- A query parameter: one the operation does not have, a value
outside its set, range or format (an unparseable cursor, an unknown
expandpath orfieldsname, an identifier that is not a UUID), or a required one left out, such asqon a search ornewsletterwhen the credential reaches more than one. - The request body: not JSON, not the shape the operation reads,
a property it does not write, or a value of the wrong type, length
or format.
paramis absent here, since the body is not a parameter, and the message names the property. - The
Idempotency-Keyheader, on an operation that changes something: missing, or a value this API will not store. - An unrecognised
Commune-Version, which answers with its own code,invalid_version, because it is never fixed by changing the body.
- A query parameter: one the operation does not have, a value
outside its set, range or format (an unparseable cursor, an unknown
-
No credential was presented, or it is malformed, unknown, revoked or expired, or it is an access token minted for a different audience.
Every one of these answers identically, down to the wording and the headers, so a refusal never confirms that a string was once real.
-
The credential is allowed to do this but the newsletter's plan does not include it.
Two surfaces can answer it: insights, the engagement and metrics operations, which are the only reads Commune reserves the right to meter, and writing, every operation that changes something.
Every other read stays free on every plan, so a credential refused at one of these can still read everything else. The body names the plan the newsletter is on and the plans that would work.
One refusal is a feature of the paid plan rather than a charge for API access, and it answers whatever is metered: a newsletter whose plan does not include it may have one automation active at a time, so
POST /automations/{automation}/activateis refused while another is running. That one is also the only402a client can clear on its own, by pausing the automation that is running.This status is predictable and should not be how you discover it.
GET /newsletters/{newsletter}/entitlementsanswers the same question in advance, carrying the same plan list this puts inallowed_valuesand the same sentence it puts inmessage. Read it once at the start of a run rather than finding out in the middle of one. -
The credential is valid but is not allowed to do this. Two codes answer with this status, and
error.codesays which.insufficient_scope: it does not hold the permission. The operation needs, say,audience: readon the newsletter addressed, and this credential holds less than that there.allowed_valuescarries the permission that was needed, and the message says what the credential does hold on that newsletter, because a credential granted the wrong family and a credential belonging to somebody whose standing on the team has narrowed look identical without it. The answer can differ per newsletter: the same credential may be allowed here and refused on the next one it reaches.The same code answers an operation that needs the account permission from a credential that does not carry it. That permission is about the person a credential belongs to rather than about any newsletter, so nothing granted on a newsletter adds up to it. It is granted on the credential itself, when a key is minted or when an authorization asks for
account:read.And it answers a parameter the credential may send, but not with the value it sent: a filter a credential holding only
readpermissions may not use, or anexpandpath whose rows need a permission the operation does not.paramnames the parameter, andallowed_valuescarries what this credential may send instead, or is absent when it may send nothing there at all.forbidden: it may not act here at all. Either the credential does not reach the newsletter addressed, because it was never granted it or because the person it belongs to can no longer act on it, or it reaches no newsletter at all;paramisnewsletter, andGET /newsletterslists the ones it does reach. Or, onDELETE /api-keys/{key}, the credential named belongs to somebody else. Neither carriesallowed_values, because there is no value to send instead. -
No such resource, or the key is not allowed to know that it exists. Commune answers
404rather than403where distinguishing the two would leak the existence of private content. -
The request collided with something. On a write this is always the
Idempotency-Key, in one of two ways, and the message says which.Either the key was already used for a different request, which is refused rather than answered with the earlier request's result. Or an earlier request using the same key has not finished, or never reported an outcome, in which case this one was not run and the key becomes usable again shortly.
Nothing was changed by a request that answers this.
-
The request is well formed and every value in it is legal, and the state of what it addresses refuses it anyway. The message says what about that state is in the way.
-
Too many requests. Back off and retry after the interval named by the
Retry-Afterresponse header.One of the budgets in
RateLimit-Policyran out, and theRateLimit-*headers on this response say which and when it resets. -
Something failed inside Commune. The request may be retried.
curl \
--request POST 'https://api.usecommune.com/newsletters/9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e/forms' \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: 3f7c1a26-9b0e-4f5a-9a2c-2c8f1d6b4e77" \
--header "Commune-Version: 2026-08-26" \
--data '{
"name": "Checklist download",
"heading": "Get the launch checklist",
"button_label": "Send me the checklist",
"name_field": {
"mode": "optional"
},
"tag_ids": [
"aa11bb22-cc33-4d44-8e55-ff6677889900"
],
"after_confirm": {
"action": "redirect",
"url": "https://example.com/checklist/thanks"
}
}'
# Headers
Idempotency-Key: 3f7c1a26-9b0e-4f5a-9a2c-2c8f1d6b4e77
Commune-Version: 2026-08-26
# Payload
{
"name": "Checklist download",
"heading": "Get the launch checklist",
"button_label": "Send me the checklist",
"name_field": {
"mode": "optional"
},
"tag_ids": [
"aa11bb22-cc33-4d44-8e55-ff6677889900"
],
"after_confirm": {
"action": "redirect",
"url": "https://example.com/checklist/thanks"
}
}
{
"object": "form",
"id": "6c8f3d21-4e5a-4b6c-9d7e-8f9a0b1c2d3e",
"public_id": "m3q8r2",
"newsletter": {
"object": "newsletter",
"id": "7d3f1c02-58a1-4a4e-9a0b-2f6d1c9e4411"
},
"name": "Waitlist",
"heading": "Subscribe to The Weekly Build",
"description": "",
"button_label": "Subscribe",
"email_placeholder": "you@example.com",
"name_field": {
"mode": "off",
"label": "First name",
"placeholder": ""
},
"consent": {
"enabled": false,
"text": "I want to receive this newsletter and agree to the [privacy policy].",
"privacy_policy_url": null
},
"style": {
"layout": "stacked",
"background": "page",
"corners": "rounded",
"button_color": "#111111"
},
"tag_ids": [],
"after_signup": {
"action": "message",
"message": "Check your inbox and click the link to confirm your subscription.",
"url": null
},
"after_confirm": {
"action": "thank_you",
"url": null
},
"confirmation_email": {
"subject": null,
"body": null,
"button_label": null,
"footnote": null,
"button_color": null,
"corners": null,
"background": null
},
"embed": {
"script": "<script src=\"https://usecommune.com/f/m3q8r2.js\" async></script>",
"html": "<form action=\"https://usecommune.com/f/m3q8r2\" method=\"post\">\n <label for=\"commune-email-m3q8r2\">Email</label>\n <input id=\"commune-email-m3q8r2\" type=\"email\" name=\"email\" placeholder=\"you@example.com\" required>\n <!-- Keep this hidden field. It catches spam bots. -->\n <input type=\"text\" name=\"website\" tabindex=\"-1\" autocomplete=\"off\" aria-hidden=\"true\" style=\"display:none\">\n <button type=\"submit\">Subscribe</button>\n</form>",
"url": "https://usecommune.com/f/m3q8r2"
},
"subscriber_count": 0,
"subscribers_this_week": 0,
"created_at": "2026-11-15T10:00:00Z",
"updated_at": "2026-11-15T10:00:00Z"
}
{
"error": {
"code": "bad_request",
"message": "Newsletter not found.",
"param": "cursor",
"allowed_values": [
"subscribed",
"unsubscribed",
"bounced",
"complained",
"pending"
],
"request_id": "req_01j9c8h1q7m3n4p5r6s7t8u9v0",
"docs_url": "https://usecommune.dev/errors/not_found"
}
}
# Headers
WWW-Authenticate: string
# Payload
{
"error": {
"code": "bad_request",
"message": "Newsletter not found.",
"param": "cursor",
"allowed_values": [
"subscribed",
"unsubscribed",
"bounced",
"complained",
"pending"
],
"request_id": "req_01j9c8h1q7m3n4p5r6s7t8u9v0",
"docs_url": "https://usecommune.dev/errors/not_found"
}
}
{
"error": {
"code": "bad_request",
"message": "Newsletter not found.",
"param": "cursor",
"allowed_values": [
"subscribed",
"unsubscribed",
"bounced",
"complained",
"pending"
],
"request_id": "req_01j9c8h1q7m3n4p5r6s7t8u9v0",
"docs_url": "https://usecommune.dev/errors/not_found"
}
}
{
"error": {
"code": "bad_request",
"message": "Newsletter not found.",
"param": "cursor",
"allowed_values": [
"subscribed",
"unsubscribed",
"bounced",
"complained",
"pending"
],
"request_id": "req_01j9c8h1q7m3n4p5r6s7t8u9v0",
"docs_url": "https://usecommune.dev/errors/not_found"
}
}
{
"error": {
"code": "bad_request",
"message": "Newsletter not found.",
"param": "cursor",
"allowed_values": [
"subscribed",
"unsubscribed",
"bounced",
"complained",
"pending"
],
"request_id": "req_01j9c8h1q7m3n4p5r6s7t8u9v0",
"docs_url": "https://usecommune.dev/errors/not_found"
}
}
# Headers
Retry-After: 42
# Payload
{
"error": {
"code": "bad_request",
"message": "Newsletter not found.",
"param": "cursor",
"allowed_values": [
"subscribed",
"unsubscribed",
"bounced",
"complained",
"pending"
],
"request_id": "req_01j9c8h1q7m3n4p5r6s7t8u9v0",
"docs_url": "https://usecommune.dev/errors/not_found"
}
}
{
"error": {
"code": "bad_request",
"message": "Newsletter not found.",
"param": "cursor",
"allowed_values": [
"subscribed",
"unsubscribed",
"bounced",
"complained",
"pending"
],
"request_id": "req_01j9c8h1q7m3n4p5r6s7t8u9v0",
"docs_url": "https://usecommune.dev/errors/not_found"
}
}
# Headers
Retry-After: 42
# Payload
{
"error": {
"code": "bad_request",
"message": "Newsletter not found.",
"param": "cursor",
"allowed_values": [
"subscribed",
"unsubscribed",
"bounced",
"complained",
"pending"
],
"request_id": "req_01j9c8h1q7m3n4p5r6s7t8u9v0",
"docs_url": "https://usecommune.dev/errors/not_found"
}
}
{
"error": {
"code": "bad_request",
"message": "Newsletter not found.",
"param": "cursor",
"allowed_values": [
"subscribed",
"unsubscribed",
"bounced",
"complained",
"pending"
],
"request_id": "req_01j9c8h1q7m3n4p5r6s7t8u9v0",
"docs_url": "https://usecommune.dev/errors/not_found"
}
}