---
title: "Sign-up forms"
description: "Every command for sign-up forms and the people who fill them in, with worked examples."
url: "https://openemail.uk/docs/cli/forms"
area: "CLI"
category: "Commands by area"
---

# Sign-up forms

Every command for sign-up forms and the people who fill them in, with worked examples.

## How it fits together

A sign-up form adds the people who fill it in to your audiences. It keeps a draft and a live copy: `update` changes the draft and the settings, and `publish` puts the draft live. Reading needs `forms:read` and changing needs `forms:write`. `resend-confirmation`, and any change that makes the form send mail, also needs `emails:send`.

**Terminal**

```
openemail forms create --name "Newsletter sign-up" --starter newsletter --publish
openemail forms list-submissions frm_3b9d2e7a1c4f80d56e2a9b14 --status pending
openemail forms analytics frm_3b9d2e7a1c4f80d56e2a9b14 --days 30
```

## Forms

| Command | What it does |
| --- | --- |
| openemail forms list | One page of the forms, newest first, with their status and numbers |
| openemail forms create --name <value> | Make a draft from `--starter`, a `--document` file or one email field. `--publish` puts it live at once |
| openemail forms get <id> | One form with its draft, its live copy and its settings |
| openemail forms update <id> | Change the name, the `--document` draft or any settings, such as `--settings-double-opt-in`, in one call |
| openemail forms publish <id> | Put the draft live |
| openemail forms pause <id> | Stop a published form taking sign-ups |
| openemail forms resume <id> | Open a paused form again |
| openemail forms duplicate <id> | Copy a form into a new draft, without its sign-ups |
| openemail forms delete <id> | Delete a form and its sign-ups after you confirm. A browser sign-in also asks for a verification code |
| openemail forms list-starters | The starting points a new form can begin from |
| openemail forms get-starter <slug> | One starting point with its document |
| openemail forms analytics <id> | Views, sign-ups and people added over a window, 30 days unless `--days` or `--minutes` says otherwise |

## Submissions

| Command | What it does |
| --- | --- |
| openemail forms list-submissions <id> | One page of sign-ups, newest first. `--q` searches email addresses and `--status` picks `pending` or `added` |
| openemail forms get-submission <id> <submission-id> | One sign-up with every answer |
| openemail forms delete-submission <id> <submission-id> | Delete one sign-up after you confirm. The person stays in your contacts |
| openemail forms delete-submissions <id> <submission-ids...> | Delete up to 200 sign-ups after you confirm |
| openemail forms approve-submission <id> <submission-id> | Add a waiting sign-up without its confirmation. Needs `contacts:write` too |
| openemail forms resend-confirmation <id> <submission-id> | Email a waiting sign-up a fresh confirmation link, unless one went out in the last ten minutes. Needs `emails:send` too |

## Signing someone up

`subscribe` posts to a published form as its page does. It needs no key and no sign-in, so it works signed out. Pass the other answers as JSON with `--data`, and the page the form was on with `--oe-source`.

**Terminal**

```
openemail forms subscribe frm_3b9d2e7a1c4f80d56e2a9b14 --email ann@example.com --data '{"first_name":"Ann","consent":true}'
```

> A missing or wrong answer exits with code `7` and lists each field and its reason. A paused form exits with `6`, and too many sign-ups from one network with `8`.