邮件任务

当前状态：Beta

邮件任务用于在你已经选定达人、已经掌握规范的平台频道标识，或已经有获批外部邮箱地址后，管理 NoxInfluencer 内的 email-task 记录。

适合什么场景

• 你要创建或查看邮件任务
• 你要管理某个任务的收件人、发件人设置和已确认内容
• 你要通过 SaaS 支持的 Excel 模板导入收件人
• 你要使用 NoxInfluencer 返回的达人标识、已知平台频道标识或获批外部邮箱添加收件人
• 你要在发送或定时前，把已确认的 brief 或文件附加到邮件任务
• 你要在富文本邮件正文中嵌入已确认的公开图片
• 你要按历史联系、CRM、合作、资源池或其他邮件任务状态过滤收件人
• 你要管理邮件任务协作者及其成员管理权限
• 你要在确认收件人、发件人、发送时间和内容后发送或定时邮件任务

当前 beta 范围

• 查看 email tasks 和 drafts
• 通过 task_id 查看单个任务
• 创建、更新、复制或删除邮件任务
• 添加、替换和查看任务收件人
• 下载收件人导入模板，并通过 Excel 导入收件人
• 删除或清空未发送任务的收件人
• 保存和查看任务级收件人隐藏/去重过滤条件
• 查看可用收件人过滤选项和可用于过滤的邮件任务
• 查看、替换、添加或移除任务协作者
• 保存任务内容、更新发件人设置
• 发送、定时或取消邮件任务
• 查看、保存和应用邮件内容模板
• 查看、替换和删除邮件商品卡
• 查看、上传、下载和删除任务附件
• 上传公开图片，用于已确认的富文本 html_body
• 查看邮件任务报告、团队汇总和团队明细指标

收件人标识

添加或替换收件人时，根据你已经掌握的信息选择一种身份输入：

creator_id 不是数据库记录 ID。它是 NoxInfluencer 根据平台和平台侧 channel_id 生成的稳定、不透明达人标识。直接复用返回值，不要尝试解码或自行构造。

达人搜索和达人读取使用不同的响应字段名：搜索结果是 data.items[].id，达人详情、分析等读取结果是 data.creator_id。把任意一种返回值放进收件人对象的 creator_id 字段即可。

最小 body 示例：

{
  "recipients": [
    {"creator_id": "<creator_id>"}
  ]
}

{
  "recipients": [
    {"platform": "youtube", "channel_id": "UC..."}
  ]
}

{
  "recipients": [
    {"email_address": "[email protected]", "title": "Creator"}
  ]
}

不要在同一个收件人对象中把 creator_id 与 platform、channel_id 或 email_address 混用。只提供 channel_id 时必须同时提供 platform。达人主页 URL、handle 和达人名称不能直接作为邮件收件人标识；先通过达人搜索或读取解析目标，再使用返回的不透明达人标识。

通过 creator_id 或 platform + channel_id 添加达人，不代表该达人当前一定可发送。has_email=false 的达人可以保留在任务中，但当前不可发送；需要一份立即可发送的候选名单时，在搜索阶段使用 --has_email true。

安全执行规则

• 很多 email 命令是 JSON-first，需要使用 --body-file
• 写操作默认 dry-run；只有在你确认具体对象和动作后才使用 --force
• NoxInfluencer 平台邮件优先使用搜索结果 data.items[].id 或达人读取结果 data.creator_id 作为收件人对象里的 creator_id
• 只有已经掌握规范平台频道标识时，才直接使用 platform + channel_id
• 只有已有外部邮箱地址时才使用 email_address；不要为了把达人加入平台邮件任务而先运行 creator contacts
• 执行 email send 或 email schedule 前，需要先读回任务和收件人
• 发送或定时前必须确认收件人、发件人、必要时的发送时间，以及内容已经获批
• 执行 email content save 后，用 email get <task_id> 读回任务，并确认返回的主题、HTML 正文和纯文本正文与已批准内容一致
• email schedule 的 plan_send_at 必须是带整点 timezone offset 的 ISO 8601 时间，例如 Z、+08:00 或 -05:00
• email get 返回任务列表口径的 send_count、open_count 和 reply_count 聚合值；需要去重收件人与当前主轮次指标时使用 email report
• email report 使用 unique_recipient_count 表示任务级去重收件人数，并单独返回当前主轮次的送达、打开和回复指标
• 邮件报告会区分 email tracking reply_count、达人级 replied_creator_count 和入站消息 inbound_message_count
• 团队报告筛选使用 SaaS 团队成员 uid，不是 Gmail 或企业邮箱账号
• 商品卡使用商品中心的 product_collect_id
• 任务发送后仍可查看商品卡，但 replace 和 delete 仍只适用于草稿阶段
• 收件人过滤使用 email recipients filter options 返回的公开 body patches，不要自己猜 SaaS 原始字段名
• 协作者命令使用 SaaS 团队 user_uid；如果不确定有效成员，先查看 collaborators list
• 收件人导入支持不超过 8MB 的 .xls 或 .xlsx 文件；请使用下载的 SaaS 模板，不要自行猜测表格列
• 只有邮件任务尚未进入有效发送流程时，才能导入收件人
• 附件上传使用 --file，不是 --body-file
• 邮件任务最多支持 1 个附件，最大 10MB；危险可执行文件或脚本扩展名会被拒绝
• 上传或删除附件会取消该任务已有的定时发送。修改附件后，需要先读回任务，再确认最终附件状态后重新定时。
• 富文本公开图片与私有附件是两条不同路径：file image upload 返回可放入 html_body 的公开 file_url，邮件附件仍是需要授权的任务文件

关键命令

构建任务、协作者、收件人、过滤条件、内容、发件人、模板或商品卡 body 前，先查看 schema；收件人 body 同时遵循本页上面的身份输入规则：

noxinfluencer schema "email create"
noxinfluencer schema "email collaborators add"
noxinfluencer schema "email recipients add"
noxinfluencer schema "email recipients import-file"
noxinfluencer schema "email recipients filter update"
noxinfluencer schema "email content save"
noxinfluencer schema "email products replace"
noxinfluencer schema "email attachments upload"
noxinfluencer schema "email attachments download"
noxinfluencer schema "email attachments delete"
noxinfluencer schema "file image upload"

发送前先读取任务状态：

noxinfluencer email list --keyword shoes --page_size 10
noxinfluencer email drafts --page_size 10
noxinfluencer email get <task_id>
noxinfluencer email recipients list <task_id>

管理收件人隐藏和去重过滤前，先读取当前支持的选项：

noxinfluencer email recipients filter options
noxinfluencer email recipients filter tasks
noxinfluencer email recipients filter get <task_id>
noxinfluencer email recipients filter update <task_id> --body-file recipient-filter.json --force

已经确认以表格为收件人来源时，使用当前 SaaS 模板导入：

noxinfluencer email recipients import-template --language cn --output email-recipient-template.xlsx
noxinfluencer email recipients import-file <task_id> --file recipients.xlsx --force

按团队成员 user_uid 管理任务协作者：

noxinfluencer email collaborators list
noxinfluencer email collaborators list <task_id>
noxinfluencer email collaborators add <task_id> --body-file collaborator.json --force
noxinfluencer email collaborators remove <task_id> --body-file collaborator.json --force

在已经有确认过的收件人和内容后，再组装邮件任务。执行写操作前，先检查 recipients.json 使用了正确且互不冲突的身份字段。

noxinfluencer email create --body-file email-task.json --force
noxinfluencer email recipients add <task_id> --body-file recipients.json --force
noxinfluencer email recipients delete <task_id> --body-file recipient-delete.json --force
noxinfluencer email content save <task_id> --body-file content.json --force
noxinfluencer email get <task_id>
noxinfluencer email sender update <task_id> --body-file sender.json --force

任务已存在后、发送或定时前，再附加已确认文件：

noxinfluencer email attachments list <task_id>
noxinfluencer email attachments upload <task_id> --file brief.pdf --force
noxinfluencer email attachments download <task_id> <attachment_id> --output ./brief.pdf
noxinfluencer email attachments delete <task_id> <attachment_id> --force

要在已确认的富文本正文中插入图片，请单独上传，并把返回的 file_url 写入 html_body：

noxinfluencer file image upload --file hero.jpg --force

只有读回任务并确认无误后，才发送或定时：

noxinfluencer email send <task_id> --force
noxinfluencer email schedule <task_id> --body-file schedule.json --force
noxinfluencer email cancel <task_id> --force

发送后分析使用邮件报告：

noxinfluencer email report <task_id>
noxinfluencer email team-summary --task-ids <task_id>,<task_id>
noxinfluencer email team-breakdown --task-ids <task_id>,<task_id> --page_size 20

商品记录已存在于 商品中心 后，再添加商品卡：

noxinfluencer email products list <task_id>
noxinfluencer email products replace <task_id> --body-file email-products.json --force
noxinfluencer email products delete <task_id> <email_product_id> --force

当前边界

• 该工作流只操作 NoxInfluencer 邮件任务，不操作外部邮箱平台
• 它不会代你撰写触达或谈判文案
• 平台邮件不要求先获取可见联系方式；只有需要可见 / 可导出的外部联系信息时，才使用 达人触达
• 立即发送没有单独 preview endpoint；确认执行前应先读回任务状态和收件人
• 商品卡 replace 会替换任务 primary project 上的当前所有商品卡，最多支持 5 个商品 collect IDs
• 任务列表聚合值与报告指标回答的是不同问题，不要把 email get 和 email report 的字段当成相同收件人范围或轮次口径直接比较
• email recipients filter update 会把过滤条件保存到任务 primary project；{} 表示清空全部收件人过滤条件
• email recipients filter tasks 只列出可用于隐藏“已在其他邮件任务中”的收件人的任务
• email content save 会写入任务 primary project 的最新内容行，服务端会通过读取内容行做保存后校验；如果读回内容不一致，不要把该任务视为可发送
• email collaborators replace 会重置整组协作者；如果只是新增或移除一个成员，不要用 replace
• 协作者 remove 会保留任务 owner 和其他非 owner 协作者
• 发件人、模板和权限行为可能依赖你的账号配置
• 附件属于 NoxInfluencer 邮件任务 primary project，不是外部邮箱或外部邮件平台里的文件
• 富文本公开图片 URL 不是任务附件，也不能替代私有附件工作流
• 附件上传和删除可能改变定时发送状态；修改附件后，不要假设之前的定时仍然有效

推荐下一步

• 达人触达
• CRM
• 商品中心
• 组织活动工作流