Create Segment Lists

Build a library of segment lists that enable targeted marketing, accurate reporting, and proper suppression. These lists form the foundation of segment-based operations.

Prerequisites

- HubSpot API token in INLINECODE0
Python with hubspot-api-client installed via INLINECODE2
ICP tier property created (run /create-icp-tiers first)
Lifecycle stages cleaned up (run /fix-lifecycle-stages first)

Interview: Gather Requirements

Before executing, collect the following information from the user:

Q1: What are your key customer segments?

- Examples: Industry verticals (Manufacturing, Professional Services, Retail, Education, Logistics), company size tiers (Enterprise, Mid-Market, SMB), geographic regions (North America, EMEA, APAC)
Default: Core business segments (Customers, Partners, Competitors, Internal) plus ICP tiers and engagement-based segments

Q2: What engagement criteria define "active" for your business?

- Examples: Email open or click in last 90 days, website visit in last 60 days, form submission in last 30 days, meeting booked in last 90 days
Default: Any email engagement (open or click) within the last 90 days

Recommended Segments

Core Business Segments

List Name	Type	Criteria
All Customers	Active	Lifecycle stage = Customer
All Partners

ICP-Based Segments

List Name	Type	Criteria
ICP Tier 1	Active	ICP tier property = Tier 1
ICP Tier 2

Industry Segments

List Name	Type	Criteria
[Industry Name]	Active	Industry = [value]
(Create one per target industry)

| |

Engagement Segments

List Name	Type	Criteria
Highly Engaged (90 days)	Active	Email open or click in last 90 days
Disengaged (6+ months)

Step-by-Step Instructions

Stage 1: Before — Plan Your Segments

1. Review the segments above and decide which are relevant to your business.
Confirm the properties these lists depend on are populated (ICP tier, lifecycle stage, industry).
Check for existing lists that overlap — merge or rename rather than creating duplicates.

Stage 2: Execute — Create Lists

Use the Lists API to create active (smart) lists:

CODEBLOCK0

Create each list, verify member count, and document the list ID.

For static lists (Competitors), create the list and manually add contacts or import from a CSV.

Stage 3: After — Verify

1. Check member counts for each list — do they match expectations?
Verify no contacts appear in mutually exclusive lists (e.g., both Customer and Competitor).
Confirm lists are visible to the appropriate teams.

Stage 4: Rollback

- Lists can be deleted via the API or UI.
Deleting a list does not affect the contacts in it — only the list definition is removed.
Check if any workflows or emails reference the list before deleting.

Tips

- Use a consistent naming convention: [Category] - Segment Name (e.g., [ICP] - Tier 1, [Industry] - Manufacturing).
Review segment membership quarterly — segments should grow or shrink in expected ways.
Use these lists as building blocks for email sends, ad audiences, and workflow enrollment triggers.

创建细分列表

构建细分列表库，实现精准营销、准确报告和适当排除。这些列表构成了基于细分的运营基础。

前提条件

- .env 文件中的 HubSpot API 令牌
通过 uv 安装了 hubspot-api-client 的 Python 环境
已创建 ICP 层级属性（先运行 /create-icp-tiers）
已清理生命周期阶段（先运行 /fix-lifecycle-stages）

访谈：收集需求

执行前，向用户收集以下信息：

问题1：您的关键客户细分有哪些？

- 示例：行业垂直领域（制造业、专业服务、零售、教育、物流）、公司规模层级（企业级、中端市场、中小企业）、地理区域（北美、欧洲、亚太）
默认：核心业务细分（客户、合作伙伴、竞争对手、内部）加上 ICP 层级和基于互动的细分

问题2：哪些互动标准定义了您业务中的活跃？

- 示例：过去90天内打开或点击邮件、过去60天内访问网站、过去30天内提交表单、过去90天内预约会议
默认：过去90天内任何邮件互动（打开或点击）

列表名称	类型	标准
所有客户	动态	生命周期阶段 = 客户
所有合作伙伴

列表名称	类型	标准
ICP 层级 1	动态	ICP 层级属性 = 层级 1
ICP 层级 2

列表名称	类型	标准
[行业名称]	动态	行业 = [值]
（每个目标行业创建一个）

列表名称	类型	标准
高度活跃（90天内）	动态	过去90天内打开或点击邮件
不活跃（6个月以上）

分步说明

第一阶段：执行前——规划您的细分

1. 查看上述细分，确定哪些与您的业务相关。
确认这些列表依赖的属性已填充（ICP 层级、生命周期阶段、行业）。
检查是否有重叠的现有列表——合并或重命名，避免创建重复。

第二阶段：执行——创建列表

使用列表 API 创建动态（智能）列表：

python
from hubspot import HubSpot

apiclient = HubSpot(accesstoken=os.getenv(HUBSPOTAPITOKEN))

示例：创建所有客户列表

apiclient.crm.lists.listsapi.create( listcreaterequest={ name: 所有客户, objectTypeId: 0-1, # 联系人 processingType: DYNAMIC, filterBranch: { filterBranchType: OR, filters: [{ filterType: PROPERTY, property: lifecyclestage, operation: { operationType: ENUMERATION, operator: ISEQUALTO, value: customer } }] } } )

创建每个列表，验证成员数量，并记录列表 ID。

对于静态列表（竞争对手），创建列表后手动添加联系人或从 CSV 导入。

第三阶段：执行后——验证

1. 检查每个列表的成员数量——是否符合预期？
验证没有联系人出现在互斥列表中（例如，同时出现在客户和竞争对手中）。
确认列表对相应团队可见。

第四阶段：回滚

- 可通过 API 或 UI 删除列表。
删除列表不会影响其中的联系人——仅删除列表定义。
删除前检查是否有任何工作流或邮件引用该列表。

提示

- 使用一致的命名规范：[类别] - 细分名称（例如，[ICP] - 层级 1、[行业] - 制造业）。
每季度审查细分成员——细分应按照预期方式增长或缩减。
将这些列表作为邮件发送、广告受众和工作流触发的基础构建模块。

create-segment-lists创建细分列表