Flomailr/Docs

Forms API

Create and manage signup forms. Each form has a submit URL you can post to from your own site. All routes need a bearer API key (see API Overview).

For the dashboard builder, embed code and display options, see Forms.

The form object

{
  "id": "clx...",
  "name": "Footer signup",
  "listId": "clx...",
  "fields": ["firstName"],
  "style": {},
  "successMessage": "Thanks! You're subscribed.",
  "createdAt": "2026-10-01T09:00:00.000Z",
  "updatedAt": "2026-10-01T09:00:00.000Z",
  "embedUrl": "https://flomailr.com/api/forms/clx.../submit"
}
  • fields lists the optional fields shown next to email, for example ["firstName", "lastName"].
  • style holds the form's look (button text and colours, background, corner radius). It is {} until the builder or a PATCH sets it.
  • listId is the list that new subscribers join. It can be null.
  • embedUrl is the URL the form submits to.

List forms

GET /api/v1/forms

Query: limit, after (see pagination).

Create a form

POST /api/v1/forms

{
  "name": "Footer signup",
  "listId": "clx...",
  "fields": ["firstName", "lastName"],
  "successMessage": "You're in."
}
  • name is required.
  • listId is optional. If given it must be a list in your workspace (404 otherwise).
  • fields defaults to ["firstName"]. Non-string entries are dropped.
  • successMessage defaults to "Thanks! You're subscribed."

Returns 201.

Get, update and delete

GET    /api/v1/forms/:id
PATCH  /api/v1/forms/:id
DELETE /api/v1/forms/:id

PATCH accepts name (cannot be empty), listId (a list id, or null to detach), fields (an array of strings), successMessage and style (an object). DELETE returns 204.

The API does not expose a form's display mode or trigger settings. Set those in the dashboard.

Submitting a form

The embedUrl is a public endpoint. It needs no API key, so a browser on your own site can post to it directly. It allows cross-origin requests.

POST /api/forms/:id/submit

Send JSON or a standard form post with email (required) and optionally firstName and lastName:

curl -X POST https://flomailr.com/api/forms/FORM_ID/submit \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com","firstName":"Ada"}'

A successful post returns the form's success message:

{ "ok": true, "message": "Thanks! You're subscribed." }
  • An invalid or missing email returns 400 with { "error": "..." }.
  • Each IP address can submit five times in ten minutes. After that the endpoint returns 429.
  • An address that has bounced returns 400 ("This email address cannot be re-subscribed."). Other suppressed addresses get the normal success message and are left unchanged.
  • Whether the new contact is subscribed straight away or must confirm by email first depends on the signup rules. See Double Opt-In.