MailHub

主动给用户发送

C2S POST /bp/user/me/mail_hub/send

S2S POST /bp/server/user/{user_id}/mail_hub/send

接口功能：主动给用户发送邮件

请求头部参数 (Headers)：

参考接入 BytePower

请求体

• content-type: "application/json"

• 描述：邮件发送所需信息

• 参数类型

  名字	类型	示例	是否必填	描述
  name	string	download	true	console 配置的 email strategy 名称
  email_to	string	example@example.com	false	收件人邮箱，不传或者为空，会使用用户绑定的邮箱
  custom_variables	map	{"foo": "bar"}	false	自定义变量，用于邮件内容模板渲染

• 模板语法：

  • 如果在接口中传入了 "custom_variables": {"foo": "bar"}，则在邮件模板中可以通过 {{.CustomVariables.foo}} 读取并显示。
  • 特殊系统变量 {{.TrackingPixelURL}} 或 {{.CustomVariables.TrackingPixelURL}} 可用于追踪邮件打开情况（通常嵌入为 <img> 标签的 src）。

• 请求体示例：

{
  "name": "download",
  "email_to": "example@example.com",
  "custom_variables": {
    "foo": "bar"
  }
}

响应

• HTTP 状态码：200

  描述：成功 响应示例：

{}

HTTP 状态码：4xx 描述：错误 响应示例：

{
  "error": {
    "error_type": "invalid_parameter",
    "message": "xxxxx"
  }
}

error_type：

• invalid_parameter（参数错误）
• mail_hub.api_email_invalid (enable_api_email 为 false 且发送接口 email_to 不为空)
• mail_hub.email_to_invalid (email_to 邮件地址校验失败)
• mail_hub.send_duplicate （该策略已经还在发送中）

邮件打开追踪（Tracking Pixel）

GET /bp/res/i.gif

接口功能：通过 1x1 透明 GIF 追踪邮件是否被打开。该接口无需鉴权，嵌入邮件 HTML 中作为 <img> 标签的 src，用户打开邮件时自动加载。

请求参数（Query String）

名字	缩写	类型	是否必填	描述
email	e	string	是	收件人邮箱
message_id	mid	string	是	邮件消息 ID，由发送时生成
user_id	u	string	否	用户 ID，缺省时根据 email 自动查找

注意

e 和 mid 同时存在时才会上报打开事件。缺少任一参数仅返回图片，不记录事件。

请求示例

GET /bp/res/i.gif?e=user%40example.com&u=U123&mid=m1a2b3c

响应

• HTTP 状态码：200
• Content-Type: image/gif
• 响应体：1x1 透明 GIF（43 bytes）

响应头包含缓存禁止指令，确保每次打开邮件都会触发请求：

Cache-Control: no-store, no-cache, must-revalidate, max-age=0
Pragma: no-cache

上报事件

当 e 和 mid 均存在时，上报 email_operation 事件：

{
  "email": "user@example.com",
  "status": "open",
  "extra": "{\"email\":\"user@example.com\",\"user_id\":\"U123\",\"message_id\":\"m1a2b3c\",\"user_agent\":\"...\",\"ip\":\"...\"}",
  "message_id": "m1a2b3c"
}

记录用户活跃

S2S POST /bp/server/user/{user_id}/account/record_activity

接口功能：记录用户最近活跃时间（last_login_time），供 web_paid_no_login trigger 判定使用。

请求头部参数 (Headers)：

参考接入 BytePower

响应

• HTTP 状态码：200

  描述：成功 响应示例：

{}