# molted lists

Source: https://molted.email/docs/cli/lists

Manage email lists and send broadcasts

| Command | Description |
| - | - |
| [`molted lists create`](#molted-lists-create) | Create a new email list |
| [`molted lists list`](#molted-lists-list) | List email lists (archived lists are left out), most recently updated first |
| [`molted lists get`](#molted-lists-get) | Get an email list by ID |
| [`molted lists update`](#molted-lists-update) | Update an email list |
| [`molted lists archive`](#molted-lists-archive) | Archive (soft-delete) an email list |
| [`molted lists subscribe`](#molted-lists-subscribe) | Subscribe a contact to a list |
| [`molted lists unsubscribe`](#molted-lists-unsubscribe) | Unsubscribe a contact from a list |
| [`molted lists subscribers`](#molted-lists-subscribers) | List subscribers of an email list, newest first, any status (alias: members) |
| [`molted lists import`](#molted-lists-import) | Bulk subscribe contacts from a JSON or CSV file |
| [`molted lists send`](#molted-lists-send) | Send a template to all active subscribers |
| [`molted lists sends`](#molted-lists-sends) | View send history for a list: the latest 50 broadcasts with delivery counts |
| [`molted lists stats`](#molted-lists-stats) | View list statistics (subscriber counts). Use `--growth` or `--sends` for time-series breakdowns. |

## Agent context

Lists are named groups of subscribers for newsletters, announcements, and marketing broadcasts. Unlike segments (dynamic filter-based), lists use explicit subscribe/unsubscribe membership.

### Create a list and add subscribers

```bash
molted lists create --name "Weekly Digest" --type newsletter --double-opt-in
# -> {"id":"<listId>","name":"Weekly Digest","type":"newsletter","doubleOptIn":true,"subscriberCount":0,...}

molted lists subscribe <listId> --email alice@example.com --name "Alice"
# -> {"id":"...","listId":"<listId>","contactId":"...","status":"pending","source":"api",...}
# "active" on a single opt-in list. On a double opt-in list the subscriber
# stays "pending": the API emits a list.subscribe.pending event with a
# confirmationUrl but sends no email itself, so a journey triggered on that
# event must send the confirmation. A suppressed address is refused (400);
# an address that unsubscribed earlier comes back "unsubscribed".

molted lists import <listId> --file contacts.csv
# -> {"total":153,"subscribed":150,"pending":0,"skipped":3,"failed":0,
#     "skippedReasons":{"previously_unsubscribed":3}}
```

### Send to all subscribers

```bash
molted lists send <listId> --template welcome --yes
# -> {"id":"...","status":"completed","subscriberCount":153,"sent":150,
#     "blocked":2,"failed":1,"blockedReasons":{"suppressed":2},...}
# status becomes "failed" when sent === 0 (every attempt was blocked or failed).
# Inspect blockedReasons to see why (e.g. trial_not_activated,
# suppressed, hourly_limit_exceeded).
# The list must be active with 1 to 500 active subscribers (400 otherwise).
# A broadcast is always exempt from requireConsentForMarketing (settings):
# the active subscription itself is the consent, so it never blocks with
# no_consent, whatever that tenant setting is set to. A double opt-in
# confirmation email is exempt the same way.
```

### Check send history

```bash
molted lists sends <listId>
# -> [{"sendId":"...","sentAt":"...","subscriberCount":153,"status":"completed",
#      "templateId":"welcome","delivered":148,"bounced":2,"opened":60,"clicked":12}]
# The latest 50 broadcasts, newest first.
```

### View stats

```bash
molted lists stats <listId>
# -> {"subscriberCount":153,"pendingCount":2,"unsubscribedCount":5,"totalSends":12,"lastSentAt":"..."}
```

Responses return the API object directly (consistent with all other commands). Errors go to stderr as \{ "error": "message", "detail": ... }.

Related: [`molted contacts sync`](https://molted.email/docs/cli/contacts.md), [`molted segments`](https://molted.email/docs/cli/segments.md), [`molted templates`](https://molted.email/docs/cli/templates.md), [`molted suppressions`](https://molted.email/docs/cli/suppressions.md)

## Commands

### molted lists create

Create a new email list

```bash
molted lists create [options]
```

| Option | Description | Default |
| - | - | - |
| `--name <name>` | List name (required; 409 if an unarchived list already has it) (required) | |
| `--type <type>` | List type: newsletter, announcement, marketing (default newsletter) | |
| `--double-opt-in` | Enable double opt-in confirmation | |
| `--description <text>` | List description | |
| `--metadata <json>` | Additional metadata as JSON | |

### molted lists list

List email lists (archived lists are left out), most recently updated first

```bash
molted lists list [options]
```

| Option | Description | Default |
| - | - | - |
| `--status <status>` | Currently ignored: the API has no status filter | |
| `--limit <n>` | Max results, 0-200 (default 50) | |
| `--offset <n>` | Offset for pagination (default 0) | |

### molted lists get

Get an email list by ID

```bash
molted lists get <id>
```

| Argument | Description | Required |
| - | - | - |
| `<id>` | List ID | yes |

### molted lists update

Update an email list

```bash
molted lists update [options] <id>
```

| Argument | Description | Required |
| - | - | - |
| `<id>` | List ID | yes |

| Option | Description | Default |
| - | - | - |
| `--name <name>` | List name | |
| `--description <text>` | List description | |
| `--type <type>` | List type: newsletter, announcement, marketing | |
| `--status <status>` | List status: active, paused, archived (an archived list cannot be reactivated: 409) | |
| `--double-opt-in` | Enable double opt-in | |
| `--no-double-opt-in` | Disable double opt-in | |

### molted lists archive

Archive (soft-delete) an email list

```bash
molted lists archive <id>
```

| Argument | Description | Required |
| - | - | - |
| `<id>` | List ID | yes |

### molted lists subscribe

Subscribe a contact to a list

```bash
molted lists subscribe [options] <listId>
```

| Argument | Description | Required |
| - | - | - |
| `<listId>` | List ID | yes |

| Option | Description | Default |
| - | - | - |
| `--email <email>` | Subscriber email address (required) (required) | |
| `--name <name>` | Subscriber name | |
| `--source <source>` | Subscription source: api, import, form, manual (default api) | |

### molted lists unsubscribe

Unsubscribe a contact from a list

```bash
molted lists unsubscribe [options] <listId>
```

| Argument | Description | Required |
| - | - | - |
| `<listId>` | List ID | yes |

| Option | Description | Default |
| - | - | - |
| `--email <email>` | Subscriber email address (required) (required) | |

### molted lists subscribers

List subscribers of an email list, newest first, any status (alias: members)

```bash
molted lists subscribers [options] <listId>
```

| Argument | Description | Required |
| - | - | - |
| `<listId>` | List ID | yes |

| Option | Description | Default |
| - | - | - |
| `--limit <n>` | Max results, 0-200 (default 50) | |
| `--offset <n>` | Offset for pagination (default 0) | |

### molted lists import

Bulk subscribe contacts from a JSON or CSV file

```bash
molted lists import [options] <listId>
```

| Argument | Description | Required |
| - | - | - |
| `<listId>` | List ID | yes |

| Option | Description | Default |
| - | - | - |
| `--file <path>` | Path to a .csv or .json file of subscribers (required) (required) | |

#### File format reference

CSV  First row must be headers. An "email" column is required.\
Only the email is sent: name and any extra columns are ignored.

email\
[alice@example.com](mailto:alice@example.com)\
[bob@example.com](mailto:bob@example.com)

JSON Top-level array of objects with an "email" field.

```bash
[
  {"email": "alice@example.com"},
  {"email": "bob@example.com"}
]
```

Rows with an empty email are dropped before sending. Every other row is sent and counted by the API as subscribed, pending, skipped (suppressed or previously unsubscribed) or failed, with source "import". Subscribers are sent in batches of 500; the list must be active.

#### Examples

```bash
molted lists import <listId> --file contacts.csv
molted lists import <listId> --file subscribers.json
```

### molted lists send

Send a template to all active subscribers

```bash
molted lists send [options] <listId>
```

| Argument | Description | Required |
| - | - | - |
| `<listId>` | List ID | yes |

| Option | Description | Default |
| - | - | - |
| `--template <slug>` | Template slug (required) (required) | |
| `--payload <json>` | Template payload as JSON | |
| `--mailbox <id>` | Mailbox ID to send from | |
| `--yes` | Skip the confirmation prompt (it only appears on an interactive TTY without CI or `MOLTED_NONINTERACTIVE` set) | |

### molted lists sends

View send history for a list: the latest 50 broadcasts with delivery counts

```bash
molted lists sends [options] <listId>
```

| Argument | Description | Required |
| - | - | - |
| `<listId>` | List ID | yes |

| Option | Description | Default |
| - | - | - |
| `--limit <n>` | Currently ignored: the API always returns the latest 50 | |
| `--offset <n>` | Currently ignored: the API does not page send history | |

### molted lists stats

View list statistics (subscriber counts). Use `--growth` or `--sends` for time-series breakdowns.

```bash
molted lists stats [options] <listId>
```

| Argument | Description | Required |
| - | - | - |
| `<listId>` | List ID | yes |

| Option | Description | Default |
| - | - | - |
| `--growth` | Growth over time instead of the summary (calls .../stats/growth) | |
| `--period <period>` | Time period for `--growth` (default 30d) (one of: 7d, 30d, 90d, all) | |
| `--sends` | Send performance instead of the summary (calls .../stats/sends) | |

See [CLI overview](https://molted.email/docs/cli.md) for global options, credentials and output format.
