Email Lists

Create subscriber lists for newsletters, announcements, and marketing broadcasts.

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

Create a list

POST https://api.molted.email/v1/agent/lists

CLI

molted lists create --name "Weekly Digest" --type newsletter --double-opt-in

curl

curl -X POST https://api.molted.email/v1/agent/lists \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Digest",
    "type": "newsletter",
    "doubleOptIn": true,
    "description": "Weekly product updates"
  }'

List types

Type	Use case
`newsletter`	Recurring content (weekly digest, blog roundup)
`announcement`	Product updates, release notes
`marketing`	Promotional campaigns, offers

List all lists

GET https://api.molted.email/v1/agent/lists

CLI

molted lists list
molted lists list --limit 10 --offset 20

Get a list

GET https://api.molted.email/v1/agent/lists/:id

CLI

molted lists get <list-id>

Update a list

PATCH https://api.molted.email/v1/agent/lists/:id

CLI

molted lists update <list-id> --name "New Name" --description "Updated description"
molted lists update <list-id> --status paused

Updatable fields: name, description, type, status, doubleOptIn.

Archive a list

DELETE https://api.molted.email/v1/agent/lists/:id

CLI

molted lists archive <list-id>

Archiving soft-deletes the list. Subscribers are preserved but no new sends can be initiated.

POST https://api.molted.email/v1/agent/lists/:id/subscribers

CLI

molted lists subscribe <list-id> --email alice@example.com --name "Alice"

If double opt-in is enabled on the list, the subscriber status will be pending until they confirm.

Unsubscribe a contact

POST https://api.molted.email/v1/agent/lists/:id/unsubscribe

CLI

molted lists unsubscribe <list-id> --email alice@example.com

List subscribers

GET https://api.molted.email/v1/agent/lists/:id/subscribers

CLI

molted lists subscribers <list-id>
molted lists subscribers <list-id> --limit 100 --offset 0

Bulk import subscribers

CLI

molted lists import <list-id> --file subscribers.csv
molted lists import <list-id> --file subscribers.json

CSV format - headers must include email; name is optional; extra columns become metadata:

email,name,plan
alice@example.com,Alice,pro
bob@example.com,Bob,starter

JSON format - array of subscriber objects:

[
  { "email": "alice@example.com", "name": "Alice" },
  { "email": "bob@example.com", "name": "Bob", "metadata": { "plan": "starter" } }
]

Files are processed in chunks of 500. The output includes per-item results and a summary.

Send to a list

POST https://api.molted.email/v1/agent/lists/:id/send

CLI

molted lists send <list-id> --template <template-id> --yes
molted lists send <list-id> --template <template-id> --mailbox <mailbox-id> --payload '{"promo_code": "SPRING25"}'

The --yes flag skips the confirmation prompt. In non-TTY environments (piped scripts, agent runtimes), confirmation is automatically skipped.

View send history

GET https://api.molted.email/v1/agent/lists/:id/sends

CLI

molted lists sends <list-id>

CLI output format

All list commands use a structured JSON envelope for agent-friendly parsing:

Success

{
  "status": "success",
  "message": "List 'Weekly Digest' created successfully.",
  "data": { "id": "...", "name": "Weekly Digest", "subscriberCount": 0 }
}

Error

{
  "status": "error",
  "message": "Failed to create list",
  "details": { "error": "..." }
}

Bulk operations include a summary object with counts for subscribed, alreadySubscribed, and failed.

On this page