openemail forms

Returns one page of the sign-up forms the caller can reach, newest first, without their documents or settings. Paging is keyset: --limit takes 1 to 100 and defaults to 25, and nextCursor goes back as --cursor while hasMore is true.

Each form carries its status, url, the hosted page that shows it, subscribeUrl, where a plain HTML form posts, audienceIds, doubleOptIn, hasUnpublishedChanges and stats. stats is counted at the moment of the read: views of the hosted page and the embed while the form was live, submissions stored, added, the sign-ups added to the audiences, pending, the ones still to confirm, and lastSubmittedAt.

Read one with get for the draft document, the publishedDocument visitors see and the settings.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.

Makes a draft form and returns it whole, in the shape get returns. Its fields, copy and style come from document when you send one, from the starter named in starter when you do not, and otherwise from a one-field email form. settings changes any of the defaults, which add people to the default audience only, send no confirmation email, show the thank-you message from the copy and notify nobody.

A form takes no sign-ups until it is published. Send publish: true to put it live in the same call, or call publish later. Nothing is created when the document or settings break a rule.

Once it is live, share it with url, point a plain HTML <form method="post"> at subscribeUrl, embed it with the script at /embed/form.js on the OpenEmail web app, or sign people up from your own code with subscribe.

A designer builds a new sign-up form from a written brief, as Create with AI does on the Forms page of the app: it picks the fields, writes the copy and sets the look, then saves the form as a draft. Review it with get, change it with update or redesign, and put it live with publish.

Put everything the form must ask and say in brief: what it is for, the fields, the wording word for word, the colours and the tone. It spends one AI action and can take up to half a minute.

A designer applies written instructions to the draft of a form and leaves the rest alone, as Ask AI does in the form builder of the app: add, remove or reorder fields, make one required, rewrite or translate the copy, change colours or fonts. The change is saved to the draft, so a live form keeps showing its published version until publish.

Send the updatedAt you read as --expected-updated-at to refuse the change when somebody saved the form since. It spends one AI action and can take up to half a minute.

Returns the starters the console offers when somebody makes a form, as a plain array: blank, just the email field, then newsletter, waitlist, event, early-access and contact. Each carries its slug, name and description, and the documents are left out.

Pass a slug to create as starter to begin a form from it, or read it whole with getStarter to change its fields first.

Starters are part of the product rather than workspace data, so the answer is the same for every key and changes only when a release adds one.

Returns one starter in full: everything listStarters carries plus document, the fields, copy and style a form made from it begins with.

The document is there so a client can change it before it creates a form, rather than creating from the starter and updating afterwards. Send it, changed or not, as document on create.

Returns the whole form: the fields list carries with fresh stats, the draft document, the publishedDocument visitors see, which is null until the first publish, the settings and the named audiences sign-ups join.

hasUnpublishedChanges is true while the draft differs from what the live form shows. Settings take effect when they are saved, published or not.

For a form with doubleOptIn on, senderIssue says why confirmation emails cannot go out right now: missing when no senderAddress is set, not_sendable when the address cannot send, and not_allowed when its owner may not send as it. senderProblem says the same in a sentence. Both are null when confirmations can go out.

A partial update: a field you leave out keeps its stored value, and description: null clears the note. document replaces the draft whole, and a live form keeps showing its published copy until publish. settings is merged field by field, so { settings: { doubleOptIn: true, senderAddress: '[email protected]' } } changes those two and keeps the rest, and settings take effect at once, live form or not.

To avoid overwriting somebody else's change, read the form and send its updatedAt back as --expected-updated-at. A save made in between is then refused with 409 version_conflict rather than overwritten, and nothing is written.

Deletes the form and every submission stored on it. Its hosted page and embed stop working at once, and subscribe answers 404 form_not_found. The people it added stay in your contacts and audiences.

There is no undo. To stop sign-ups and keep the form, its submissions and its statistics, use pause.

Copies the draft document to publishedDocument and sets the form live, so the hosted page, the embed and subscribe show and take the new version from then on. Publishing a paused form opens it again. It takes no body.

The draft is checked first: the document and settings have to pass the rules create applies, and a double opt-in form needs a senderAddress that can send confirmations. An audience deleted since is skipped when people sign up. Submissions keep the answers, labels included, they were sent with, so publishing a change never rewrites them.

Closes a published form. Its hosted page and embed stay up and show the closed title and message from its copy, and subscribe answers 409 form_closed. Pausing a paused form changes nothing. It takes no body.

The form keeps its documents, settings, submissions and statistics, and resume opens it again with the version that was published last.

Opens a paused form again with the version that was published last, so it takes sign-ups once more. Changes made to the draft since stay in the draft: publish puts them live and opens the form in one call. Resuming a live form changes nothing. It takes no body.

Makes a new draft with the same document and settings, named after the original with copy added, such as Newsletter copy. Submissions and statistics are not copied, and the copy takes no sign-ups until you publish it. It takes no body.

An audience in the settings that the caller cannot reach is left out of the copy.

Returns the numbers behind a form's Analytics tab in one request: views, submissions and added over a window, cut into buckets, with totals and the conversion rate.

A view is one load of the hosted page or the embed while the form is live, and views are not deduplicated by visitor. A submission is counted when it is stored, waiting or added. added counts the sign-ups added to the audiences in the window, one per sign-up, dated when they joined, so a double opt-in sign-up can be submitted in one bucket and added in a later one.

series is sparse and oldest first: a bucket with nothing in it has no entry, so a chart must fill the gaps. grain sets the bucket width and the key shape, YYYY-MM-DD, YYYY-MM-DDTHH or YYYY-MM-DDTHH:MM, and --offset-minutes shifts the boundaries so days break where the reader's day does. The window starts at the beginning of its oldest bucket, reported as since, and ends now, reported as until.

Returns one page of the sign-ups a form has stored, newest first. Each keeps the answers as they were sent, labels included, so it still reads right after the form changes. Paging is keyset: --limit takes 1 to 100 and defaults to 25, and nextCursor, a submission id, goes back as --cursor while hasMore is true.

status is added once the person is a contact in the audiences, and pending while a double opt-in form waits for them to confirm. expired is true on a pending submission whose newest confirmation link, sent at sign-up or by a resend, is more than 7 days old: approve it with approveSubmission, or send a fresh link with resendConfirmation.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.

Returns one submission of the form: the address the person signed up with, lower cased, its status, every answer as it was sent, the audiences it joins, the page it came from, and when it was made and confirmed.

Deletes the submission. The person it added stays in your contacts and audiences, and a pending one can no longer be confirmed, since its link stops working. There is no undo.

Deletes many submissions of one form and answers with how many went. A repeated id counts once, and an id that names no submission of this form is skipped rather than refused. The people the submissions added stay in your contacts and audiences, and a pending one can no longer be confirmed.

Adds the person behind a pending submission to its audiences without waiting for them to open the confirmation email, for when you know them. The submission comes back added with confirmedAt set, and a form.confirmed webhook goes out with via set to approval. It takes no body.

It does not resubscribe someone who unsubscribed from one of the audiences, as their own confirmation would. A submission that is already added is returned as it is.

Emails the person behind a pending submission a new confirmation link from the form's senderAddress, with the form's current subject, message and button. The new link works for 7 days from now. It takes no body.

To protect the person, one address gets at most one confirmation from a form every ten minutes, and five a day across the workspace. A call within ten minutes of the last one, or past the fifth in a day, sends nothing and answers confirmationSent: false, and so does a call for a submission that is already added.

Posts a sign-up to a published form, as a visitor of its hosted page does, and answers with the outcome. It sends no credential, even from a client that holds one, so it works for any published form, in this workspace or another.

values holds the answers keyed by field key, and every form has the field keyed email. A text field takes a string, a number field a number or a numeric string, a checkbox or consent field true or false, a dropdown or single choice field one option value, and a multiple choice or audience field an array of option values. A key the form does not have is ignored, and a key starting oe_ is never stored as an answer.

On a double opt-in form outcome is pending: the person joins the audiences once they open a confirmation link, emailed after this answer unless this form emailed that address in the last ten minutes or the address has had five from this workspace today. Otherwise they join at once and outcome is added. Someone who unsubscribed from an audience stays unsubscribed unless they confirm through a double opt-in form.