一、应用场景
邮件集成服务是物联网平台提供的用于客户自定义邮件发送通道的功能。客户可以使用邮件集成服务实现将物联网平台需要发送邮箱的业务通过客户指定的第三方邮件平台进行发送。可用于以下业务场景:
- 客户已有自建的统一的邮件系统,需要将物联网平台的邮件通过客户自建的邮件系统发送;
- 客户希望根据不同用户地区、用户邮箱类型采用不同的邮件发送提供商的邮件发送服务;
二、功能说明
客户在物联网平台管理台【应用中心->集成->邮件服务->邮件配置】中开启第三方邮件平台功能,并填写URL与Token。其中URL是用来接收物联网平台发送的邮件数据接口,URL必须为HTTPS接口;Token用作验证URL有效性。在物联云平台产生一条E-mail后,将使用第三方厂商平台发送E-mail,物联云平台会将E-mail POST到第三方厂商邮件平台,最终由第三方厂商平台将E-mail发出。
邮件主要包含以下几种:
用户注册激活
用户重置密码
用户更换手机号
邮件注册激活码
邮件找回密码验证码
文件邮件
成员报警邮件
成员找回邮件
三、前提条件
- 参考管理台操作手册《应用中台操作手册》,在管理台【应用中心->集成->邮件服务->邮件配置】中选择使用第三方厂商邮件;
- 在管理台正确配置第三方邮箱URL、Token;
- 第三方平台在配置的URL上实现验证接口和接收邮件内容的接口;
- 点击【验证】按钮进行第三方优先系统对接验证,验证完成后点击【保存】按钮;
四、关键流程
4.1. 第三方邮件系统对接流程
流程说明: 成员在管理台进行邮件配置,填写第三方邮件系统URL和Token,进行验证和保存。验证通过后,物联网平台的邮件将发送到配置的第三方邮件系统进行发送。
4.2 邮件发送流程
流程说明: 邮件发送者根据不同场景向物联网中台发起 发送邮件 请求,物联网中台收到请求后根据请求信息找出企业下设置第三方邮件系统的地址以及调用凭证,利用邮件系统地址和调用凭证向第三方邮件系统发送邮件。
五、API列表
5.1 验证URL有效性
接口描述
在物联网平台配置完URL和Token后,物联网平台会通过配置的URL和Token向第三方厂商发起验证。
验证URL有效性: 需要符合以下规范,且由外部系统实现,其中请求地址可自定义,调用成功判断标准为HTTP响应状态码为200且返回对应的返回值。
请求方式
GET
请求地址
由用户在物联网平台管理台配置的URL
请求头
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
Content-Type | true | String | application/json |
请求参数
名称 | 参数位置 | 必填 | 类型 | 备注 |
---|---|---|---|---|
timestamp | query | true | string | 时间戳 |
signature | query | true | string | 物联网平台加密签名; 1.签名算法:signature=SHA1(corpId + Token + timestamp), 2.corpId是企业在物联网平台的企业ID 3.Token由客户在物联网平台管理台填写 |
验证方法说明:第三方邮件系统通过检验signature对GET请求验证,若自身通过签名算法【SHA1(corpId + Token + timestamp) 】加密得到的数据与请求的signature一致,则返回HTTP状态码 200 OK设置有效,否则设置无效,返回错误消息,统一按照返回消息格式响应。
请求示例:
GET http://tac.com/email/iot?tumestamp=14342587903&signature=37975ef199e20f8b04fbdba750547e42b2e604f3
返回参数说明
校验成功返回http 状态码 200。
返回示例:
http status code :200
错误返回参数说明
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
err_code | 是 | Integer | 错误码 |
err_msg | 是 | String | 错误信息 |
错误返回示例:
{
"err_code":"4031003",
"err_msg":"Token验证失败"
}
错误码:
错误码 | 描述 |
---|---|
4031003 | 不合法的调用凭证 |
4041010 | 企业ID不合法 |
5.2 发送邮件
接口描述
物联网根据邮件模板生成E-Mail,若管理台邮件配置为【使用第三方厂商邮件】,则将内容POST到管理台填写的URL中,内容为请求Body,第三方厂商负责将E-mail发出。此接口定义物联网平台发出E-mail格式;
发送邮件: 需要符合以下规范,且由外部系统实现,其中请求地址可自定义,调用成功判断标准为HTTP响应状态码为200且返回对应的返回值。
请求方式
POST
请求地址
由用户在物联网平台管理台配置的URL
请求头
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
Content-Type | true | String | application/json |
请求参数
名称 | 参数位置 | 必填 | 类型 | 备注 |
---|---|---|---|---|
subject | body | true | String | 要发送的邮件主题 |
to | body | true | String | 接收者E-mail地址,多个地址以英文逗号分隔, 如:example1@xlink.cn,example2@xlink.cn |
email_param | body | true | Object | 邮件参数,具体格式参考本文档附录一 |
email_param.type | body | true | enum | 邮件参数类型,参考5.3.1 邮件参数类型说明 |
email_param.code | body | false | String | 验证码 |
email_param.hour | body | false | String | 验证码有效期, 单位 h |
plain_email | body | false | String | 邮件原文内容 |
验证方法说明:第三方邮件系统通过检验signature对GET请求验证,若自身通过签名算法【SHA1(corp_id + Token + timestamp) 】加密得到的数据与请求的signature一致,则返回HTTP状态码 200 OK设置有效,否则设置无效,返回错误消息,统一按照返回消息格式响应。
请求示例:
{
"subject":"用户注册邮件",
"to":"example1@xlink.cn,example2@xlink.cn",
"email_param":{
"type": 1,
"code":"87d1",
"hour": 2,
},
"plain_email":"邮件内容"
}
返回参数说明
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
err_code | 是 | Integer | 错误码 |
err_msg | 是 | String | 错误信息 |
返回示例:
{
"err_code":"4031003",
"err_msg":"Token验证失败"
}
错误码:
错误码 | 描述 |
---|---|
0 | 发送成功 |
4002011 | email内容不合法 |
4002012 | email接收者地址不合法 |
5.3 附录一:邮件参数说明
5.3.1 邮件参数类型说明
Type枚举值 | 备注 |
---|---|
1 | 用户注册激活 |
2 | 用户重置密码 |
3 | 用户更换手机号 |
5 | 邮件注册激活码 |
6 | 邮件找回密码验证码 |
7 | 文件邮件 |
8 | 成员告警信息 |
9 | 成员找回密码 |
5.3.2 各类型邮件参数描述
5.3.2.1 用户注册激活
{
"type": "1",
"url": "用户激活链接地址",
"hour": "链接有效期"
}
5.3.2.2 用户重置密码
{
"type": "2",
"url": "用户重置密码链接地址",
"hour": "链接有效期"
}
5.3.2.3 用户更换手机号
{
"type": "3",
"code": "验证码",
"hour": "验证码有效期"
}
5.3.2.4 邮件注册激活码
{
"type": "3",
"code": "验证码",
"hour": "验证码有效期"
}
5.3.2.5 邮件找回密码验证码
{
"type": "5",
"hour": "激活码有效期"
}
5.3.2.6 文件邮件
{
"type": "7",
"download_url": "文件下载地址"
}
5.3.2.7 成员报警邮件
{
"type": 8,
"username": "成员的名称",
"corporation": "报警企业名称",
"productName": "报警设备所属产品",
"time": "成员找回密码时间",
"email": "成员的邮件地址"
}
5.3.2.8 成员找回邮件
{
"type": 9,
"url": "找回密码链接",
"username": "成员的名称",
"email": "成员的邮件地址",
"verifycode": "成员找回密码验证码",
"time": "成员找回密码时间",
"hour": "成员找回密码链接有效期"
}