MailHub

概览

MailHub 是 BytePower 的邮件自动化模块，支持根据用户行为和状态，按策略自动发送邮件。主要能力包括：

• 策略驱动发送：通过 Console 配置邮件策略（strategy），定义触发条件（trigger）、邮件内容模板（content）和发送间隔。
• 手动触发发送：通过 API 主动给指定用户发送邮件。
• 自定义变量：发送时传入自定义变量，用于邮件模板渲染。
• 邮件打开追踪：通过 Tracking Pixel（1x1 透明 GIF）统计邮件打开率。

Trigger 类型

MailHub 通过 trigger 来识别不同用户群体，决定是否发送邮件。目前支持以下 trigger 类型：

trigger type	描述
web_sub_no_change	Web 付费用户，未重置密码
web_sub_and_change	Web 付费用户，已重置密码
web_no_sub	Web 未付费用户
user_manual	用户手动触发，不设条件，调用 API 即发送
web_paid_no_login	Web 平台付费但付费后未登录使用的用户

web_paid_no_login

该 trigger 用于识别通过 Web 平台（Stripe、PayPal、Braintree、Wellhub、Paddle、FunnelFox）付费后，但从未在客户端实际登录使用产品的用户。适用于发送引导邮件提升 app 使用率和留存。

判定逻辑：

1. 用户在 Web 支付平台存在至少一笔购买记录（取首次购买时间）。
2. 用户的 last_login_time（最近登录时间）不晚于首次购买时间，即付费后未再登录。

TIP

last_login_time 通过 record_activity 接口更新。如果用户从未登录过（last_login_time 为零值），也视为"付费后未登录"。

主动发送邮件

通过 API 调用 send 接口，可以主动给用户发送邮件。

基础用法

{
  "name": "download",
  "email_to": "user@example.com"
}

• name：Console 配置的 email strategy 名称（必填）。
• email_to：收件人邮箱（可选），不传则使用用户绑定的邮箱。

自定义变量

通过 custom_variables 传入自定义变量，在邮件模板中使用 {{.CustomVariables.xxx}} 引用：

{
  "name": "welcome",
  "custom_variables": {
    "app_name": "MyApp",
    "inviter": "Bob"
  }
}

模板示例：

Hello {{.UserName}}, welcome to {{.CustomVariables.app_name}}!
Your inviter is {{.CustomVariables.inviter}}.

系统变量

以下变量由系统自动注入，无需通过 custom_variables 传入：

变量	描述
{{.UserName}}	用户名
{{.Email}}	用户邮箱
{{.SessionToken}}	用户 session token
{{.TrackingPixelURL}}	邮件打开追踪图片 URL
{{.MessageID}}	邮件消息唯一 ID
{{.CustomVariables.TrackingPixelURL}}	同 {{.TrackingPixelURL}}
{{.CustomVariables.MessageID}}	同 {{.MessageID}}

接口详情请参考 API 文档。

邮件打开追踪

MailHub 支持通过 Tracking Pixel 统计邮件打开率。

原理

邮件发送时，系统自动生成一个包含追踪参数的 1x1 透明 GIF URL，注入到模板变量 {{.TrackingPixelURL}}。用户打开邮件时，邮件客户端加载这张图片，触发 email_operation 事件记录。

模板集成

在 HTML 邮件模板底部嵌入：

<img src="{{.TrackingPixelURL}}" width="1" height="1" alt="" style="display:block;" />

注意

• Tracking Pixel 仅在 HTML 格式的邮件中有效。
• 部分邮件客户端（如 Outlook 某些版本）默认不加载外部图片，此时无法追踪。
• 追踪数据为统计参考，不保证 100% 准确。

追踪参数

生成的 Tracking Pixel URL 包含以下参数：

参数	描述
e	收件人邮箱
u	用户 ID
mid	邮件消息 ID

事件数据

每次邮件被打开，上报 email_operation 事件，包含：

• email：收件人邮箱
• status：open
• message_id：邮件消息 ID
• extra：JSON 字符串，包含所有追踪参数以及 user_agent 和 ip

Console 配置

MailHub 的策略配置在 Console 的 MailHub 页面完成，主要配置项包括：

• Strategy Name：策略名称，API 调用时使用。
• Trigger Type：触发类型，决定哪些用户会收到邮件。
• Content：邮件内容模板，支持 HTML 和纯文本格式，可使用模板变量。
• Interval：发送间隔，避免频繁打扰用户。
• Enable API Email：是否允许通过 API 指定收件人邮箱（默认关闭，仅使用用户绑定邮箱）。