sequenzy-email-marketing

Sequenzy 邮件营销

概述

将此技能用作 Sequenzy 邮件营销／产品运营的默认技能：订阅者、列表、标签、细分、营销活动、序列、模板、AI 邮件生成、事务性发送、投递统计信息、仪表板 URL、CLI／MCP 行为，以及当前支持的工作流检查。对于受支持的工作流，优先使用 sequenzy CLI；如果任务通过 MCP 工具执行，则以 packages/mcp/src/tools/index.ts 为 MCP 的事实来源；如果当前实现尚未接入所请求的工作流，请明确指出。如果 sequenzy 和 sequenzy-email-marketing 都匹配，请先加载此技能。

基本规则

1. 将 packages/cli/src/index.tsx 视为实际接入哪些命令的事实来源。
2. 将 packages/cli/src/commands/ 和 packages/cli/src/api.ts 视为 CLI 行为、负载结构和 API 路由的事实来源。
3. 将 packages/mcp/src/tools/index.ts 视为 MCP 工具名称、参数和执行前验证的事实来源。
4. 对于只出现在文档或 --help 文本中、但没有对应实现的命令或工具，不要承诺支持。
5. 交互式身份验证优先使用 sequenzy login，自动化场景优先使用 SEQUENZY_API_KEY。
6. 只要工作流允许，就优先检查后再修改。

支持的工作流

执行任何重要操作前，请阅读 references/use-cases.md。当前已实现的 CLI 流程如下：

• 登录和退出
• 使用 whoami 检查本地身份验证／会话
• 使用 account 检查账户
• 使用 companies list|get|create|update 检查或创建公司，或更新品牌／发件人身份
• 查看统计概览，或按营销活动、序列或交易邮件 ID 查看统计；支持自定义 --start／--end 时间范围、按 --email-type 和 --mailbox-provider 限定范围、--include-bots，以及营销活动的 clickedLinks 和投票／NPS 的 polls 数组
• 使用 events --campaign|--sequence 列出原始投递／互动事件，使用 email-sends list|get 检查单次投递，并使用 suppressions get|remove 清理退信抑制记录
• 订阅者的 list、add、update、get 和 remove；list 默认会获取所有分页，并支持按标签、细分和列表筛选；add 和 update 使用原生个人资料字段设置姓名，即 --first-name／--last-name（MCP add_subscriber／update_subscriber：firstName／lastName），因此绝不要将姓名存入自定义属性；两者还支持处理原生电话号码和 SMS 同意状态
• 使用 subscribers import／import-status 批量导入订阅者、添加订阅者备注、使用 subscribers event 触发自定义事件（实时触发或通过 --occurred-at 回填），以及使用 subscribers tags add|remove 批量操作标签
• 列表的 list、create、update、delete、add-subscribers、remove-subscribers，以及用于从电子邮件、JSON、CSV 或换行文本文件批量填充列表的 import 别名
• 标签的 list、create、update 和 delete；为保持向后兼容，不带子命令的 sequenzy tags 仍会列出标签定义
• 细分的 list、create、update、delete 和 count，包括 --match any、嵌套筛选器根节点、自定义事件筛选器和已保存细分组合筛选器
• 模板的 list、get、create、update 和 delete；list 支持按标签筛选，create／update 接受标签、原始 HTML 或 Sequenzy 区块 JSON
• 营销活动的 list、get、create、update（包括标签和回复地址更新）、schedule 和 test；list 支持按标签筛选，create 接受标签以及原始 HTML、Sequenzy 区块 JSON 或通过提示词生成的内容，update 接受标签以及原始 HTML 或 Sequenzy 区块 JSON，schedule 会返回审核预览链接；create 和 schedule 均可通过 --segment 或 --target-lists-json／--target-lists-file 指定受众
• 营销活动生命周期控制：campaigns cancel（立即停止已排期、已暂停、等待审批或正在发送的营销活动，不会提示确认）、campaigns unschedule（将已排期的营销活动或循环系列恢复为草稿）、对正在进行的发送使用 campaigns pause 和 campaigns resume（resume 支持 --spread-over-hours）、campaigns delete（发送中、已排期或已暂停时无法删除，须先取消），以及使用 --mode campaign|ab_test|variant 的 campaigns duplicate
• 使用 campaigns audience 检查营销活动受众；使用 campaigns render／templates render／sequences render 生成真实待发送的 HTML 预览（支持订阅者或临时个性化、区域设置、跟踪和 --out）；使用 campaigns schedule --repeat weekly|monthly 设置循环发送；以及在发送后使用 campaigns resend-to-non-openers 重新触达未打开邮件的用户
• A/B 测试的 list、get、stats、restart、update-variant、create、add-variant、delete-variant 和 delete；create／add-variant／delete-variant／delete 用于草稿状态的营销活动 A/B 测试，变体 A 是受保护的对照组，restart 会重新运行已结束的序列 A/B 测试。对于序列 A/B 测试步骤，在授予 ab_tests:read 权限后，sequences get --json 和 MCP get_sequence 会显示每个变体的完整区块；只能通过 ab-tests update-variant／update_ab_test_variant 编辑这些区块
• MCP 模板和营销活动工具支持在列出／创建／更新时使用标签；MCP update_campaign 还支持 replyTo 和 replyProfileId，MCP schedule_campaign 可为草稿或已排期的营销活动安排发送
• MCP search_subscribers 支持通过 list、listId 或 listName 使用列表筛选器；MCP add_subscribers_to_list 每次调用最多接受 500 个电子邮件地址
• 序列的 list、get、create、update、enable、disable、delete、enroll 和 cancel-enrollments；包括显式折扣操作步骤、按订阅者 ID 或事件属性字段值取消订阅，以及使用 update 插入包含标签、列表、细分、事件、已点击链接和字段条件的分支；事件和已点击链接分支检查可使用 activityScope（this_sequence、previous_email、ever）
• 使用 sequences enroll 从电子邮件、JSON 或文件手动添加订阅，可通过 --target-node-id 指定节点，并报告已添加、已跳过和未找到的订阅者
• 团队的 list、invite（支持 --role admin|marketer|viewer|restricted 和仅限所有者使用的 --billing-access），以及 cancel-invitation
• 收件箱的 list（支持按状态、搜索、未读状态和分页筛选）、get、reply（通过 --note 添加内部备注）、close、reopen 和 mark-read
• 用于出站 Webhook 端点的 webhooks list、create、update、delete、test、deliveries 和 replay；create 会返回一次性签名密钥，必须作为敏感信息处理
• AI 生成：generate email、generate sequence、generate subjects 和 generate sms
• 生成仪表盘 URL：CLI urls、MCP get_app_urls，以及营销活动、序列、模板和公司结果中的 appUrls／url 字段
• 网站的 list、add、check 和 guide
• 用于数字产品交付的产品 list、sync、upsert（以自定义 ID 为键的 API 提供方产品，每批最多 100 个）、delete、attach-file 和 detach-file；attach-file --file 会通过预签名 URL 上传本地文件；附加文件会作为 {{event.download.url}}／{{event.download.name}} 暴露在 saas.purchase 事件中（MCP：list_products、upsert_products、delete_product、attach_product_file、remove_product_file、sync_products）
• 使用 api-keys create|list|revoke 管理 API 密钥，包括创建时使用权限预设和显式范围；新密钥的输出属于敏感信息
• 交易邮件：通过 send 使用模板或原始 HTML 发送单次邮件；通过 transactional list|get|create|update|delete 管理已保存的模板，并通过 transactional widgets preferences-token 获取偏好设置 iframe 令牌
• 表单的 list 和 update（MCP 还提供：create_form、get_form_embed），以及使用 landing-pages 全面管理落地页，包括发布／取消发布、复制、自定义域名和 DNS 验证
• 序列的 CRUD 之外的操作：render、发送到特定节点的 test 邮件、duplicate、archive／unarchive、支持 CSV 导出的订阅列表、pause-enrollments／resume-enrollments、转化 goals，以及入站触发器 webhook get|configure|rotate
• 使用 templates localizations set|sync 进行模板 AI／手动本地化
• 集成：catalog、connect（API 密钥／Webhook 密钥提供方；OAuth 提供方需在仪表盘中连接）、list、get、activity、sync、enable-sync／disable-sync、Shopify pixel／enable-pixel，以及 guide
• 使用 audience-syncs list|ad-accounts|create|update|delete|sync 同步 Meta Ads 受众
• 可送达性和发送配置：sender-profiles list|update、tracking settings|update（打开／点击跟踪、严格机器人过滤、归因窗口、双重确认和自动 UTM），以及序列／步骤级别的发送时段
• 使用 shopify settings get|update 设置 Shopify 自动化（浏览放弃、购物车放弃、降价）
• SMS 操作：sms settings、sms send-test、SMS 序列步骤，以及 generate sms
• 使用 sync-rules get|update 设置集成事件到标签的同步规则
• 使用 account notifications get|set 管理个人通知偏好设置
• 产品反馈：用户批准确切载荷后，通过 feedback 向 Sequenzy 团队提交缺失功能报告、错误报告及其他产品反馈（MCP：submit_feedback）

不支持或尚未实现的工作流

即使存在对应的名词，也应将缺少子命令视为不支持。主要的剩余缺口包括：立即发送营销活动（没有“立即发送”命令——请改用时间接近未来的 --at 时间戳来安排发送）、添加或验证发送域名（只能通过 MCP 的 add_sending_domain / verify_sending_domain 或控制面板操作）、创建表单和获取嵌入代码片段（只能通过 MCP 的 create_form / get_form_embed 操作），以及上传图片素材（只能通过 MCP 的 upload_image_asset 操作）。支持批量添加订阅者的方式是使用 sequenzy lists add-subscribers 及其别名 sequenzy lists import，而不是 subscribers add。如果用户想要的功能不受支持，请提议使用 sequenzy feedback "..." --category missing_capability 报告此缺口（MCP：submit_feedback）。发送反馈前，向用户展示你计划发送的确切消息、类别和上下文，不要包含私人账号、订阅者、联系人或营销活动详情，并且只有在用户批准后才能发送。

工作区角色

选择需要特权的工作流前，请检查 sequenzy account 或 MCP get_account。账号密钥权限由所选范围和你当前的工作区角色共同决定；roleRestrictedScopes 会标明该角色受限的范围。canSendLive 表示至少有一种发送工作流可用，并不代表允许使用所有发送工具。

营销人员可以管理营销内容、订阅者、营销活动和序列，包括营销测试发送和取消预约发送。他们不能使用事务性发送，也不能管理团队、账单、集成、API 密钥、发送身份或工作区设置。应选择现有的发件人／回复资料；同时也不允许内联创建新资料。由事务性发送支持的模板及其营销活动、A/B 测试和序列来源，即使通过副本、预览、分享链接、分析和保留的发送历史访问，也仍受保护。请使用权限范围最小且符合条件的角色；不能向营销人员或受限成员授予账单访问权限。

执行模式

1. 首先使用 sequenzy whoami 检查身份验证，或确认已设置 SEQUENZY_API_KEY。
2. 选择与使用场景匹配且范围最小的命令。
3. 执行变更前，验证 ID、收件人邮箱、主题、模板或内容输入。
4. 直接说明 CLI 的限制，不要编造变通方案。
5. 如果 CLI 不支持该工作流，请说明最佳替代方案是使用 Sequenzy 控制面板还是直接使用 API，并提供使用 sequenzy feedback "..." --category missing_capability（MCP：submit_feedback）报告缺失功能的选项。发送反馈前，向用户展示计划发送的确切消息、类别和上下文，排除私密的账户、订阅者、联系人和营销活动详情，并且只在用户批准后发送。
6. 创建、检查或安排营销活动、序列、模板或公司时，如果用户可能想要查看或编辑，请提供工具/CLI 输出中 url、previewUrl 或 appUrls 的控制面板 URL。如有需要，使用 sequenzy urls 或 MCP get_app_urls 生成。
7. 破坏性命令（delete、delete-variant、cancel-invitation、revoke、suppressions remove 等）会提示确认。执行前，告知用户确切操作及资源（ID 和名称），并针对该项操作取得明确批准。只有获得批准后，才可传入 --yes（或 -y）；非 TTY 的 Agent 和 CI 运行需要此参数才能跳过提示。绝不要使用 --yes 绕过用户尚未确认的操作。
8. 将 API 密钥、Webhook 签名密钥和其他一次性凭据视为敏感输出。不要在聊天、日志、工单或公开记录中粘贴原始密钥值。将其保存到用户批准的安全位置，例如密码管理器、密钥存储、加密文件或版本控制之外的本地 .env 文件；否则请对其脱敏，并仅报告保存位置和简短指纹。
9. 指出影响实际运行的实现注意事项，例如 whoami 使用缓存的本地身份验证状态、序列创建同时支持 --goal 和显式步骤模式、显式折扣步骤需要 Stripe 才能激活、生成的序列最多包含 10 封邮件、当前后端中 campaigns test 是桩式成功路径，以及条件邮件内容需要使用区块 JSON 而非原始 HTML。

控制面板 URL

如果已设置 SEQUENZY_APP_URL，请将其用作控制面板的基础 URL；否则默认使用 https://sequenzy.com。

优先使用 CLI/MCP 结果返回的实际 URL：

• 序列编辑器：/dashboard/company/{companyId}/sequences/{sequenceId}
• 营销活动编辑器：/dashboard/company/{companyId}/campaign/{campaignId}
• 营销活动预览/审核：/dashboard/company/{companyId}/campaign/{campaignId}?step=review
• 模板/邮件编辑器：/dashboard/company/{companyId}/emails/{emailId}
• 设置：/dashboard/company/{companyId}/settings
• 设置标签页：/dashboard/company/{companyId}/settings?tab={tab}

常用设置标签页包括 domain、tracking、localization、integrations、events、tags、goals、sync-rules、api-keys、widgets 和 team。

参考资料

• references/command-reference.md：准确的命令格式、环境变量、行为和注意事项。
• references/use-cases.md：最常见 Agent 任务的决策树和示例。