build-smart-lists

Files (2)

• SKILL.md
• execute.py · scripts/

SKILL.md (first lines)

# 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 service key (`HUBSPOT_ACCESS_TOKEN` in `.env`; an existing legacy private app token also works) with `crm.lists.read` and `crm.lists.write` scopes
- Python 3.10+ with [`uv`](https://github.com/astral-sh/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

Script paths are relative to this skill's directory. Run them from your project directory so `.env`, `data/`, and `reports/` resolve there: prefix each path with wherever this skill is installed (`skills/build-smart-lists/` in a clone of the repo).

| Stage | Script | Run with |
|-------|--------|----------|
| Execute | [`scripts/execute.py`](./scripts/execute.py) | `uv run scripts/execute.py` |

`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)

| # | List Name | Object | Key Filter |
|---|-----------|--------|-----------|
| 1 | All Marketing Contacts | Contacts | `hs_marketable_status` = true |
| 2 | All Leads | Contacts | Lifecycle stage = Lead |
| 3 | All MQLs | Contacts | Lifecycle stage = MQL |
| 4 | All SQLs | Contacts | Lifecycle stage = SQL |
| 5 | All Customers | Contacts | Lifecycle stage = Customer |
| 6 | ICP Tier 1 Companies | Companies | ICP Tier = Tier 1 |
| 7 | ICP Tier 2 Companies | Companies | ICP Tier = Tier 2 |
| 8 | ICP Tier 3 Companies | Companies | ICP Tier = Tier 3 |
| 9 | Engaged Last 90 Days | Contacts | Email open OR click within the active window |
| 10 | Unengaged 180+ Days | Contacts | Marketable + no email open beyond the re-engagement window |

### 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):

| # | List Name | Purpose | Key Filters |
|---|-----------|---------|-------------|
| A | Marketable - Active | Master sendable list (who CAN receive email) | Marketing contact + not unsubscribed + not bounced + has email + not quarantined |
| B | ICP Tier 1 Contacts | Highest priority *contacts* | Associated company ICP Tier = Tier 1 + member of Marketable - Active |
| C | ICP Tier 2 Contacts | Secondary priority contacts | Associated company ICP Tier = Tier 2 + member of Marketable - Active |
| D | Partners | Partner communications and exclusion | Lifecycle stage = Partner (or custom contact type property) |
| E | Re-engagement Needed | Sunset candidates | 5+ emails delivered + no open in 180 days + member of Marketable - Active |
| F | Senior Decision Makers | Top persona list | Job title contains target titles |
| G | Industry Leaders | Contacts at companies in target verticals | Associated company industry is any of target industries |
| H | Content Engaged | Form submissions and content downloads | Form submissions > 0 OR conversion contains content 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)

```bash
uv run 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):

```python
{
    "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)

From TomGranot/hubspot-admin-skills, MIT.

More from TomGranot/hubspot-admin-skills