CLI

nextmail forms

Every command in this namespace, with its arguments, flags and examples.

Commands

Forms that add the people who fill them in to your audiences, with an optional confirmation email first: make them from a starter or your own fields, publish, pause and copy them, read their analytics, manage what people sent, and sign someone up without a credential.

Every command here also takes the global flags, such as --json, --profile and --dry-run. See the global flags

`nextmail forms list`

List one page of the sign-up forms in the workspace

forms:readNeeds a sign-inAliasesls

Usage

nextmail 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 <n> stops after that many items.

Flags

--limit <n>: Rows per page, a whole number from 1 to 100. The server defaults to 25.
Default25
--cursor <value>: 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 <n>: Stop after this many items. Implies --all.
--ndjson: Print every item as one JSON object per line. Implies --all

Examples

nextmail forms list

With optional flags

nextmail forms list --limit 50

Walk every page and stop after 100 items

nextmail forms list --all --max 100

One JSON object per line when piped

nextmail forms list --all > forms.ndjson

Also available in

API: GET /forms
TypeScript: nextmail.forms.list()
Python: forms.list()
Ruby: forms.list
PHP: forms->list
Go: Forms.List
Java: forms().list
C#: Forms.ListAsync

`nextmail forms create`

Create a sign-up form

forms:writeNeeds a sign-inAliasesnewadd

Usage

nextmail forms create --name <value> [flags]
nextmail forms create --data <json|@file|-> [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 <form method="post"> at subscribeUrl, embed it with the script at /embed/form.js on the Nextmail web app, or sign people up from your own code with subscribe.

Flags

--name <value>: 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 <value>: A note for the workspace, at most 500 characters. Visitors never see it.
--starter <value>: Begin from a starter: blank, newsletter, waitlist, event, early-access or contact. Ignored when document is sent.
--document <json|@file|->: The whole form, fields, copy and style, in the shape get and getStarter return. Every field carries all 15 of its keys, and saveAs for one whose answer fills a custom field, 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 <a,b>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 true. A draft may wait for its senderAddress, but publishing needs one and emails:send, so send false for a form that adds people at once.
--settings-sender-address <value>: The workspace address confirmation emails come from, required to publish with doubleOptIn. Left out while doubleOptIn is left out too, a key that holds emails:send gets the first address it may send as. It has to be an address the caller may send as, or the call is refused with 422 form_sender_refused.
--settings-confirm-subject <value>: The subject of the confirmation email, 1 to 200 characters. Defaults to Please confirm your subscription.
--settings-confirm-message <value>: The text of the confirmation email above its button, at most 2000 characters.
--settings-confirm-button <value>: The label of the confirmation button, 1 to 60 characters. Defaults to Confirm my subscription.
--settings-success-action <value>: 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 <value>: The http or https page redirect sends people to, at most 2000 characters. Required while successAction is redirect.
--settings-notify-addresses <a,b>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.
--settings-allowed-sites <a,b>Repeatable: Up to 20 sites that may show the form or post to it: a domain (example.com), every subdomain of one (*.example.com), or either with a path (example.com/pricing, example.com/blog/*). A scheme or a port narrows it further (https://example.com, localhost:3000). An empty list, the default, allows any site, and the form's own page always works. An entry that is not written this way is 422 invalid_form.
--publish: Publish in the same call, so the form takes sign-ups at once.
--data <json|@file|->: The whole body as JSON, inline, from a file with @path, or - for standard input. Flags override its keys.

Examples

The required values only

nextmail forms create --name Newsletter

With optional flags

nextmail forms create --name Newsletter --starter newsletter --settings-audience-ids aud_9f2c4b7e1a0d63d84c5f2e7b --publish

Read the whole body from a JSON file

nextmail forms create --data @form.json

Also available in

API: POST /forms
TypeScript: nextmail.forms.create()
Python: forms.create()
Ruby: forms.create
PHP: forms->create
Go: Forms.Create
Java: forms().create
C#: Forms.CreateAsync

`nextmail forms design`

Design a form from a brief

forms:writeNeeds a sign-in

Usage

nextmail forms design --brief <value> [flags]
nextmail forms design --data <json|@file|-> [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.

Flags

--brief <value>: Everything the form must ask and say, up to 4,000 characters. Required, here or in --data.
--name <value>: A short name for the form, up to 120 characters. Left out, the designer names it.
--data <json|@file|->: The whole body as JSON, inline, from a file with @path, or - for standard input. Flags override its keys.

Examples

nextmail 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

nextmail forms design --data @form.json

Also available in

API: POST /forms/design
TypeScript: nextmail.forms.design()
Python: forms.design()
Ruby: forms.design
PHP: forms->design
Go: Forms.Design
Java: forms().design
C#: Forms.DesignAsync

`nextmail forms redesign`

Change a form’s design from instructions

forms:writeNeeds a sign-in

Usage

nextmail forms redesign <id> --instructions <value> [flags]
nextmail forms redesign <id> --data <json|@file|-> [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.

Arguments

<id>Required: Form id such as frm_8d2f6a1c9b3e47d0a5f1c2e9.

Flags

--instructions <value>: What to change, with every detail, up to 4,000 characters. Required, here or in --data.
--expected-updated-at <value>: The updatedAt you read, as it came. When the form was saved since, nothing is written and the answer is 409 version_conflict.
--data <json|@file|->: The whole body as JSON, inline, from a file with @path, or - for standard input. Flags override its keys.

Examples

nextmail 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

nextmail forms redesign frm_8d2f6a1c9b3e47d0a5f1c2e9 --data @form.json

Also available in

API: POST /forms/{id}/redesign
TypeScript: nextmail.forms.redesign()
Python: forms.redesign()
Ruby: forms.redesign
PHP: forms->redesign
Go: Forms.Redesign
Java: forms().redesign
C#: Forms.RedesignAsync

`nextmail forms list-starters`

List the starting points for a new form

forms:readNeeds a sign-in

Usage

nextmail 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.

Examples

nextmail forms list-starters

Print the raw JSON

nextmail forms list-starters --json

Also available in

API: GET /forms/starters
TypeScript: nextmail.forms.listStarters()
Python: forms.list_starters()
Ruby: forms.list_starters
PHP: forms->listStarters
Go: Forms.ListStarters
Java: forms().listStarters
C#: Forms.ListStartersAsync

`nextmail forms get-starter`

Retrieve one starter with its document

forms:readNeeds a sign-in

Usage

nextmail forms get-starter <slug> [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.

Arguments

<slug>Required: A starter slug from listStarters: blank, newsletter, waitlist, event, early-access or contact.

Examples

nextmail forms get-starter newsletter

Print the raw JSON

nextmail forms get-starter newsletter --json

Also available in

API: GET /forms/starters/{slug}
TypeScript: nextmail.forms.getStarter()
Python: forms.get_starter()
Ruby: forms.get_starter
PHP: forms->getStarter
Go: Forms.GetStarter
Java: forms().getStarter
C#: Forms.GetStarterAsync

`nextmail forms get`

Retrieve a form with its documents and settings

forms:readNeeds a sign-inAliasesshowview

Usage

nextmail forms get <id> [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.

Arguments

<id>Required: Form id such as frm_8d2f6a1c9b3e47d0a5f1c2e9.

Examples

nextmail forms get frm_8d2f6a1c9b3e47d0a5f1c2e9

Print the raw JSON

nextmail forms get frm_8d2f6a1c9b3e47d0a5f1c2e9 --json

Also available in

API: GET /forms/{id}
TypeScript: nextmail.forms.get()
Python: forms.get()
Ruby: forms.get
PHP: forms->get
Go: Forms.Get
Java: forms().get
C#: Forms.GetAsync

`nextmail forms update`

Change a form's name, document or settings

forms:writeNeeds a sign-inAliasesedit

Usage

nextmail forms update <id> [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.

Arguments

<id>Required: Form id such as frm_8d2f6a1c9b3e47d0a5f1c2e9.

Flags

--name <value>: New name, trimmed, 1 to 120 characters.
--description <value>: New note, at most 500 characters. Null clears it.
--document <json|@file|->: The new draft, whole, in the shape get returns. Every field carries all 15 of its keys, and saveAs for one whose answer fills a custom field, 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 <a,b>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 <value>: 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 <value>: The subject of the confirmation email, 1 to 200 characters.
--settings-confirm-message <value>: The text of the confirmation email above its button, at most 2000 characters.
--settings-confirm-button <value>: The label of the confirmation button, 1 to 60 characters.
--settings-success-action <value>: 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 <value>: The http or https page redirect sends people to, at most 2000 characters. Required while successAction is redirect.
--settings-notify-addresses <a,b>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.
--settings-allowed-sites <a,b>Repeatable: The sites that may show the form or post to it, replacing the old list, at most 20: a domain (example.com), every subdomain of one (*.example.com), or either with a path (example.com/pricing, example.com/blog/*). An empty list allows any site again. An entry that is not written this way is 422 invalid_form.
--expected-updated-at <value>: The updatedAt you read, as it came. When the form was saved since, nothing is written and the answer is 409 version_conflict.
--data <json|@file|->: The whole patch as JSON, inline, from a file with @path, or - for standard input. Flags override its keys.

Examples

With optional flags

nextmail forms update frm_8d2f6a1c9b3e47d0a5f1c2e9 --settings-double-opt-in --settings-sender-address hello@acme.com

Print the raw JSON

nextmail forms update frm_8d2f6a1c9b3e47d0a5f1c2e9 --settings-double-opt-in --settings-sender-address hello@acme.com --json

Also available in

API: PATCH /forms/{id}
TypeScript: nextmail.forms.update()
Python: forms.update()
Ruby: forms.update
PHP: forms->update
Go: Forms.Update
Java: forms().update
C#: Forms.UpdateAsync

`nextmail forms delete`

Delete a form and every submission it holds

forms:writeNeeds a sign-in

Asks you to confirm

Aliasesrmdelremove

Usage

nextmail forms delete <id> [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.

Arguments

<id>Required: Form id such as frm_8d2f6a1c9b3e47d0a5f1c2e9.

Examples

nextmail forms delete frm_8d2f6a1c9b3e47d0a5f1c2e9

Skip the confirmation, for scripts

nextmail forms delete frm_8d2f6a1c9b3e47d0a5f1c2e9 --yes

Also available in

API: DELETE /forms/{id}
TypeScript: nextmail.forms.delete()
Python: forms.delete()
Ruby: forms.delete
PHP: forms->delete
Go: Forms.Delete
Java: forms().delete
C#: Forms.DeleteAsync

`nextmail forms publish`

Put the draft of a form live

forms:writeNeeds a sign-in

Usage

nextmail forms publish <id> [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.

Arguments

<id>Required: Form id such as frm_8d2f6a1c9b3e47d0a5f1c2e9.

Examples

nextmail forms publish frm_8d2f6a1c9b3e47d0a5f1c2e9

Print the raw JSON

nextmail forms publish frm_8d2f6a1c9b3e47d0a5f1c2e9 --json

Also available in

API: POST /forms/{id}/publish
TypeScript: nextmail.forms.publish()
Python: forms.publish()
Ruby: forms.publish
PHP: forms->publish
Go: Forms.Publish
Java: forms().publish
C#: Forms.PublishAsync

`nextmail forms pause`

Stop a published form taking sign-ups

forms:writeNeeds a sign-in

Usage

nextmail forms pause <id> [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.

Arguments

<id>Required: Form id such as frm_8d2f6a1c9b3e47d0a5f1c2e9.

Examples

nextmail forms pause frm_8d2f6a1c9b3e47d0a5f1c2e9

Print the raw JSON

nextmail forms pause frm_8d2f6a1c9b3e47d0a5f1c2e9 --json

Also available in

API: POST /forms/{id}/pause
TypeScript: nextmail.forms.pause()
Python: forms.pause()
Ruby: forms.pause
PHP: forms->pause
Go: Forms.Pause
Java: forms().pause
C#: Forms.PauseAsync

`nextmail forms resume`

Open a paused form again

forms:writeNeeds a sign-in

Usage

nextmail forms resume <id> [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.

Arguments

<id>Required: Form id such as frm_8d2f6a1c9b3e47d0a5f1c2e9.

Examples

nextmail forms resume frm_8d2f6a1c9b3e47d0a5f1c2e9

Print the raw JSON

nextmail forms resume frm_8d2f6a1c9b3e47d0a5f1c2e9 --json

Also available in

API: POST /forms/{id}/resume
TypeScript: nextmail.forms.resume()
Python: forms.resume()
Ruby: forms.resume
PHP: forms->resume
Go: Forms.Resume
Java: forms().resume
C#: Forms.ResumeAsync

`nextmail forms duplicate`

Copy a form into a new draft

forms:writeNeeds a sign-in

Usage

nextmail forms duplicate <id> [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.

Arguments

<id>Required: Form id such as frm_8d2f6a1c9b3e47d0a5f1c2e9.

Examples

nextmail forms duplicate frm_8d2f6a1c9b3e47d0a5f1c2e9

Print the raw JSON

nextmail forms duplicate frm_8d2f6a1c9b3e47d0a5f1c2e9 --json

Also available in

API: POST /forms/{id}/duplicate
TypeScript: nextmail.forms.duplicate()
Python: forms.duplicate()
Ruby: forms.duplicate
PHP: forms->duplicate
Go: Forms.Duplicate
Java: forms().duplicate
C#: Forms.DuplicateAsync

`nextmail forms analytics`

Read views, sign-ups and people added over a window

forms:readNeeds a sign-in

Usage

nextmail forms analytics <id> [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.

Arguments

<id>Required: Form id such as frm_8d2f6a1c9b3e47d0a5f1c2e9.

Flags

--days <n>: How far back to look, from 1 to 1095, defaulting to 30.
Default30
--minutes <n>: The window in minutes, from 1 to 1576800, which wins over days when both are sent.
--grain <value>: Bucket width: minute, hour or day, defaulting to day.
Default"day"
--offset-minutes <n>: Minutes east of UTC to cut the buckets in, from -840 to 840, defaulting to 0. Pass -new Date().getTimezoneOffset() for the local zone.
Default0

Examples

The required values only

nextmail forms analytics frm_8d2f6a1c9b3e47d0a5f1c2e9

With optional flags

nextmail forms analytics frm_8d2f6a1c9b3e47d0a5f1c2e9 --days 90 --grain day

Print the raw JSON

nextmail forms analytics frm_8d2f6a1c9b3e47d0a5f1c2e9 --json

Also available in

API: GET /forms/{id}/analytics
TypeScript: nextmail.forms.analytics()
Python: forms.analytics()
Ruby: forms.analytics
PHP: forms->analytics
Go: Forms.Analytics
Java: forms().analytics
C#: Forms.AnalyticsAsync

`nextmail forms list-submissions`

List one page of a form's submissions

forms:readNeeds a sign-in

Usage

nextmail forms list-submissions <id> [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.

Arguments

<id>Required: Form id such as frm_8d2f6a1c9b3e47d0a5f1c2e9.

Flags

--limit <n>: Rows per page, a whole number from 1 to 100. The server defaults to 25.
Default25
--cursor <value>: 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 <value>: Only submissions whose email address contains this text, ignoring case, at most 200 characters.
--status <value>: Only pending or only added submissions.
--all: Fetch every page and stream the items as they arrive.
--max <n>: Stop after this many items. Implies --all.
--ndjson: Print every item as one JSON object per line. Implies --all

Examples

The required values only

nextmail forms list-submissions frm_8d2f6a1c9b3e47d0a5f1c2e9

With optional flags

nextmail forms list-submissions frm_8d2f6a1c9b3e47d0a5f1c2e9 --status pending

Walk every page and stop after 100 items

nextmail forms list-submissions frm_8d2f6a1c9b3e47d0a5f1c2e9 --all --max 100

One JSON object per line when piped

nextmail forms list-submissions frm_8d2f6a1c9b3e47d0a5f1c2e9 --all > forms.ndjson

Also available in

API: GET /forms/{id}/submissions
TypeScript: nextmail.forms.listSubmissions()
Python: forms.list_submissions()
Ruby: forms.list_submissions
PHP: forms->listSubmissions
Go: Forms.ListSubmissions
Java: forms().listSubmissions
C#: Forms.ListSubmissionsAsync

`nextmail forms get-submission`

Retrieve one submission with every answer

forms:readNeeds a sign-in

Usage

nextmail forms get-submission <id> <submission-id> [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.

Arguments

<id>Required: Form id such as frm_8d2f6a1c9b3e47d0a5f1c2e9.
<submission-id>Required: Submission id such as fsb_3c7e1a9f0b2d4c6e8a1f3b5d, from listSubmissions or a form.submitted webhook.

Examples

nextmail forms get-submission frm_8d2f6a1c9b3e47d0a5f1c2e9 fsb_3c7e1a9f0b2d4c6e8a1f3b5d

Print the raw JSON

nextmail forms get-submission frm_8d2f6a1c9b3e47d0a5f1c2e9 fsb_3c7e1a9f0b2d4c6e8a1f3b5d --json

Also available in

API: GET /forms/{id}/submissions/{submissionId}
TypeScript: nextmail.forms.getSubmission()
Python: forms.get_submission()
Ruby: forms.get_submission
PHP: forms->getSubmission
Go: Forms.GetSubmission
Java: forms().getSubmission
C#: Forms.GetSubmissionAsync

`nextmail forms delete-submission`

Delete one submission of a form

forms:writeNeeds a sign-in

Asks you to confirm

Usage

nextmail forms delete-submission <id> <submission-id> [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.

Arguments

<id>Required: Form id such as frm_8d2f6a1c9b3e47d0a5f1c2e9.
<submission-id>Required: Submission id such as fsb_3c7e1a9f0b2d4c6e8a1f3b5d, from listSubmissions or a form.submitted webhook.

Examples

nextmail forms delete-submission frm_8d2f6a1c9b3e47d0a5f1c2e9 fsb_3c7e1a9f0b2d4c6e8a1f3b5d

Skip the confirmation, for scripts

nextmail forms delete-submission frm_8d2f6a1c9b3e47d0a5f1c2e9 fsb_3c7e1a9f0b2d4c6e8a1f3b5d --yes

Also available in

API: DELETE /forms/{id}/submissions/{submissionId}
TypeScript: nextmail.forms.deleteSubmission()
Python: forms.delete_submission()
Ruby: forms.delete_submission
PHP: forms->deleteSubmission
Go: Forms.DeleteSubmission
Java: forms().deleteSubmission
C#: Forms.DeleteSubmissionAsync

`nextmail forms delete-submissions`

Delete up to 200 submissions of a form in one call

forms:writeNeeds a sign-in

Asks you to confirm

Usage

nextmail forms delete-submissions <id> <submission-ids...> [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.

Arguments

<id>Required: Form id such as frm_8d2f6a1c9b3e47d0a5f1c2e9.
<submission-ids...>RequiredOne or more: 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

nextmail forms delete-submissions frm_8d2f6a1c9b3e47d0a5f1c2e9 fsb_3c7e1a9f0b2d4c6e8a1f3b5d

Skip the confirmation, for scripts

nextmail forms delete-submissions frm_8d2f6a1c9b3e47d0a5f1c2e9 fsb_3c7e1a9f0b2d4c6e8a1f3b5d --yes

Also available in

API: POST /forms/{id}/submissions/batch-remove
TypeScript: nextmail.forms.deleteSubmissions()
Python: forms.delete_submissions()
Ruby: forms.delete_submissions
PHP: forms->deleteSubmissions
Go: Forms.DeleteSubmissions
Java: forms().deleteSubmissions
C#: Forms.DeleteSubmissionsAsync

`nextmail forms approve-submission`

Add a waiting sign-up without its confirmation

forms:writecontacts:writeNeeds a sign-in

Usage

nextmail forms approve-submission <id> <submission-id> [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.

Arguments

<id>Required: Form id such as frm_8d2f6a1c9b3e47d0a5f1c2e9.
<submission-id>Required: Submission id such as fsb_3c7e1a9f0b2d4c6e8a1f3b5d, from listSubmissions or a form.submitted webhook.

Examples

nextmail forms approve-submission frm_8d2f6a1c9b3e47d0a5f1c2e9 fsb_3c7e1a9f0b2d4c6e8a1f3b5d

Print the raw JSON

nextmail forms approve-submission frm_8d2f6a1c9b3e47d0a5f1c2e9 fsb_3c7e1a9f0b2d4c6e8a1f3b5d --json

Also available in

API: POST /forms/{id}/submissions/{submissionId}/approve
TypeScript: nextmail.forms.approveSubmission()
Python: forms.approve_submission()
Ruby: forms.approve_submission
PHP: forms->approveSubmission
Go: Forms.ApproveSubmission
Java: forms().approveSubmission
C#: Forms.ApproveSubmissionAsync

`nextmail forms resend-confirmation`

Email a waiting sign-up a fresh confirmation link

forms:writeemails:sendNeeds a sign-in

Usage

nextmail forms resend-confirmation <id> <submission-id> [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.

Arguments

<id>Required: Form id such as frm_8d2f6a1c9b3e47d0a5f1c2e9.
<submission-id>Required: Submission id such as fsb_3c7e1a9f0b2d4c6e8a1f3b5d, from listSubmissions or a form.submitted webhook.

Examples

nextmail forms resend-confirmation frm_8d2f6a1c9b3e47d0a5f1c2e9 fsb_3c7e1a9f0b2d4c6e8a1f3b5d

Print the raw JSON

nextmail forms resend-confirmation frm_8d2f6a1c9b3e47d0a5f1c2e9 fsb_3c7e1a9f0b2d4c6e8a1f3b5d --json

Also available in

API: POST /forms/{id}/submissions/{submissionId}/resend
TypeScript: nextmail.forms.resendConfirmation()
Python: forms.resend_confirmation()
Ruby: forms.resend_confirmation
PHP: forms->resendConfirmation
Go: Forms.ResendConfirmation
Java: forms().resendConfirmation
C#: Forms.ResendConfirmationAsync

`nextmail forms subscribe`

Sign someone up through a published form

No sign-in needed

Usage

nextmail forms subscribe <form-id> --email <value> [flags]
nextmail forms subscribe <form-id> --data <json|@file|-> [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.

Arguments

<form-id>Required: The id of a published form, such as frm_8d2f6a1c9b3e47d0a5f1c2e9.

Flags

--email <value>: The address to sign up, the answer to the email field every form has. Required, here or in --data.
--oe-source <value>: 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 <json|@file|->: The whole values as JSON, inline, from a file with @path, or - for standard input. Flags override its keys.

Examples

The required values only

nextmail forms subscribe frm_8d2f6a1c9b3e47d0a5f1c2e9 --email ada@example.com

With optional flags

nextmail forms subscribe frm_8d2f6a1c9b3e47d0a5f1c2e9 --email ada@example.com --oe-source https://acme.com/launch

Read the whole body from a JSON file

nextmail forms subscribe frm_8d2f6a1c9b3e47d0a5f1c2e9 --data @form.json

Also available in

API: POST /subscribe/{formId}
TypeScript: nextmail.forms.subscribe()
Python: forms.subscribe()
Ruby: forms.subscribe
PHP: forms->subscribe
Go: Forms.Subscribe
Java: forms().subscribe
C#: Forms.SubscribeAsync