--- title: "openemail forms" description: "Every command in this namespace, with its arguments, flags and examples." url: "https://openemail.uk/docs/cli/reference/forms" area: "CLI" category: "Reference" --- # openemail forms Every command in this namespace, with its arguments, flags and examples. ## Commands ### `openemail forms list` List one page of the sign-up forms in the workspace ```bash openemail forms list [flags] ``` 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 ` stops after that many items. - Scopes: `forms:read`. - Needs a sign-in. - Aliases: `ls`. **Flags** - `--limit ` (default `25`): Rows per page, a whole number from 1 to 100. The server defaults to 25. - `--cursor `: The `nextCursor` from the previous page, passed back exactly as it came. One the server cannot read is a 400 `invalid_cursor`. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** ```bash openemail forms list ``` With optional flags ```bash openemail forms list --limit 50 ``` Walk every page and stop after 100 items ```bash openemail forms list --all --max 100 ``` One JSON object per line when piped ```bash openemail forms list --all > forms.ndjson ``` Also available in: API [`GET /forms`](https://openemail.uk/docs/api/reference/forms#get-forms); SDK [`forms.list()`](https://openemail.uk/docs/sdk/reference/forms#list). ### `openemail forms create` Create a sign-up form ```bash openemail forms create --name [flags] openemail forms create --data [flags] ``` 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 `
` 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`. - Scopes: `forms:write`. - Needs a sign-in. - Aliases: `new`, `add`. **Flags** - `--name `: What the workspace calls the form, trimmed, 1 to 120 characters. Visitors never see it, and it need not be unique. Required, here or in `--data`. - `--description `: A note for the workspace, at most 500 characters. Visitors never see it. - `--starter `: Begin from a starter: `blank`, `newsletter`, `waitlist`, `event`, `early-access` or `contact`. Ignored when `document` is sent. - `--document `: The whole form, `fields`, `copy` and `style`, in the shape `get` and `getStarter` return. Every field carries all 15 of its keys, with null for the ones it does not use, and a document needs exactly one email field, keyed `email` and required, and its field keys and ids must be unique. Leave it out to use `starter` or a one-field email form. JSON shaped as `FormDocument`, inline or from a file with @path. - `--settings-audience-ids ` (repeatable): The audiences every sign-up joins, at most 20 ids such as `aud_9f2c4b7e1a0d63d84c5f2e7b`. Every contact is in the default audience as well, so an empty list adds people there only. An id that is not an audience the caller can reach is a 404 `audience_not_found`. - `--settings-double-opt-in`: Email each person a confirmation link and add them only once they open it. Defaults to false. True needs `senderAddress`. - `--settings-sender-address `: The workspace address confirmation emails come from, required for `doubleOptIn`. It has to be an address the caller may send as, or the call is refused with 422 `form_sender_refused`. - `--settings-confirm-subject `: The subject of the confirmation email, 1 to 200 characters. Defaults to Please confirm your subscription. - `--settings-confirm-message `: The text of the confirmation email above its button, at most 2000 characters. - `--settings-confirm-button `: The label of the confirmation button, 1 to 60 characters. Defaults to Confirm my subscription. - `--settings-success-action `: What a person sees after signing up: `message`, the thank-you copy in the document, which is the default, or `redirect`, which sends them to `redirectUrl`. - `--settings-redirect-url `: The http or https page `redirect` sends people to, at most 2000 characters. Required while `successAction` is `redirect`. - `--settings-notify-addresses ` (repeatable): Up to 10 addresses of this workspace that get an email about each sign-up. Each has to be one the caller can read, or the call is refused with 422 `invalid_form`. - `--publish`: Publish in the same call, so the form takes sign-ups at once. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** The required values only ```bash openemail forms create --name Newsletter ``` With optional flags ```bash openemail forms create --name Newsletter --starter newsletter --settings-audience-ids aud_9f2c4b7e1a0d63d84c5f2e7b --publish ``` Read the whole body from a JSON file ```bash openemail forms create --data @form.json ``` Also available in: API [`POST /forms`](https://openemail.uk/docs/api/reference/forms#post-forms); SDK [`forms.create()`](https://openemail.uk/docs/sdk/reference/forms#create). ### `openemail forms design` Design a form from a brief ```bash openemail forms design --brief [flags] openemail forms design --data [flags] ``` 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. - Scopes: `forms:write`. - Needs a sign-in. **Flags** - `--brief `: Everything the form must ask and say, up to 4,000 characters. Required, here or in `--data`. - `--name `: A short name for the form, up to 120 characters. Left out, the designer names it. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** ```bash openemail forms design --brief 'A waitlist for our beta: email, first name and company, with a short line on what joining means. Dark green button that says Join the waitlist.' ``` Read the whole body from a JSON file ```bash openemail forms design --data @form.json ``` Also available in: API [`POST /forms/design`](https://openemail.uk/docs/api/reference/forms#post-forms-design); SDK [`forms.design()`](https://openemail.uk/docs/sdk/reference/forms#design). ### `openemail forms redesign` Change a form’s design from instructions ```bash openemail forms redesign --instructions [flags] openemail forms redesign --data [flags] ``` 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. - Scopes: `forms:write`. - Needs a sign-in. **Arguments** - `` (required): Form id such as `frm_8d2f6a1c9b3e47d0a5f1c2e9`. **Flags** - `--instructions `: What to change, with every detail, up to 4,000 characters. Required, here or in `--data`. - `--expected-updated-at `: The `updatedAt` you read, as it came. When the form was saved since, nothing is written and the answer is 409 `version_conflict`. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** ```bash openemail forms redesign frm_8d2f6a1c9b3e47d0a5f1c2e9 --instructions 'Add a required company field after the name, and make the button say Join.' ``` Read the whole body from a JSON file ```bash openemail forms redesign frm_8d2f6a1c9b3e47d0a5f1c2e9 --data @form.json ``` Also available in: API [`POST /forms/{id}/redesign`](https://openemail.uk/docs/api/reference/forms#post-forms-id-redesign); SDK [`forms.redesign()`](https://openemail.uk/docs/sdk/reference/forms#redesign). ### `openemail forms list-starters` List the starting points for a new form ```bash openemail forms list-starters [flags] ``` 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. - Scopes: `forms:read`. - Needs a sign-in. **Examples** ```bash openemail forms list-starters ``` Print the raw JSON ```bash openemail forms list-starters --json ``` Also available in: API [`GET /forms/starters`](https://openemail.uk/docs/api/reference/forms#get-forms-starters); SDK [`forms.listStarters()`](https://openemail.uk/docs/sdk/reference/forms#listStarters). ### `openemail forms get-starter` Retrieve one starter with its document ```bash openemail forms get-starter [flags] ``` 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`. - Scopes: `forms:read`. - Needs a sign-in. **Arguments** - `` (required): A starter slug from `listStarters`: `blank`, `newsletter`, `waitlist`, `event`, `early-access` or `contact`. **Examples** ```bash openemail forms get-starter newsletter ``` Print the raw JSON ```bash openemail forms get-starter newsletter --json ``` Also available in: API [`GET /forms/starters/{slug}`](https://openemail.uk/docs/api/reference/forms#get-forms-starters-slug); SDK [`forms.getStarter()`](https://openemail.uk/docs/sdk/reference/forms#getStarter). ### `openemail forms get` Retrieve a form with its documents and settings ```bash openemail forms get [flags] ``` 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. - Scopes: `forms:read`. - Needs a sign-in. - Aliases: `show`, `view`. **Arguments** - `` (required): Form id such as `frm_8d2f6a1c9b3e47d0a5f1c2e9`. **Examples** ```bash openemail forms get frm_8d2f6a1c9b3e47d0a5f1c2e9 ``` Print the raw JSON ```bash openemail forms get frm_8d2f6a1c9b3e47d0a5f1c2e9 --json ``` Also available in: API [`GET /forms/{id}`](https://openemail.uk/docs/api/reference/forms#get-forms-id); SDK [`forms.get()`](https://openemail.uk/docs/sdk/reference/forms#get). ### `openemail forms update` Change a form's name, document or settings ```bash openemail forms update [flags] ``` 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: 'hello@acme.com' } }` 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. - Scopes: `forms:write`. - Needs a sign-in. - Aliases: `edit`. **Arguments** - `` (required): Form id such as `frm_8d2f6a1c9b3e47d0a5f1c2e9`. **Flags** - `--name `: New name, trimmed, 1 to 120 characters. - `--description `: New note, at most 500 characters. Null clears it. - `--document `: The new draft, whole, in the shape `get` returns. Every field carries all 15 of its keys, and a document needs exactly one email field, keyed `email` and required, and its field keys and ids must be unique. JSON shaped as `FormDocument`, inline or from a file with @path. - `--settings-audience-ids ` (repeatable): The new list of audiences every sign-up joins, replacing the old one, at most 20 ids such as `aud_9f2c4b7e1a0d63d84c5f2e7b`. Every contact is in the default audience as well, so an empty list adds people there only. A new id that is not an audience the caller can reach is a 404 `audience_not_found`. - `--settings-double-opt-in`: Email each person a confirmation link and add them only once they open it. True needs `senderAddress`. - `--settings-sender-address `: The workspace address confirmation emails come from, required for `doubleOptIn`. It has to be an address the caller may send as, or the call is refused with 422 `form_sender_refused`. - `--settings-confirm-subject `: The subject of the confirmation email, 1 to 200 characters. - `--settings-confirm-message `: The text of the confirmation email above its button, at most 2000 characters. - `--settings-confirm-button `: The label of the confirmation button, 1 to 60 characters. - `--settings-success-action `: What a person sees after signing up: `message`, the thank-you copy in the document or `redirect`, which sends them to `redirectUrl`. - `--settings-redirect-url `: The http or https page `redirect` sends people to, at most 2000 characters. Required while `successAction` is `redirect`. - `--settings-notify-addresses ` (repeatable): Up to 10 addresses of this workspace that get an email about each sign-up, replacing the old list. Each has to be one the caller can read, or the call is refused with 422 `invalid_form`. - `--expected-updated-at `: The `updatedAt` you read, as it came. When the form was saved since, nothing is written and the answer is 409 `version_conflict`. - `--data `: The whole `patch` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** With optional flags ```bash openemail forms update frm_8d2f6a1c9b3e47d0a5f1c2e9 --settings-double-opt-in --settings-sender-address hello@acme.com ``` Print the raw JSON ```bash openemail forms update frm_8d2f6a1c9b3e47d0a5f1c2e9 --settings-double-opt-in --settings-sender-address hello@acme.com --json ``` Also available in: API [`PATCH /forms/{id}`](https://openemail.uk/docs/api/reference/forms#patch-forms-id); SDK [`forms.update()`](https://openemail.uk/docs/sdk/reference/forms#update). ### `openemail forms delete` Delete a form and every submission it holds ```bash openemail forms delete [flags] ``` 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`. - Scopes: `forms:write`. - Needs a sign-in. - Asks you to confirm. - Aliases: `rm`, `del`, `remove`. **Arguments** - `` (required): Form id such as `frm_8d2f6a1c9b3e47d0a5f1c2e9`. **Examples** ```bash openemail forms delete frm_8d2f6a1c9b3e47d0a5f1c2e9 ``` Skip the confirmation, for scripts ```bash openemail forms delete frm_8d2f6a1c9b3e47d0a5f1c2e9 --yes ``` Also available in: API [`DELETE /forms/{id}`](https://openemail.uk/docs/api/reference/forms#delete-forms-id); SDK [`forms.delete()`](https://openemail.uk/docs/sdk/reference/forms#delete). ### `openemail forms publish` Put the draft of a form live ```bash openemail forms publish [flags] ``` 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. - Scopes: `forms:write`. - Needs a sign-in. **Arguments** - `` (required): Form id such as `frm_8d2f6a1c9b3e47d0a5f1c2e9`. **Examples** ```bash openemail forms publish frm_8d2f6a1c9b3e47d0a5f1c2e9 ``` Print the raw JSON ```bash openemail forms publish frm_8d2f6a1c9b3e47d0a5f1c2e9 --json ``` Also available in: API [`POST /forms/{id}/publish`](https://openemail.uk/docs/api/reference/forms#post-forms-id-publish); SDK [`forms.publish()`](https://openemail.uk/docs/sdk/reference/forms#publish). ### `openemail forms pause` Stop a published form taking sign-ups ```bash openemail forms pause [flags] ``` 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. - Scopes: `forms:write`. - Needs a sign-in. **Arguments** - `` (required): Form id such as `frm_8d2f6a1c9b3e47d0a5f1c2e9`. **Examples** ```bash openemail forms pause frm_8d2f6a1c9b3e47d0a5f1c2e9 ``` Print the raw JSON ```bash openemail forms pause frm_8d2f6a1c9b3e47d0a5f1c2e9 --json ``` Also available in: API [`POST /forms/{id}/pause`](https://openemail.uk/docs/api/reference/forms#post-forms-id-pause); SDK [`forms.pause()`](https://openemail.uk/docs/sdk/reference/forms#pause). ### `openemail forms resume` Open a paused form again ```bash openemail forms resume [flags] ``` 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. - Scopes: `forms:write`. - Needs a sign-in. **Arguments** - `` (required): Form id such as `frm_8d2f6a1c9b3e47d0a5f1c2e9`. **Examples** ```bash openemail forms resume frm_8d2f6a1c9b3e47d0a5f1c2e9 ``` Print the raw JSON ```bash openemail forms resume frm_8d2f6a1c9b3e47d0a5f1c2e9 --json ``` Also available in: API [`POST /forms/{id}/resume`](https://openemail.uk/docs/api/reference/forms#post-forms-id-resume); SDK [`forms.resume()`](https://openemail.uk/docs/sdk/reference/forms#resume). ### `openemail forms duplicate` Copy a form into a new draft ```bash openemail forms duplicate [flags] ``` 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. - Scopes: `forms:write`. - Needs a sign-in. **Arguments** - `` (required): Form id such as `frm_8d2f6a1c9b3e47d0a5f1c2e9`. **Examples** ```bash openemail forms duplicate frm_8d2f6a1c9b3e47d0a5f1c2e9 ``` Print the raw JSON ```bash openemail forms duplicate frm_8d2f6a1c9b3e47d0a5f1c2e9 --json ``` Also available in: API [`POST /forms/{id}/duplicate`](https://openemail.uk/docs/api/reference/forms#post-forms-id-duplicate); SDK [`forms.duplicate()`](https://openemail.uk/docs/sdk/reference/forms#duplicate). ### `openemail forms analytics` Read views, sign-ups and people added over a window ```bash openemail forms analytics [flags] ``` 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`. - Scopes: `forms:read`. - Needs a sign-in. **Arguments** - `` (required): Form id such as `frm_8d2f6a1c9b3e47d0a5f1c2e9`. **Flags** - `--days ` (default `30`): How far back to look, from 1 to 1095, defaulting to 30. - `--minutes `: The window in minutes, from 1 to 1576800, which wins over `days` when both are sent. - `--grain ` (default `"day"`): Bucket width: `minute`, `hour` or `day`, defaulting to `day`. - `--offset-minutes ` (default `0`): Minutes east of UTC to cut the buckets in, from -840 to 840, defaulting to 0. Pass `-new Date().getTimezoneOffset()` for the local zone. **Examples** The required values only ```bash openemail forms analytics frm_8d2f6a1c9b3e47d0a5f1c2e9 ``` With optional flags ```bash openemail forms analytics frm_8d2f6a1c9b3e47d0a5f1c2e9 --days 90 --grain day ``` Print the raw JSON ```bash openemail forms analytics frm_8d2f6a1c9b3e47d0a5f1c2e9 --json ``` Also available in: API [`GET /forms/{id}/analytics`](https://openemail.uk/docs/api/reference/forms#get-forms-id-analytics); SDK [`forms.analytics()`](https://openemail.uk/docs/sdk/reference/forms#analytics). ### `openemail forms list-submissions` List one page of a form's submissions ```bash openemail forms list-submissions [flags] ``` 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 ` stops after that many items. - Scopes: `forms:read`. - Needs a sign-in. **Arguments** - `` (required): Form id such as `frm_8d2f6a1c9b3e47d0a5f1c2e9`. **Flags** - `--limit ` (default `25`): Rows per page, a whole number from 1 to 100. The server defaults to 25. - `--cursor `: The `nextCursor` from the previous page, a submission id of this form. One that names no submission of this form is a 400 `invalid_cursor`. - `--q `: Only submissions whose email address contains this text, ignoring case, at most 200 characters. - `--status `: Only `pending` or only `added` submissions. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** The required values only ```bash openemail forms list-submissions frm_8d2f6a1c9b3e47d0a5f1c2e9 ``` With optional flags ```bash openemail forms list-submissions frm_8d2f6a1c9b3e47d0a5f1c2e9 --status pending ``` Walk every page and stop after 100 items ```bash openemail forms list-submissions frm_8d2f6a1c9b3e47d0a5f1c2e9 --all --max 100 ``` One JSON object per line when piped ```bash openemail forms list-submissions frm_8d2f6a1c9b3e47d0a5f1c2e9 --all > forms.ndjson ``` Also available in: API [`GET /forms/{id}/submissions`](https://openemail.uk/docs/api/reference/forms#get-forms-id-submissions); SDK [`forms.listSubmissions()`](https://openemail.uk/docs/sdk/reference/forms#listSubmissions). ### `openemail forms get-submission` Retrieve one submission with every answer ```bash openemail forms get-submission [flags] ``` 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. - Scopes: `forms:read`. - Needs a sign-in. **Arguments** - `` (required): Form id such as `frm_8d2f6a1c9b3e47d0a5f1c2e9`. - `` (required): Submission id such as `fsb_3c7e1a9f0b2d4c6e8a1f3b5d`, from `listSubmissions` or a `form.submitted` webhook. **Examples** ```bash openemail forms get-submission frm_8d2f6a1c9b3e47d0a5f1c2e9 fsb_3c7e1a9f0b2d4c6e8a1f3b5d ``` Print the raw JSON ```bash openemail forms get-submission frm_8d2f6a1c9b3e47d0a5f1c2e9 fsb_3c7e1a9f0b2d4c6e8a1f3b5d --json ``` Also available in: API [`GET /forms/{id}/submissions/{submissionId}`](https://openemail.uk/docs/api/reference/forms#get-forms-id-submissions-submissionid); SDK [`forms.getSubmission()`](https://openemail.uk/docs/sdk/reference/forms#getSubmission). ### `openemail forms delete-submission` Delete one submission of a form ```bash openemail forms delete-submission [flags] ``` 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. - Scopes: `forms:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): Form id such as `frm_8d2f6a1c9b3e47d0a5f1c2e9`. - `` (required): Submission id such as `fsb_3c7e1a9f0b2d4c6e8a1f3b5d`, from `listSubmissions` or a `form.submitted` webhook. **Examples** ```bash openemail forms delete-submission frm_8d2f6a1c9b3e47d0a5f1c2e9 fsb_3c7e1a9f0b2d4c6e8a1f3b5d ``` Skip the confirmation, for scripts ```bash openemail forms delete-submission frm_8d2f6a1c9b3e47d0a5f1c2e9 fsb_3c7e1a9f0b2d4c6e8a1f3b5d --yes ``` Also available in: API [`DELETE /forms/{id}/submissions/{submissionId}`](https://openemail.uk/docs/api/reference/forms#delete-forms-id-submissions-submissionid); SDK [`forms.deleteSubmission()`](https://openemail.uk/docs/sdk/reference/forms#deleteSubmission). ### `openemail forms delete-submissions` Delete up to 200 submissions of a form in one call ```bash openemail forms delete-submissions [flags] ``` 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. - Scopes: `forms:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): Form id such as `frm_8d2f6a1c9b3e47d0a5f1c2e9`. - `` (required): From 1 to 200 submission ids of this form, such as `fsb_3c7e1a9f0b2d4c6e8a1f3b5d`, sent as `ids`. An empty list or more than 200 is a 422 `invalid_parameter` on `ids`. **Examples** ```bash openemail forms delete-submissions frm_8d2f6a1c9b3e47d0a5f1c2e9 fsb_3c7e1a9f0b2d4c6e8a1f3b5d ``` Skip the confirmation, for scripts ```bash openemail forms delete-submissions frm_8d2f6a1c9b3e47d0a5f1c2e9 fsb_3c7e1a9f0b2d4c6e8a1f3b5d --yes ``` Also available in: API [`POST /forms/{id}/submissions/batch-remove`](https://openemail.uk/docs/api/reference/forms#post-forms-id-submissions-batch-remove); SDK [`forms.deleteSubmissions()`](https://openemail.uk/docs/sdk/reference/forms#deleteSubmissions). ### `openemail forms approve-submission` Add a waiting sign-up without its confirmation ```bash openemail forms approve-submission [flags] ``` 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. - Scopes: `forms:write`, `contacts:write`. - Needs a sign-in. **Arguments** - `` (required): Form id such as `frm_8d2f6a1c9b3e47d0a5f1c2e9`. - `` (required): Submission id such as `fsb_3c7e1a9f0b2d4c6e8a1f3b5d`, from `listSubmissions` or a `form.submitted` webhook. **Examples** ```bash openemail forms approve-submission frm_8d2f6a1c9b3e47d0a5f1c2e9 fsb_3c7e1a9f0b2d4c6e8a1f3b5d ``` Print the raw JSON ```bash openemail forms approve-submission frm_8d2f6a1c9b3e47d0a5f1c2e9 fsb_3c7e1a9f0b2d4c6e8a1f3b5d --json ``` Also available in: API [`POST /forms/{id}/submissions/{submissionId}/approve`](https://openemail.uk/docs/api/reference/forms#post-forms-id-submissions-submissionid-approve); SDK [`forms.approveSubmission()`](https://openemail.uk/docs/sdk/reference/forms#approveSubmission). ### `openemail forms resend-confirmation` Email a waiting sign-up a fresh confirmation link ```bash openemail forms resend-confirmation [flags] ``` 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. - Scopes: `forms:write`, `emails:send`. - Needs a sign-in. **Arguments** - `` (required): Form id such as `frm_8d2f6a1c9b3e47d0a5f1c2e9`. - `` (required): Submission id such as `fsb_3c7e1a9f0b2d4c6e8a1f3b5d`, from `listSubmissions` or a `form.submitted` webhook. **Examples** ```bash openemail forms resend-confirmation frm_8d2f6a1c9b3e47d0a5f1c2e9 fsb_3c7e1a9f0b2d4c6e8a1f3b5d ``` Print the raw JSON ```bash openemail forms resend-confirmation frm_8d2f6a1c9b3e47d0a5f1c2e9 fsb_3c7e1a9f0b2d4c6e8a1f3b5d --json ``` Also available in: API [`POST /forms/{id}/submissions/{submissionId}/resend`](https://openemail.uk/docs/api/reference/forms#post-forms-id-submissions-submissionid-resend); SDK [`forms.resendConfirmation()`](https://openemail.uk/docs/sdk/reference/forms#resendConfirmation). ### `openemail forms subscribe` Sign someone up through a published form ```bash openemail forms subscribe --email [flags] openemail forms subscribe --data [flags] ``` 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. - No sign-in needed. **Arguments** - `` (required): The id of a published form, such as `frm_8d2f6a1c9b3e47d0a5f1c2e9`. **Flags** - `--email `: The address to sign up, the answer to the email field every form has. Required, here or in `--data`. - `--oe-source `: The page the form was filled in on, stored as its origin and path, at most 500 characters. A call from a server has no `Referer` to fall back on, so pass it to keep the source. - `--data `: The whole `values` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** The required values only ```bash openemail forms subscribe frm_8d2f6a1c9b3e47d0a5f1c2e9 --email ada@example.com ``` With optional flags ```bash openemail forms subscribe frm_8d2f6a1c9b3e47d0a5f1c2e9 --email ada@example.com --oe-source https://acme.com/launch ``` Read the whole body from a JSON file ```bash openemail forms subscribe frm_8d2f6a1c9b3e47d0a5f1c2e9 --data @form.json ``` Also available in: API [`POST /subscribe/{formId}`](https://openemail.uk/docs/api/reference/forms#post-subscribe-formid); SDK [`forms.subscribe()`](https://openemail.uk/docs/sdk/reference/forms#subscribe).