Skip to main content
Lists are containers for organizing subscribers. Each list can have different types, opt-in modes, and subscription settings.

​
List Data Model

Each list has the following properties:
  • ID: Unique numeric identifier
  • UUID: Unique universal identifier for public URLs
  • Name: List name (1-500 characters)
  • Type: public, private, or temporary
  • Opt-in: single or double
  • Status: active or archived
  • Tags: Array of tags for organization
  • Description: Optional text description
  • Created At: Timestamp when list was created
  • Updated At: Timestamp of last modification

​
Creating Lists

1

Navigate to Lists

Click Lists in the main menu
2

Create New List

Click New and configure:
  • Name: Required, unique identifier
  • Type: Choose list visibility and purpose
  • Opt-in Mode: Single or double opt-in
  • Tags: Add organizational tags (optional)
  • Description: Add context for the list (optional)
3

Save and Use

Lists are immediately available for subscriber assignment and campaigns

​
List Types

​
Public Lists

Visible on public subscription pages and available for self-service subscription.Use cases:
  • Newsletter signups
  • Product announcements
  • Marketing campaigns
  • Blog updates
Public subscription pages are enabled via app.enable_public_subscription_page setting

​
Opt-in Modes

Lists support two confirmation workflows:

Single Opt-in

​
Immediate Confirmation

Subscribers are immediately confirmed when added to the list.Characteristics:
  • Subscription status set to confirmed instantly
  • No confirmation email required
  • Faster list growth
  • Higher potential for invalid emails
Best for:
  • Offline signups
  • Imported contacts
  • Gated content downloads

Double Opt-in

​
Email Confirmation Required

Subscribers must confirm via email before receiving campaigns.Characteristics:
  • Subscription status starts as unconfirmed
  • Confirmation email sent automatically
  • Status changes to confirmed after click
  • Better list quality
  • GDPR compliant
Best for:
  • Public signup forms
  • GDPR/privacy compliance
  • High-quality engagement lists

​
Configuring Double Opt-in

Double opt-in campaigns are sent automatically when enabled via app.send_optin_confirmation setting. Opt-in email includes:
  • Confirmation URL with list UUIDs
  • Unsubscribe URL
  • List-Unsubscribe headers (if enabled)

​
Public Subscription Pages

Public lists appear on the self-service subscription page at /subscription/form.

​
Subscription Page Features

1

List Selection

Subscribers can choose which public lists to join
2

Data Collection

Form collects email, name, and optional custom attributes
3

Opt-in Processing

  • Single opt-in: Immediate confirmation
  • Double opt-in: Sends confirmation email
4

Preference Management

Subscribers can manage preferences via unique URLs
Enable public pages via Settings → App → enable_public_subscription_page

​
Managing Lists

​
Updating Lists

Modify list properties:
  • Name, type, opt-in mode
  • Tags and description
  • Status (active/archived)
Changing from single to double opt-in does not retroactively unconfirm existing subscribers

​
Archiving Lists

Set list status to archived to:
  • Hide from campaign list selection
  • Preserve data and relationships
  • Prevent new subscriptions
  • Maintain historical records

​
Deleting Lists

Deleting a list:
  • Removes all subscriber-list relationships
  • Deletes from subscriber_lists table
  • Campaign-list relationships are preserved with list name
  • Cannot be undone
Deleting popular lists can create many orphan subscribers (not subscribed to any list)

​
List Organization

​
Tags

Use tags to categorize lists: 
["newsletter", "product-updates", "weekly"]
Tags are stored as PostgreSQL arrays (VARCHAR[100][]) and can be used for:
  • Filtering in admin interface
  • Organizing related lists
  • Bulk operations

​
Description Field

Add context and notes:
  • Purpose of the list
  • Target audience
  • Campaign schedule
  • Internal documentation

​
Subscriber-List Relationships

The subscriber_lists table manages the many-to-many relationship:

​
Subscription Statuses

Awaiting double opt-in confirmation. Subscribers with this status:
  • Do not receive regular campaigns
  • Can receive opt-in campaigns (type: optin)
  • Can be manually confirmed

​
Meta Field

Each subscription can have custom metadata (JSONB): 
{
  "source": "landing-page-A",
  "subscribed_at": "2024-01-15",
  "referrer": "facebook"
}

​
List Analytics

View subscriber counts per list with breakdown by status: 
SELECT 
  list_id,
  status,
  COUNT(*) as subscriber_count
FROM subscriber_lists
GROUP BY list_id, status
Materialized view mat_list_subscriber_stats provides cached counts for performance.

​
Querying Lists

​
Filter Options

  • Query: Search by name
  • Type: Filter by public, private, temporary
  • Opt-in: Filter by single or double
  • Status: Filter by active or archived
  • Tags: Filter by tag values

​
Minimal Mode

For performance, use ?minimal=true to retrieve lists without JOIN operations (excludes subscriber counts).

​
Campaign Integration

Sending campaigns to lists:
  1. Select one or more target lists when creating a campaign
  2. Campaign reaches subscribers with:
    • Status: enabled (subscriber level)
    • Subscription status: confirmed (for regular campaigns)
    • For opt-in campaigns: unconfirmed status

​
List Names in Campaigns

Campaigns store list names even if lists are deleted: 
CREATE TABLE campaign_lists (
    campaign_id  INTEGER REFERENCES campaigns(id),
    list_id      INTEGER NULL REFERENCES lists(id),
    list_name    TEXT NOT NULL
)

​
API Examples

​
Create List

curl -u 'username:password' -X POST 'http://localhost:9000/api/lists' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Product Updates",
    "type": "public",
    "optin": "double",
    "tags": ["newsletter", "weekly"],
    "description": "Weekly product announcements and updates"
  }'

​
Query Lists

# Get all active public lists
curl -u 'username:password' 'http://localhost:9000/api/lists?type=public&status=active'

# Get lists with specific tag
curl -u 'username:password' 'http://localhost:9000/api/lists?tag=newsletter'

​
Database Schema

CREATE TABLE lists (
    id              SERIAL PRIMARY KEY,
    uuid            UUID NOT NULL UNIQUE,
    name            TEXT NOT NULL,
    type            list_type NOT NULL,
    optin           list_optin NOT NULL DEFAULT 'single',
    status          list_status NOT NULL DEFAULT 'active',
    tags            VARCHAR(100)[],
    description     TEXT NOT NULL DEFAULT '',
    created_at      TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at      TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE TYPE list_type AS ENUM ('public', 'private', 'temporary');
CREATE TYPE list_optin AS ENUM ('single', 'double');
CREATE TYPE list_status AS ENUM ('active', 'archived');

​
Best Practices

Use Double Opt-in

For public-facing lists to ensure compliance and list quality

Tag Consistently

Develop a tagging system for easy filtering and organization

Document Lists

Use descriptions to explain list purpose and audience

Archive Instead of Delete

Preserve historical data by archiving unused lists

Build docs developers (and LLMs) love

Get started for freeTalk to us