SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场build-smart-lists

build-smart-lists

营销与增长

查看项目

更新于 10-16 03:19

技能介绍

用途

build-smart-lists 用于在 HubSpot 中创建营销与销售运营所需的分群列表，作为所有营销活动、销售优先级排序和数据库健康监控的基础。若没有预定义列表，每次邮件活动都需要从零构建筛选条件，且无法标准化定义“哪些联系人实际可接收邮件”，也没有基于画像的分群。该技能通过 Lists API（v3）自动创建十个基础动态列表，并提供一组在界面中构建的高级分群方案。

主要能力

基础列表（由脚本创建）

脚本 scripts/execute.py 通过 POST /crm/v3/lists 创建以下 10 个动态列表，已存在的列表会被跳过（HTTP 409），并输出记录所创建列表 ID 的 CSV 审计文件：

  1. All Marketing Contacts（联系人，hs_marketable_status = true）
  2. All Leads（生命周期阶段 = Lead）
  3. All MQLs（生命周期阶段 = MQL）
  4. All SQLs（生命周期阶段 = SQL）
  5. All Customers（生命周期阶段 = Customer）
  6. ICP Tier 1 Companies（公司，ICP Tier = Tier 1）
  7. ICP Tier 2 Companies（公司，ICP Tier = Tier 2）
  8. ICP Tier 3 Companies（公司，ICP Tier = Tier 3）
  9. Engaged Last 90 Days（联系人，活动窗口内打开或点击邮件）
  10. Unengaged 180+ Days（联系人，可营销且超过再互动窗口无邮件打开）

高级分群（在界面中构建）

这些列表使用需要人工判断或门户特定配置的功能（列表成员筛选、职位关键词、表单名称关键词）：

A. Marketable - Active：主可发送列表，定义“谁可以接收营销邮件”的唯一事实来源。 B. ICP Tier 1 Contacts：关联公司 ICP Tier = Tier 1 且属于 Marketable - Active。 C. ICP Tier 2 Contacts：关联公司 ICP Tier = Tier 2 且属于 Marketable - Active。 D. Partners：生命周期阶段 = Partner（或自定义联系人类型属性），应从潜客活动中排除。 E. Re-engagement Needed：已送达 5 封以上邮件、180 天内无打开且属于 Marketable - Active。 F. Senior Decision Makers：职位包含目标职位关键词。 G. Industry Leaders：关联公司行业属于目标行业。 H. Content Engaged：表单提交次数 > 0 或转化包含内容关键词。

使用方式

前置条件

  • 超级管理员或营销中心管理员权限
  • HubSpot 私有应用访问令牌（.env 中的 HUBSPOT_ACCESS_TOKEN），需具备 crm.lists.read 和 crm.lists.write 作用域
  • Python 3.10+ 及 uv
  • ICP Tier 属性已创建且工作流已处理（create-icp-tiers 技能）；脚本假定属性名为 company_segment，值为 tier_1_primary_icp 等，如不同需调整脚本配置块
  • 建议但不强制要求已创建线索评分模型（build-lead-scoring 技能）
  • 客户和合作伙伴的生命周期阶段属性已填充（fix-lifecycle-stages 技能）

执行步骤

  1. 需求访谈：确认“互动”的定义（默认邮件打开或点击在 90 天内，通过 ACTIVE_WINDOW_DAYS 配置）、目标画像职位（默认 C 级与 VP/Director 级业务职能负责人，用于界面构建的画像列表）。
  2. 在脚本配置块中设置 ACTIVE_WINDOW_DAYS、REENGAGEMENT_WINDOW_DAYS 和 ICP_PROPERTY_NAME。
  3. 决定在界面中构建哪些高级分群。
  4. 运行基础列表脚本：uv run skills/build-smart-lists/scripts/execute.py
  5. 在界面中创建高级分群列表（如 Marketable - Active、ICP Tier 联系人、Partners、Re-engagement Needed、Senior Decision Makers、Industry Leaders、Content Engaged）。

执行前检查

使用 POST /crm/v3/lists/search（空查询返回所有列表，分页）盘点现有列表以避免重复。脚本会跳过名称完全匹配的列表（HTTP 409），但近似重复名称（如“Customers”与“All Customers”）需要人工决定合并、重命名或跳过。

执行后验证

检查各列表规模是否合理（文档提供了预期范围与预警条件，例如 All Marketing Contacts / Marketable - Active 应为总联系人的 30-80%，低于 10% 或高于 90% 需警惕）。验证清单包括：所有列表显示为 Active（非 Static）、已完成处理（无“Processing”状态）、可发送列表随机抽查 5 个联系人具有有效邮箱且未退订未退信、ICP 列表抽查记录属性正确、画像列表职位匹配无假阳性、再互动列表满足送达与窗口条件。

适用场景

  • 营销团队需要快速回答“现在可以给多少高级决策者发邮件”或“我们有多少互动联系人”
  • 销售运营需要基于 ICP 分层进行优先级排序
  • 数据库健康监控与再互动（日落）候选识别
  • 每封营销邮件活动都应引用主可发送列表（Marketable - Active），确保包含可送达性与同意检查

限制

  • 若套餐层级导致 Lists API 返回 403，需按文档表格在界面中手动构建相同列表。
  • 动态列表存在处理延迟，需等待处理完成再判断数量；小列表几分钟，复杂列表可能更久。
  • 职位“包含任意关键词”匹配是宽泛设计，会匹配字符串任意位置（如“CTO”会匹配“Former CTO”“Assistant to the CTO”），需定期审查并添加排除条件。
  • 内容与事件列表依赖表单命名约定，关键词筛选仅在表单命名包含关键词时有效。
  • ICP 属性名称与值必须与 create-icp-tiers 技能一致。
  • 删除列表可通过 DELETE /crm/v3/lists/{listId} 或界面完成，删除列表不影响其中联系人，仅移除列表定义；删除前需检查是否有工作流、邮件或依赖列表（列表成员筛选）引用该列表。
  • 文档建议为增长做规划，随运营成熟可添加更多针对性列表，并创建仪表盘为每个列表显示当前数量。