邮件插件开发文档 | DM Hub API 文档

邮件插件简介

发布版本：1.88

不同的客户的邮件供应商可能都不同，DMHub支持通过插件形式发送邮件。您可以通过插件满足系统现有所有功能，比如群发邮件，自动流程发送邮件，测试发送邮件，发送量发送速率管控等等。做到这些您的插件需要提供两个接口： 1.群发邮件接口 2.创建模版接口以及调用DMHub的发送邮件回执接口以完成发送状态上报。

安全说明

由于DMHub可能是通过公网访问邮件插件的接口，因此需要一定的安全校验。目前插件支持两种安全校验。

1.生成签名： DMHub在请求插件接口时会带有以下parameters

    POST ${url}/email/batch?appId=${appId}&timestamp=${timestamp}

parameters说明

名称	类型	描述	实例
url	String	在邮件插件平台中配置的插件服务地址	http://localhost:1234/
appId	String	在邮件插件平台中配置的appId	cl001116d62
timestamp	String	当前时间，格式为yyyyMMddHHmmss，时间为UTC时间	20210308131501

2.阿里云api gateway：

该方式只需要在插件平台正确的配置阿里云网关的appKey和appSecret即可。详细请见阿里云网关

插件接口说明

1.群发邮件接口

格式

POST ${url}/email/batch

请求体

DMHub的邮件有模版的概念，模版内以客户的属性或身份作为变量，通过模版+属性变量的方式来达到每个人收到的邮件都可能不一样的效果。而有些客户认为的敏感信息是不会存储在DMHub 中，比如手机号码、家庭住址等等，而插件可以获取到这些敏感信息。这时候就需要在插件内部组装模版+变量。

{
  "templateId": "123",
   "batchId": "1223",
   "audienceIdType": "email",
   "domain":"dmhub.com.cn",
   "data": [
       {
           "_audienceId": "xxxx@convertlab.com",
           "var1": "1234556" ,
           "name": "Michael",
           "其他变量": "其他变量的值",
           "attr": {
               "attr1": "1234",
               // 其他自定义字段
           }
       }
   ]
}

参数说明

名称	类型	描述
templateId	String	邮件模版ID
batchId	String	发送批次号
audienceIdType	String	触达类型
data	List	参数列表
_audienceId	String	触达ID
var1	String	自定义的变量名称
attr	Map	客户自定义属性
name@3	String	客户姓名

接口返回

插件内部发送邮件最好是异步发送，通过一些消息组件做到降低接口延迟，提高并行度。

在接口处理成功时需要返回

{"code":"SUCCESS"}

在接口处理失败后需要按照标准错误格式返回，例如：

{"error":{"code":"400001","message":"invalid signature"}}

2.创建邮件模版接口

格式

POST ${url}/email/template

请求体

{
	"templateId": "123",
	 "templateContent": "test send",
	 "emailType": "notify/market",
	 "subject": "convertlab营销邮件",
	 "fromName": "wyp",
	 "aliasName": "王先生"
}

参数说明

名称	类型	描述
templateId	String	邮件模版ID
templateContent	String	内容
emailType	String	类型notify=通知，market=营销
subject	String	标题
fromName	String	发送方
aliasName	String	别名

接口返回

在接口处理成功时需要返回

{"code":"SUCCESS"}

在接口处理失败后需要按照标准错误格式返回，例如：

{"error":{"code":"400001","message":"invalid signature"}}

3.发送邮件插件回执

格式

POST http://api.xxx.cn/v1/sms/report?access_token={access_token}

请求体

   {
      "type":"email",
      "reports":
           [{
                    "audienceId": audienceId,
                    "batchId"   : batchId,
                    "receiveDate" : "2019-04-28 16:28:34",
                    "event "      : "email_delivered",
                    "receiver "   : "接受者邮件", //可选
                    "errorMessage": "接收成功",
                    "errorCode"   : "400"
             }]
   }

参数说明

名称	类型	描述
type	String	回执类型
reports	List	回执业务体
audienceId	String	触达ID
batchId	String	批次id
receiveDate	Date	收件时间
event	String	事件
receiver	String	收件人
errorMessage	String	失败原因
errorCode	String	失败编码

接口返回

在接口处理成功时需要返回

{"code":"SUCCESS"}

在接口处理失败后需要按照标准错误格式返回，例如：

{"error":{"code":"400001","message":"invalid signature"}}

系统通知

发布版本：2.5

系统通知邮件可以支持通过插件发送，实现邮件通道的定制。该功能的实现需要开启相应的功能开关。

邮件通知接口

格式

POST ${url}/email/plugin/send

请求体

发送系统通知需要您的插件具备模版类型。通知模版示例、模版类型和对应的变量请下载文件进行查看。模版下载

例如：租户即将到期通知 { "name": "12", "tenantId": "10113", "dateEnd": "2022-03-10", "emailTemplateType": "TenantExpiring" }

参数说明

名称	类型	描述
name	String	租户名称
tenantId	int	租户Id
dateEnd	String	到期时间
emailTemplateType	String	模版类型