Build Smart Lists

Build Smart Lists for Segmentation

Create the core active (dynamic) lists that serve as the foundation for all marketing campaigns, sales prioritization, and database health monitoring. Ten foundation lists are created automatically via the Lists API (v3); a further set of advanced segments is built in the UI.

Why This Matters

Without predefined lists, every email campaign requires building filters from scratch, there is no standardized definition of "who can we actually email", and there is no persona-based segmentation. The marketing team cannot quickly answer basic questions like "How many senior decision-makers can we email right now?" or "How many engaged contacts do we have?"

Prerequisites

• Super Admin or Marketing Hub Admin permissions
• A HubSpot private app access token (HUBSPOT_ACCESS_TOKEN in .env) with crm.lists.read and crm.lists.write scopes
• Python 3.10+ with uv
• ICP Tier property created and workflows processed (create-icp-tiers skill) — the script assumes the property name company_segment with values like tier_1_primary_icp; adjust its configuration block if yours differ
• Lead scoring model created (build-lead-scoring skill) is recommended but not required
• Lifecycle Stage property populated for customers and partners (fix-lifecycle-stages skill)

Scripts

execute.py creates the 10 foundation lists below via POST /crm/v3/lists, skips lists that already exist (409), and writes a CSV audit trail of created list IDs. There are no before/after scripts: the before-state inventory is a single Lists API query (see Before), and verification is a member-count review in the UI.

Interview: Gather Requirements

Before executing, collect the following information from the user:

Q1: What defines "engaged" for your business? (e.g., activity in last 60-120 days)

• Examples: Email open or click in last 90 days, website visit in last 60 days, form submission in last 30 days
• Default: Email open or click in the last 90 days (set ACTIVE_WINDOW_DAYS in the script; shorter cycles suit high-velocity sales, longer cycles suit enterprise)

Q2: What job titles represent your target personas?

• Examples: CEO, COO, CFO, CTO, CRO, VP of Operations, VP of Marketing, Director of Operations, Director of Marketing, Head of Procurement, Engineering Manager
• Default: C-suite and VP/Director-level leaders across business functions (used for the UI-built persona list)

The List Library

Foundation lists (created by the script)

Advanced segments (built in the UI)

These use features that benefit from human judgment and portal-specific configuration (list-membership filters, persona keywords, form-name keywords):

Overlap note: "All Customers" (script) covers the Customers use case; "Unengaged 180+ Days" (script) is a simpler variant of "Re-engagement Needed" (UI, adds the delivered-count guard). Keep whichever fits your operation — do not maintain both without a reason.

Plan

1. Run the interview above; set ACTIVE_WINDOW_DAYS, REENGAGEMENT_WINDOW_DAYS, and ICP_PROPERTY_NAME in the script's configuration block
2. Decide which advanced segments to build in the UI
3. Create foundation lists via the script, advanced segments via the UI
4. Verify list sizes make sense relative to the database

Before

Inventory existing lists to avoid duplicates (POST /crm/v3/lists/search with an empty query returns all lists, paginated). Check for name collisions with the library above — the script skips exact name matches (HTTP 409), but near-duplicates ("Customers" vs "All Customers") need a human decision: merge, rename, or skip.

Execute

Step 1: Foundation lists (script)

uv run skills/build-smart-lists/scripts/execute.py

The script posts each definition to POST /crm/v3/lists with processingType: "DYNAMIC". Example payload shape (see the script for all ten):

{
    "name": "All Customers",
    "objectTypeId": "0-1",  # contacts ("0-2" for companies)
    "processingType": "DYNAMIC",
    "filterBranch": {
        "filterBranchType": "AND",
        "filterBranches": [],
        "filters": [{
            "filterType": "PROPERTY",
            "property": "lifecyclestage",
            "operation": {
                "operationType": "ENUMERATION",
                "operator": "IS_EQUAL_TO",
                "value": "customer",
            },
        }],
    },
}

If the Lists API returns 403 on your plan tier, build the same lists manually in the UI using the table above.

Step 2: Marketable - Active (master sendable list — UI)

This is the most important advanced list. It defines the single source of truth for "who can receive marketing email." All campaign sends should reference this list.

1. Go to Contacts > Lists > Create list
2. Select Contact-based > Active list
3. Name: Marketable - Active
4. Add filters (all AND logic):
   • Marketing contact status > is any of > Marketing contact
   • AND Unsubscribed from all email > is not equal to > True
   • AND Hard bounce reason > is unknown
   • AND Email > is known
   • AND Email quarantined > is not equal to > True
5. Save the list

Step 3: Remaining advanced segments (UI)

ICP Tier 1 / Tier 2 Contacts (B, C):

• Filters: Associated company property > ICP Tier > is any of > [tier] AND List membership > is member of > Marketable - Active
• Using List membership as a filter is a powerful pattern: these lists automatically inherit all deliverability and consent logic from Marketable - Active. New disqualification conditions added there propagate automatically.

Partners (D): Lifecycle stage > is any of > Partner. Always exclude from prospect campaigns.

Re-engagement Needed (E):

• Marketing emails delivered > is greater than > 5
• AND Last marketing email open date > is more than > 180 days ago (tune to your cycle: 120-270)
• AND List membership > is member of > Marketable - Active
• Feeds the engagement-based suppression workflow.

Senior Decision Makers (F): Job title > contains any of > [your target titles]. Customize keywords to your buyer personas.

Industry Leaders (G): Associated company property > Industry > is any of > [your target industries].

Content Engaged (H): OR logic between groups:

• Number of Form Submissions > is greater than > 0
• OR First conversion > contains any of > [content keywords like "Download", "Guide", "Checklist", "E-Book", "Whitepaper"]
• OR Recent conversion > contains any of > [same keywords]
• The conversion-based filters depend on your form naming conventions — review actual form names (Marketing > Forms) and adjust.

After

Verify List Sizes

After all lists are created and processed:

Verification Checklist

1. All lists show as Active (not Static) in the list view
2. All lists have completed processing (no "Processing" status)
3. Sendable-list sanity check: Open Marketable - Active (or All Marketing Contacts), click 5 random contacts. Each should have a valid email, not be unsubscribed, not be bounced.
4. ICP list check: Open an ICP Tier 1 list, click 5 records. Each should have ICP Tier = Tier 1.
5. Persona list check: Open Senior Decision Makers, verify job titles match expected patterns. Watch for false positives (e.g., "Marketing Intern" matching on "Marketing").
6. Re-engagement check: Verify contacts have 5+ emails delivered and no open beyond your configured window.

Rollback

• Lists can be deleted via DELETE /crm/v3/lists/{listId} or the UI — the script's CSV audit trail records every list ID it created.
• Deleting a list does not affect the contacts in it — only the list definition is removed.
• Check whether any workflows, emails, or dependent lists (list-membership filters!) reference a list before deleting it.

Key Technical Learnings

• The master sendable list is the foundation. Every email campaign should either send directly to it (with additional filters) or use it as an inclusion filter. Never send to a list that does not incorporate deliverability and consent checks.
• List membership as a filter is a powerful pattern. Changes to the master list's criteria automatically propagate to all dependent lists.
• "Contains any of" for job titles is broad by design. It matches the keyword anywhere in the title string, so "CTO" matches "CTO", "Former CTO", "Assistant to the CTO". Review lists periodically and add exclusion terms (e.g., AND Job title does not contain "Former", "Assistant", "Intern") if false positives become a problem.
• Content and event lists depend on form naming conventions. The keyword-based filters only work if forms follow a naming convention that includes the keywords. After creating the lists, check if counts seem too low and adjust keywords to match actual form names.
• Active lists have a processing delay. HubSpot processes active lists periodically (every few minutes for small lists, potentially longer for complex ones). Wait for processing to complete before judging counts.
• Each list should be active (dynamic), not static. Static lists are snapshots that never update. Active lists update automatically as contact properties change, which is essential for ongoing segmentation.
• The ICP property name and values must match the create-icp-tiers skill. The script defaults to property company_segment with values tier_1_primary_icp / tier_2_secondary_icp / tier_3_tertiary_icp. If you chose different names, update the script's configuration block before running.
• Plan for growth. These lists cover core use cases. As marketing operations mature, add more targeted lists: "MQL Ready" (score threshold), "Competitor Employees" (for exclusion), "Recent Form Submitters (Last 30 Days)" (for fast follow-up), or service/product-specific interest lists.
• Build a dashboard. Create a dashboard with one KPI tile per list showing the current count. This gives at-a-glance visibility into segment health and makes it easy to spot sudden changes (e.g., Marketable list drops 50% = something broke).