---
title: "Forms"
description: "Sign-up forms, the people who fill them in, and their numbers."
url: "https://nextmail.sh/docs/mcp/tools/forms"
area: "MCP server"
category: "Tools"
---

# Forms

Sign-up forms, the people who fill them in, and their numbers.

## Forms tools

| Tool | What it does |
| --- | --- |
| listForms | The workspace’s sign-up forms, most recently changed first, with their status, sign-ups and views. |
| getForm | One form in full: its fields, copy, audiences, double opt-in and notifications. A published form adds its link, embed code and the address a plain HTML form posts to, and `includeDesign` returns the draft as JSON. |
| listFormStarters | The starting points a new form can begin from, with the fields each asks for. |
| createForm | Create a form from a starter, from a design written as `document`, or from a starter with changes on top, with any settings. It stays a draft unless `publish` is true, and has double opt-in on unless `doubleOptIn` is false. |
| updateForm | Change a form’s name and settings, which apply at once, or its draft design through `document`. Copy and style merge key by key, and `fields` replaces the whole list. |
| publishForm | Make the current draft what visitors see, so the form takes sign-ups. |
| setFormStatus | Pause a published form, or open it again. |
| duplicateForm | Copy a form into a new draft, without its sign-ups. |
| deleteForm | Delete a form and its sign-ups for good. Its link and embeds stop working, and the people it added stay in your contacts. |
| getFormAnalytics | Views, sign-ups, people added and still waiting, and the conversion rate over a window, in total and per minute, hour or day. Views are kept per hour. |
| listFormSubmissions | The people who filled in a form, newest first, with their answers and status, a page at a time. Search by email address and filter by status. |
| getFormSubmission | One sign-up in full: every answer, its status, when it came in and when the person was added, the page it came from and its audiences. |
| approveFormSubmission | Add a sign-up that is waiting for its confirmation without the email. Needs `contacts:write` as well. |
| resendFormConfirmation | Email a fresh confirmation link to a sign-up still waiting. Nothing is sent when this form emailed that address in the last ten minutes, or when the address has had five from this workspace in the last day. Needs `emails:send` as well. |
| removeFormSubmissions | Delete up to 200 sign-ups of a form by id. Contacts and audiences stay as they are. |
| designForm | Design a new sign-up form from a brief. A designer picks the fields, the copy and the look, and saves it as a draft unless `publish` is true. |
| editFormDesign | Change the fields, wording or look of a form from instructions. The change lands in the draft, and visitors see the published version until `publishForm`. |

> Reading needs `forms:read` and every change needs `forms:write`. Anything that makes a form send mail also needs `emails:send`: turning on double opt-in, setting the sender or the confirmation email, publishing or opening a double opt-in form, and resending a confirmation. A client acting for a member sees only the forms that member made, and a client limited to some addresses may only send confirmations from, and notify, addresses it can reach.

> Designing a form from a written brief works the same here as in the app’s chat: `designForm` makes a new one and `editFormDesign` changes one, like `POST /forms/design` and `POST /forms/{id}/redesign` over REST. A client that would rather design the form itself passes the fields, copy and style as `document` to `createForm` or `updateForm`, and the tools tidy the design and say what they changed.

> Some tools on this server make a change the REST API guards with a verification code, and ask for the same code. Until the client has verified a code in the last 60 minutes, or the person has chosen Allow changes for 60 minutes on it in Account → Connected apps, such a tool answers with a result that starts `Refused (step_up_required):` and changes nothing. `emptyAudience` never asks for a code. The API Authentication page lists every tool that asks, and shows how to ask for a code and verify it.

> The tools apply the same rules and refusals as the REST API, and the `/forms` pages of the API reference describe every field. `listForms` orders by last change, and `createForm` and `updateForm` tidy a partial `document` where the API takes it whole.

## Reference

### `listForms`

List the sign-up forms in this workspace, the most recently changed first: name, id, status (draft, live or paused), sign-ups and views. Use it to find a form by name before reading or changing it.

- Scopes: `forms:read`.
- The app's assistant runs it without asking.
- Toolkit: `forms`.

**Inputs**

Takes no input.

Also available in: API [`GET /forms`](https://nextmail.sh/docs/api/reference/forms#get-forms); TypeScript [`nextmail.forms.list()`](https://nextmail.sh/docs/sdk/reference/forms#list), [`nextmail.forms.listAll()`](https://nextmail.sh/docs/sdk/reference/forms#listAll), [`nextmail.forms.iterate()`](https://nextmail.sh/docs/sdk/reference/forms#iterate); Python [`forms.list()`](https://nextmail.sh/docs/python/reference/forms#list), [`forms.list_all()`](https://nextmail.sh/docs/python/reference/forms#listAll), [`forms.iterate()`](https://nextmail.sh/docs/python/reference/forms#iterate); Ruby [`forms.list`](https://nextmail.sh/docs/ruby/reference/forms#list), [`forms.list_all`](https://nextmail.sh/docs/ruby/reference/forms#listAll), [`forms.iterate`](https://nextmail.sh/docs/ruby/reference/forms#iterate); PHP [`forms->list`](https://nextmail.sh/docs/php/reference/forms#list), [`forms->listAll`](https://nextmail.sh/docs/php/reference/forms#listAll), [`forms->iterate`](https://nextmail.sh/docs/php/reference/forms#iterate); Go [`Forms.List`](https://nextmail.sh/docs/go/reference/forms#list), [`Forms.ListAll`](https://nextmail.sh/docs/go/reference/forms#listAll), [`Forms.Iterate`](https://nextmail.sh/docs/go/reference/forms#iterate); Java [`forms().list`](https://nextmail.sh/docs/java/reference/forms#list), [`forms().listAll`](https://nextmail.sh/docs/java/reference/forms#listAll), [`forms().iterate`](https://nextmail.sh/docs/java/reference/forms#iterate); C# [`Forms.ListAsync`](https://nextmail.sh/docs/csharp/reference/forms#list), [`Forms.ListAllAsync`](https://nextmail.sh/docs/csharp/reference/forms#listAll), [`Forms.IterateAsync`](https://nextmail.sh/docs/csharp/reference/forms#iterate).

### `getForm`

Read one sign-up form: its fields, copy, which audiences it fills, double opt-in, what happens after sign-up, notifications and its numbers, and once it is published its public link, the code to embed it on a website and the address a plain HTML form posts to. includeDesign adds the draft design as JSON, to change and pass back to updateForm as document.

- Scopes: `forms:read`.
- The app's assistant runs it without asking.
- Toolkit: `forms`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters): The form, by id (frm_...). listForms finds it by name.
- `includeDesign` (`boolean`, default `false`)

Also available in: API [`GET /forms/{id}`](https://nextmail.sh/docs/api/reference/forms#get-forms-id); TypeScript [`nextmail.forms.get()`](https://nextmail.sh/docs/sdk/reference/forms#get); Python [`forms.get()`](https://nextmail.sh/docs/python/reference/forms#get); Ruby [`forms.get`](https://nextmail.sh/docs/ruby/reference/forms#get); PHP [`forms->get`](https://nextmail.sh/docs/php/reference/forms#get); Go [`Forms.Get`](https://nextmail.sh/docs/go/reference/forms#get); Java [`forms().get`](https://nextmail.sh/docs/java/reference/forms#get); C# [`Forms.GetAsync`](https://nextmail.sh/docs/csharp/reference/forms#get).

### `listFormStarters`

The starter designs a new sign-up form can begin from: slug, name, the fields each asks for and what it is for. Pass a slug to createForm as starter.

- Scopes: `forms:read`.
- The app's assistant runs it without asking.
- Toolkit: `forms`.

**Inputs**

Takes no input.

Also available in: API [`GET /forms/starters`](https://nextmail.sh/docs/api/reference/forms#get-forms-starters), [`GET /forms/starters/{slug}`](https://nextmail.sh/docs/api/reference/forms#get-forms-starters-slug); TypeScript [`nextmail.forms.listStarters()`](https://nextmail.sh/docs/sdk/reference/forms#listStarters), [`nextmail.forms.getStarter()`](https://nextmail.sh/docs/sdk/reference/forms#getStarter); Python [`forms.list_starters()`](https://nextmail.sh/docs/python/reference/forms#listStarters), [`forms.get_starter()`](https://nextmail.sh/docs/python/reference/forms#getStarter); Ruby [`forms.list_starters`](https://nextmail.sh/docs/ruby/reference/forms#listStarters), [`forms.get_starter`](https://nextmail.sh/docs/ruby/reference/forms#getStarter); PHP [`forms->listStarters`](https://nextmail.sh/docs/php/reference/forms#listStarters), [`forms->getStarter`](https://nextmail.sh/docs/php/reference/forms#getStarter); Go [`Forms.ListStarters`](https://nextmail.sh/docs/go/reference/forms#listStarters), [`Forms.GetStarter`](https://nextmail.sh/docs/go/reference/forms#getStarter); Java [`forms().listStarters`](https://nextmail.sh/docs/java/reference/forms#listStarters), [`forms().getStarter`](https://nextmail.sh/docs/java/reference/forms#getStarter); C# [`Forms.ListStartersAsync`](https://nextmail.sh/docs/csharp/reference/forms#listStarters), [`Forms.GetStarterAsync`](https://nextmail.sh/docs/csharp/reference/forms#getStarter).

### `createForm`

Create a sign-up form from a starter (listFormStarters names them), from a design written out as document, or from a starter with document changes on top: copy and style merge key by key, and fields, when given, replace the list. With neither it starts from a form that asks only for an email address. The settings updateForm takes can be set at once. It is saved as a draft, whose link does not work yet, unless publish is true. A new form has double opt-in on, sending from the first address you may send as, unless doubleOptIn is false.

- Scopes: `forms:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `forms`.

**Inputs**

- `name` (`string`, required, 1 to 120 characters): A short name for the form.
- `description` (`string`, up to 500 characters): One line about what it is for.
- `starter` (`string`, one of `"blank"`, `"newsletter"`, `"waitlist"`, `"event"`, `"early-access"`, `"contact"`)
- `document` (`Record<string, any> | string`): A form design as JSON: {"fields": [...], "copy": {...}, "style": {...}}. A field needs only type and label, for example {"type": "text", "label": "First name", "mapsTo": "firstName", "required": true}. Types: email, text, textarea, number, phone, url, date, select, radio, checkboxes, checkbox, consent, audiences, hidden, heading, paragraph, divider. Every form has exactly one email field. select, radio, checkboxes and audiences take options, as text or {"label", "value"}; an audiences field offers audiences, with their ids as values. mapsTo makes a field fill a detail of the contact, each from one kind of field: firstName from a text field, lastName from a text field, name from a text field, phone from a phone field, company from a text field, jobTitle from a text field, website from a url field, birthday from a date field. The name is saved on the contact, and the rest on its contact card wherever the card has nothing yet. saveAs instead saves the answer to a custom field of the contact, such as {"type": "select", "label": "Plan", "saveAs": "plan"}, one field per custom field, on any field that takes an answer except the email or an audiences field. Fields also take placeholder, help, defaultValue, width (full or half), minLength, maxLength, min and max. copy holds title, description, submitLabel, successTitle, successMessage, pendingTitle, pendingMessage, closedTitle, closedMessage and footer. style holds accent, background, surface and text (#rrggbb), font (system, sans, serif, mono), radius (none, sm, md, lg, full), width (narrow, normal, wide), layout (card, plain), align (left, center) and logoUrl.
- `audienceIds` (`string[]`, up to 20 items): Audiences every sign-up joins, by id from listAudiences. None means All contacts.
- `doubleOptIn` (`boolean`): true emails each new sign-up a link to confirm before they are added.
- `senderAddress` (`string`, nullable, up to 2000 characters): The workspace address confirmation emails come from. Double opt-in needs one.
- `confirmSubject` (`string`, 1 to 200 characters)
- `confirmMessage` (`string`, up to 2000 characters): The confirmation email text. A blank line starts a new paragraph.
- `confirmButton` (`string`, 1 to 60 characters)
- `redirectUrl` (`string`, nullable, up to 2000 characters): A page to send people to after sign-up, or null to show the success message.
- `notifyAddresses` (`string[]`, up to 10 items): Workspace addresses that get an email about each new sign-up.
- `allowedSites` (`string[]`, up to 20 items): The sites that may show this form or post to it, at most 20: a domain (example.com, which covers www.example.com too), 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 means any site. The form's own page always works.
- `publish` (`boolean`, default `false`): true makes it live at once.

Also available in: API [`POST /forms`](https://nextmail.sh/docs/api/reference/forms#post-forms); TypeScript [`nextmail.forms.create()`](https://nextmail.sh/docs/sdk/reference/forms#create); Python [`forms.create()`](https://nextmail.sh/docs/python/reference/forms#create); Ruby [`forms.create`](https://nextmail.sh/docs/ruby/reference/forms#create); PHP [`forms->create`](https://nextmail.sh/docs/php/reference/forms#create); Go [`Forms.Create`](https://nextmail.sh/docs/go/reference/forms#create); Java [`forms().create`](https://nextmail.sh/docs/java/reference/forms#create); C# [`Forms.CreateAsync`](https://nextmail.sh/docs/csharp/reference/forms#create).

### `updateForm`

Change a sign-up form. Its name and settings apply at once, without publishing: the audiences sign-ups join, double opt-in and the address confirmations come from, the confirmation email, what happens after sign-up (message or redirect), which workspace addresses hear about each new sign-up and which sites may show the form or post to it. document changes the design in the draft: copy and style merge into the current ones key by key, and fields, when given, replace the whole list, so start from getForm with includeDesign. A live form keeps showing its published design until publishForm. Pass only what changes.

- Scopes: `forms:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `forms`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters): The form, by id (frm_...). listForms finds it by name.
- `name` (`string`, 1 to 120 characters)
- `description` (`string`, nullable, up to 500 characters)
- `document` (`Record<string, any> | string`): A form design as JSON: {"fields": [...], "copy": {...}, "style": {...}}. A field needs only type and label, for example {"type": "text", "label": "First name", "mapsTo": "firstName", "required": true}. Types: email, text, textarea, number, phone, url, date, select, radio, checkboxes, checkbox, consent, audiences, hidden, heading, paragraph, divider. Every form has exactly one email field. select, radio, checkboxes and audiences take options, as text or {"label", "value"}; an audiences field offers audiences, with their ids as values. mapsTo makes a field fill a detail of the contact, each from one kind of field: firstName from a text field, lastName from a text field, name from a text field, phone from a phone field, company from a text field, jobTitle from a text field, website from a url field, birthday from a date field. The name is saved on the contact, and the rest on its contact card wherever the card has nothing yet. saveAs instead saves the answer to a custom field of the contact, such as {"type": "select", "label": "Plan", "saveAs": "plan"}, one field per custom field, on any field that takes an answer except the email or an audiences field. Fields also take placeholder, help, defaultValue, width (full or half), minLength, maxLength, min and max. copy holds title, description, submitLabel, successTitle, successMessage, pendingTitle, pendingMessage, closedTitle, closedMessage and footer. style holds accent, background, surface and text (#rrggbb), font (system, sans, serif, mono), radius (none, sm, md, lg, full), width (narrow, normal, wide), layout (card, plain), align (left, center) and logoUrl.
- `audienceIds` (`string[]`, up to 20 items): Audiences every sign-up joins, by id from listAudiences. None means All contacts.
- `doubleOptIn` (`boolean`): true emails each new sign-up a link to confirm before they are added.
- `senderAddress` (`string`, nullable, up to 2000 characters): The workspace address confirmation emails come from. Double opt-in needs one.
- `confirmSubject` (`string`, 1 to 200 characters)
- `confirmMessage` (`string`, up to 2000 characters): The confirmation email text. A blank line starts a new paragraph.
- `confirmButton` (`string`, 1 to 60 characters)
- `redirectUrl` (`string`, nullable, up to 2000 characters): A page to send people to after sign-up, or null to show the success message.
- `notifyAddresses` (`string[]`, up to 10 items): Workspace addresses that get an email about each new sign-up.
- `allowedSites` (`string[]`, up to 20 items): The sites that may show this form or post to it, at most 20: a domain (example.com, which covers www.example.com too), 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 means any site. The form's own page always works.

Also available in: API [`PATCH /forms/{id}`](https://nextmail.sh/docs/api/reference/forms#patch-forms-id); TypeScript [`nextmail.forms.update()`](https://nextmail.sh/docs/sdk/reference/forms#update); Python [`forms.update()`](https://nextmail.sh/docs/python/reference/forms#update); Ruby [`forms.update`](https://nextmail.sh/docs/ruby/reference/forms#update); PHP [`forms->update`](https://nextmail.sh/docs/php/reference/forms#update); Go [`Forms.Update`](https://nextmail.sh/docs/go/reference/forms#update); Java [`forms().update`](https://nextmail.sh/docs/java/reference/forms#update); C# [`Forms.UpdateAsync`](https://nextmail.sh/docs/csharp/reference/forms#update).

### `publishForm`

Publish a sign-up form: its current draft becomes what visitors see and it starts taking sign-ups. Use it for a first publish and to push later changes live.

- Scopes: `forms:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `forms`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters): The form, by id (frm_...). listForms finds it by name.

Also available in: API [`POST /forms/{id}/publish`](https://nextmail.sh/docs/api/reference/forms#post-forms-id-publish); TypeScript [`nextmail.forms.publish()`](https://nextmail.sh/docs/sdk/reference/forms#publish); Python [`forms.publish()`](https://nextmail.sh/docs/python/reference/forms#publish); Ruby [`forms.publish`](https://nextmail.sh/docs/ruby/reference/forms#publish); PHP [`forms->publish`](https://nextmail.sh/docs/php/reference/forms#publish); Go [`Forms.Publish`](https://nextmail.sh/docs/go/reference/forms#publish); Java [`forms().publish`](https://nextmail.sh/docs/java/reference/forms#publish); C# [`Forms.PublishAsync`](https://nextmail.sh/docs/csharp/reference/forms#publish).

### `setFormStatus`

Pause a published sign-up form (it shows its closed message and takes no sign-ups) or open it again.

- Scopes: `forms:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `forms`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters): The form, by id (frm_...). listForms finds it by name.
- `status` (`string`, required, one of `"live"`, `"paused"`): live to take sign-ups, paused to stop.

Also available in: API [`POST /forms/{id}/pause`](https://nextmail.sh/docs/api/reference/forms#post-forms-id-pause), [`POST /forms/{id}/resume`](https://nextmail.sh/docs/api/reference/forms#post-forms-id-resume); TypeScript [`nextmail.forms.pause()`](https://nextmail.sh/docs/sdk/reference/forms#pause), [`nextmail.forms.resume()`](https://nextmail.sh/docs/sdk/reference/forms#resume); Python [`forms.pause()`](https://nextmail.sh/docs/python/reference/forms#pause), [`forms.resume()`](https://nextmail.sh/docs/python/reference/forms#resume); Ruby [`forms.pause`](https://nextmail.sh/docs/ruby/reference/forms#pause), [`forms.resume`](https://nextmail.sh/docs/ruby/reference/forms#resume); PHP [`forms->pause`](https://nextmail.sh/docs/php/reference/forms#pause), [`forms->resume`](https://nextmail.sh/docs/php/reference/forms#resume); Go [`Forms.Pause`](https://nextmail.sh/docs/go/reference/forms#pause), [`Forms.Resume`](https://nextmail.sh/docs/go/reference/forms#resume); Java [`forms().pause`](https://nextmail.sh/docs/java/reference/forms#pause), [`forms().resume`](https://nextmail.sh/docs/java/reference/forms#resume); C# [`Forms.PauseAsync`](https://nextmail.sh/docs/csharp/reference/forms#pause), [`Forms.ResumeAsync`](https://nextmail.sh/docs/csharp/reference/forms#resume).

### `duplicateForm`

Copy a sign-up form into a new draft with "copy" after its name: the same draft design and settings, and none of its sign-ups. Audiences you cannot see are left out.

- Scopes: `forms:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `forms`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters): The form, by id (frm_...). listForms finds it by name.

Also available in: API [`POST /forms/{id}/duplicate`](https://nextmail.sh/docs/api/reference/forms#post-forms-id-duplicate); TypeScript [`nextmail.forms.duplicate()`](https://nextmail.sh/docs/sdk/reference/forms#duplicate); Python [`forms.duplicate()`](https://nextmail.sh/docs/python/reference/forms#duplicate); Ruby [`forms.duplicate`](https://nextmail.sh/docs/ruby/reference/forms#duplicate); PHP [`forms->duplicate`](https://nextmail.sh/docs/php/reference/forms#duplicate); Go [`Forms.Duplicate`](https://nextmail.sh/docs/go/reference/forms#duplicate); Java [`forms().duplicate`](https://nextmail.sh/docs/java/reference/forms#duplicate); C# [`Forms.DuplicateAsync`](https://nextmail.sh/docs/csharp/reference/forms#duplicate).

### `deleteForm`

Delete a sign-up form for good. Its public link and every embed stop working at once and its sign-ups are deleted with it; the contacts it added stay, in their audiences. It cannot be undone.

- Scopes: `forms:write`.
- The app's assistant always asks first.
- Asks for a verification code, the same as [`DELETE /forms/{id}`](https://nextmail.sh/docs/api/reference/forms#delete-forms-id).
- Toolkit: `forms`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters): The form, by id (frm_...). listForms finds it by name.

Also available in: API [`DELETE /forms/{id}`](https://nextmail.sh/docs/api/reference/forms#delete-forms-id); TypeScript [`nextmail.forms.delete()`](https://nextmail.sh/docs/sdk/reference/forms#delete); Python [`forms.delete()`](https://nextmail.sh/docs/python/reference/forms#delete); Ruby [`forms.delete`](https://nextmail.sh/docs/ruby/reference/forms#delete); PHP [`forms->delete`](https://nextmail.sh/docs/php/reference/forms#delete); Go [`Forms.Delete`](https://nextmail.sh/docs/go/reference/forms#delete); Java [`forms().delete`](https://nextmail.sh/docs/java/reference/forms#delete); C# [`Forms.DeleteAsync`](https://nextmail.sh/docs/csharp/reference/forms#delete).

### `getFormAnalytics`

How one sign-up form did over a window: views, sign-ups, people added and still waiting to confirm, and the share of views that signed up, in total and per minute, hour or day (grain, day by default). The window reaches back days or minutes from now, minutes winning when both are given, and is 30 days by default. offsetMinutes is the reader's offset from UTC, so a day starts at their midnight.

- Scopes: `forms:read`.
- The app's assistant runs it without asking.
- Toolkit: `forms`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters): The form, by id (frm_...). listForms finds it by name.
- `days` (`integer`, at least 1, at most 1095)
- `minutes` (`integer`, at least 1, at most 1576800)
- `grain` (`string`, one of `"minute"`, `"hour"`, `"day"`)
- `offsetMinutes` (`integer`, at least -840, at most 840)

Also available in: API [`GET /forms/{id}/analytics`](https://nextmail.sh/docs/api/reference/forms#get-forms-id-analytics); TypeScript [`nextmail.forms.analytics()`](https://nextmail.sh/docs/sdk/reference/forms#analytics); Python [`forms.analytics()`](https://nextmail.sh/docs/python/reference/forms#analytics); Ruby [`forms.analytics`](https://nextmail.sh/docs/ruby/reference/forms#analytics); PHP [`forms->analytics`](https://nextmail.sh/docs/php/reference/forms#analytics); Go [`Forms.Analytics`](https://nextmail.sh/docs/go/reference/forms#analytics); Java [`forms().analytics`](https://nextmail.sh/docs/java/reference/forms#analytics); C# [`Forms.AnalyticsAsync`](https://nextmail.sh/docs/csharp/reference/forms#analytics).

### `listFormSubmissions`

The people who filled in one sign-up form, newest first: the sign-up id, their answers, and whether they were added or are waiting to confirm by email (a confirmation link lasts 7 days). q searches email addresses, and status keeps pending or added. One page at a time: when more follow, the last line gives a cursor to pass back for the next page.

- Scopes: `forms:read`.
- The app's assistant runs it without asking.
- Toolkit: `forms`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters): The form, by id (frm_...). listForms finds it by name.
- `q` (`string`, up to 200 characters): Search by email address.
- `status` (`string`, one of `"pending"`, `"added"`)
- `limit` (`integer`, at least 1, at most 100)
- `cursor` (`string`)

Also available in: API [`GET /forms/{id}/submissions`](https://nextmail.sh/docs/api/reference/forms#get-forms-id-submissions); TypeScript [`nextmail.forms.listSubmissions()`](https://nextmail.sh/docs/sdk/reference/forms#listSubmissions), [`nextmail.forms.listAllSubmissions()`](https://nextmail.sh/docs/sdk/reference/forms#listAllSubmissions), [`nextmail.forms.iterateSubmissions()`](https://nextmail.sh/docs/sdk/reference/forms#iterateSubmissions); Python [`forms.list_submissions()`](https://nextmail.sh/docs/python/reference/forms#listSubmissions), [`forms.list_all_submissions()`](https://nextmail.sh/docs/python/reference/forms#listAllSubmissions), [`forms.iterate_submissions()`](https://nextmail.sh/docs/python/reference/forms#iterateSubmissions); Ruby [`forms.list_submissions`](https://nextmail.sh/docs/ruby/reference/forms#listSubmissions), [`forms.list_all_submissions`](https://nextmail.sh/docs/ruby/reference/forms#listAllSubmissions), [`forms.iterate_submissions`](https://nextmail.sh/docs/ruby/reference/forms#iterateSubmissions); PHP [`forms->listSubmissions`](https://nextmail.sh/docs/php/reference/forms#listSubmissions), [`forms->listAllSubmissions`](https://nextmail.sh/docs/php/reference/forms#listAllSubmissions), [`forms->iterateSubmissions`](https://nextmail.sh/docs/php/reference/forms#iterateSubmissions); Go [`Forms.ListSubmissions`](https://nextmail.sh/docs/go/reference/forms#listSubmissions), [`Forms.ListAllSubmissions`](https://nextmail.sh/docs/go/reference/forms#listAllSubmissions), [`Forms.IterateSubmissions`](https://nextmail.sh/docs/go/reference/forms#iterateSubmissions); Java [`forms().listSubmissions`](https://nextmail.sh/docs/java/reference/forms#listSubmissions), [`forms().listAllSubmissions`](https://nextmail.sh/docs/java/reference/forms#listAllSubmissions), [`forms().iterateSubmissions`](https://nextmail.sh/docs/java/reference/forms#iterateSubmissions); C# [`Forms.ListSubmissionsAsync`](https://nextmail.sh/docs/csharp/reference/forms#listSubmissions), [`Forms.ListAllSubmissionsAsync`](https://nextmail.sh/docs/csharp/reference/forms#listAllSubmissions), [`Forms.IterateSubmissionsAsync`](https://nextmail.sh/docs/csharp/reference/forms#iterateSubmissions).

### `getFormSubmission`

One sign-up in full: every answer, whether it was added or is waiting to confirm, when it came in and was added, the page it was sent from and the audiences it joins.

- Scopes: `forms:read`.
- The app's assistant runs it without asking.
- Toolkit: `forms`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters): The form, by id (frm_...). listForms finds it by name.
- `submissionId` (`string`, required, 1 to 64 characters): The sign-up, by id, from listFormSubmissions.

Also available in: API [`GET /forms/{id}/submissions/{submissionId}`](https://nextmail.sh/docs/api/reference/forms#get-forms-id-submissions-submissionid); TypeScript [`nextmail.forms.getSubmission()`](https://nextmail.sh/docs/sdk/reference/forms#getSubmission); Python [`forms.get_submission()`](https://nextmail.sh/docs/python/reference/forms#getSubmission); Ruby [`forms.get_submission`](https://nextmail.sh/docs/ruby/reference/forms#getSubmission); PHP [`forms->getSubmission`](https://nextmail.sh/docs/php/reference/forms#getSubmission); Go [`Forms.GetSubmission`](https://nextmail.sh/docs/go/reference/forms#getSubmission); Java [`forms().getSubmission`](https://nextmail.sh/docs/java/reference/forms#getSubmission); C# [`Forms.GetSubmissionAsync`](https://nextmail.sh/docs/csharp/reference/forms#getSubmission).

### `approveFormSubmission`

Add a sign-up that is waiting to confirm by email without the confirmation: the person becomes a contact and joins the audiences the form fills, now. An address that unsubscribed from one of them before stays unsubscribed there. Use it only when the person really asked to join. A sign-up already added is left as it is.

- Scopes: `forms:write`, `contacts:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `forms`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters): The form, by id (frm_...). listForms finds it by name.
- `submissionId` (`string`, required, 1 to 64 characters): The sign-up, by id, from listFormSubmissions.

Also available in: API [`POST /forms/{id}/submissions/{submissionId}/approve`](https://nextmail.sh/docs/api/reference/forms#post-forms-id-submissions-submissionid-approve); TypeScript [`nextmail.forms.approveSubmission()`](https://nextmail.sh/docs/sdk/reference/forms#approveSubmission); Python [`forms.approve_submission()`](https://nextmail.sh/docs/python/reference/forms#approveSubmission); Ruby [`forms.approve_submission`](https://nextmail.sh/docs/ruby/reference/forms#approveSubmission); PHP [`forms->approveSubmission`](https://nextmail.sh/docs/php/reference/forms#approveSubmission); Go [`Forms.ApproveSubmission`](https://nextmail.sh/docs/go/reference/forms#approveSubmission); Java [`forms().approveSubmission`](https://nextmail.sh/docs/java/reference/forms#approveSubmission); C# [`Forms.ApproveSubmissionAsync`](https://nextmail.sh/docs/csharp/reference/forms#approveSubmission).

### `resendFormConfirmation`

Email a new confirmation link to a sign-up that is still waiting to confirm. Nothing is sent to somebody already added, to an address that got one in the last 10 minutes, or to one that has had 5 from this workspace today.

- Scopes: `forms:write`, `emails:send`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `forms`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters): The form, by id (frm_...). listForms finds it by name.
- `submissionId` (`string`, required, 1 to 64 characters): The sign-up, by id, from listFormSubmissions.

Also available in: API [`POST /forms/{id}/submissions/{submissionId}/resend`](https://nextmail.sh/docs/api/reference/forms#post-forms-id-submissions-submissionid-resend); TypeScript [`nextmail.forms.resendConfirmation()`](https://nextmail.sh/docs/sdk/reference/forms#resendConfirmation); Python [`forms.resend_confirmation()`](https://nextmail.sh/docs/python/reference/forms#resendConfirmation); Ruby [`forms.resend_confirmation`](https://nextmail.sh/docs/ruby/reference/forms#resendConfirmation); PHP [`forms->resendConfirmation`](https://nextmail.sh/docs/php/reference/forms#resendConfirmation); Go [`Forms.ResendConfirmation`](https://nextmail.sh/docs/go/reference/forms#resendConfirmation); Java [`forms().resendConfirmation`](https://nextmail.sh/docs/java/reference/forms#resendConfirmation); C# [`Forms.ResendConfirmationAsync`](https://nextmail.sh/docs/csharp/reference/forms#resendConfirmation).

### `removeFormSubmissions`

Delete up to 200 sign-ups of one form, by id from listFormSubmissions. Only the sign-ups go: contacts and audiences are not touched. It cannot be undone.

- Scopes: `forms:write`.
- The app's assistant always asks first.
- Toolkit: `forms`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters): The form, by id (frm_...). listForms finds it by name.
- `ids` (`string[]`, required, 1 to 200 items): The sign-ups to delete, by id.

Also available in: API [`DELETE /forms/{id}/submissions/{submissionId}`](https://nextmail.sh/docs/api/reference/forms#delete-forms-id-submissions-submissionid), [`POST /forms/{id}/submissions/batch-remove`](https://nextmail.sh/docs/api/reference/forms#post-forms-id-submissions-batch-remove); TypeScript [`nextmail.forms.deleteSubmission()`](https://nextmail.sh/docs/sdk/reference/forms#deleteSubmission), [`nextmail.forms.deleteSubmissions()`](https://nextmail.sh/docs/sdk/reference/forms#deleteSubmissions); Python [`forms.delete_submission()`](https://nextmail.sh/docs/python/reference/forms#deleteSubmission), [`forms.delete_submissions()`](https://nextmail.sh/docs/python/reference/forms#deleteSubmissions); Ruby [`forms.delete_submission`](https://nextmail.sh/docs/ruby/reference/forms#deleteSubmission), [`forms.delete_submissions`](https://nextmail.sh/docs/ruby/reference/forms#deleteSubmissions); PHP [`forms->deleteSubmission`](https://nextmail.sh/docs/php/reference/forms#deleteSubmission), [`forms->deleteSubmissions`](https://nextmail.sh/docs/php/reference/forms#deleteSubmissions); Go [`Forms.DeleteSubmission`](https://nextmail.sh/docs/go/reference/forms#deleteSubmission), [`Forms.DeleteSubmissions`](https://nextmail.sh/docs/go/reference/forms#deleteSubmissions); Java [`forms().deleteSubmission`](https://nextmail.sh/docs/java/reference/forms#deleteSubmission), [`forms().deleteSubmissions`](https://nextmail.sh/docs/java/reference/forms#deleteSubmissions); C# [`Forms.DeleteSubmissionAsync`](https://nextmail.sh/docs/csharp/reference/forms#deleteSubmission), [`Forms.DeleteSubmissionsAsync`](https://nextmail.sh/docs/csharp/reference/forms#deleteSubmissions).

### `designForm`

Design a new sign-up form and save it. Use it whenever the user asks to create, make or build a form, a sign-up or subscribe form, a waitlist, a registration or a contact form. A designer picks the fields, the copy and the look from the brief. It is saved as a draft unless the user asked for it to go live. It takes up to half a minute.

- Scopes: `forms:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `forms`.

**Inputs**

- `name` (`string`, required, 1 to 120 characters): A short name for the form.
- `brief` (`string`, required, 1 to 4000 characters): Everything the form must ask and say: what it is for, the fields, the wording (the user's own text word for word), colours and tone.
- `audienceIds` (`string[]`, up to 20 items): Audiences that every sign-up joins, by id from listAudiences.
- `publish` (`boolean`, default `false`): true only when the user asked for it to go live right away.

Also available in: API [`POST /forms/design`](https://nextmail.sh/docs/api/reference/forms#post-forms-design); TypeScript [`nextmail.forms.design()`](https://nextmail.sh/docs/sdk/reference/forms#design); Python [`forms.design()`](https://nextmail.sh/docs/python/reference/forms#design); Ruby [`forms.design`](https://nextmail.sh/docs/ruby/reference/forms#design); PHP [`forms->design`](https://nextmail.sh/docs/php/reference/forms#design); Go [`Forms.Design`](https://nextmail.sh/docs/go/reference/forms#design); Java [`forms().design`](https://nextmail.sh/docs/java/reference/forms#design); C# [`Forms.DesignAsync`](https://nextmail.sh/docs/csharp/reference/forms#design).

### `editFormDesign`

Change the fields, wording or look of an existing sign-up form: add, remove or reorder fields, make one required, change options, rewrite or translate the copy, change colours or fonts. The change is saved to the draft; a live form keeps its published version until publishForm. It takes up to half a minute.

- Scopes: `forms:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `forms`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters): The form, by id (frm_...). listForms finds it by name.
- `instructions` (`string`, required, 1 to 4000 characters): What to change, with every detail the user gave, their own words word for word.

Also available in: API [`POST /forms/{id}/redesign`](https://nextmail.sh/docs/api/reference/forms#post-forms-id-redesign); TypeScript [`nextmail.forms.redesign()`](https://nextmail.sh/docs/sdk/reference/forms#redesign); Python [`forms.redesign()`](https://nextmail.sh/docs/python/reference/forms#redesign); Ruby [`forms.redesign`](https://nextmail.sh/docs/ruby/reference/forms#redesign); PHP [`forms->redesign`](https://nextmail.sh/docs/php/reference/forms#redesign); Go [`Forms.Redesign`](https://nextmail.sh/docs/go/reference/forms#redesign); Java [`forms().redesign`](https://nextmail.sh/docs/java/reference/forms#redesign); C# [`Forms.RedesignAsync`](https://nextmail.sh/docs/csharp/reference/forms#redesign).