第三方短信邮件平台接口规范 - 智能用户增长

为了在QA使用将第三方短信邮件平台，当您进行第三方短信邮件平台开发时，需要遵守下面的公共参数和各功能模块接口规范。

公共参数

名称	类型	是否必须	描述
AccountId	String	是	QA组织创建者账户ID。用户配置三方接口时QA测会显示出来，同时会返回签名秘钥，用于签名校验，请妥善保存。第三方需要根据该ID映射自己平台内账户。
Signature	String	是	签名结果串，关于签名的计算方法，请查阅对应签名方式的签名机制。
SignatureMethod	String	是	签名方式，目前支持 HMAC-SHA1。
Timestamp	String	是	请求的时间戳。日期格式按照ISO8601标准表示，并需要使用UTC时间。格式为yyyy-MM-ddThh:mm:ssZ。例如：2015-11-23T04:00:00Z（为北京时间2015年11月23日12点0分0秒）。
SignatureNonce	String	是	唯一随机数，用于防止网络重放攻击。不同的请求要使用不同的随机数值。您可以使用UUID（随机串），也可以自定义。

添加邮件模板接口

接口描述	添加邮件模板
URL	${prefix}/email/emailTemplate
请求方式	post
请求类型	application/json
返回类型	/
参数名	数据类型	参数类型	是否必填	说明
1.model	object:AddEmailTemplateModel	body	是	模板信息。
1.1.remark	string		是	模板申请说明。请在申请说明中描述您的业务使用场景，长度为1~100个字符。
1.2.senderName	string		是	发送人名称。
1.3.templateContent	string		是	模板内容，限制28KB。
1.4.templateName	string		是	模板名称，长度为1~30个字符。
1.5.templateSubject	string		是	模板标题。
状态码	描述		说明
200	OK		请求成功。
201	Created		请求成功，并且创建了资源。
401	Unauthorized		请求未经授权。
404	Forbidden		请求被拒绝。
404	Not Found		请求的资源不存在。
返回属性名	类型		说明
1.platformName	string		服务方名称，与接口配置时填写的接口名称一致。
2.code	string		请求状态码，返回OK代表请求成功，其他为错误码。
3.message	string		状态码描述。
4.requestId	string		请求ID。
5.templateCode	string		模板code，用于查看模板申请状态和结果。
示例
请求参数	-d '{"remark":"string","senderName":"string","templateContent":"string","templateName":"string","templateSubject":"string"}'
返回值	{"platformName":"string","code":"string","templateCode":"string","message":"string","requestId":"string"}

修改邮件模板接口

接口描述	修改邮件模板
URL	${prefix}/email/emailTemplate/{templateCode}
请求方式	put
请求类型	application/json
返回类型	/
参数名	数据类型	参数类型	是否必填	说明
1.model	object:UpdateEmailTemplateModel	body	是	模板信息。
1.1.remark	string		否	模板申请说明。请在申请说明中描述您的业务使用场景，长度为1~100个字符。
1.2.senderName	string		否	发送人名称
1.3.templateContent	string		否	模板内容，限制28KB。
1.4.templateName	string		否	模板名称，长度为1~30个字符。
1.5.templateSubject	string		否	模板标题。
状态码	描述		说明
200	OK		请求成功。
201	Created		请求成功，并且创建了资源。
401	Unauthorized		请求未经授权。
403	Forbidden		请求被拒绝。
404	Not Found		请求的资源不存在。
返回属性名	类型		说明
1.platformName	string		服务方名称，与接口配置时填写的接口名称一致。
2.code	string		请求状态码，返回OK代表请求成功，其他为错误码。
3.message	string		状态码描述。
4.requestId	string		请求ID。
5.templateCode	string		模板code，用于查看模板申请状态和结果
示例
请求参数	-d '{"remark":"string","senderName":"string","templateContent":"string","templateName":"string","templateSubject":"string"}'
返回值	{"platformName":"string","code":"string","templateCode":"string","message":"string","requestId":"string"}

邮件模板审核状态查询接口

接口描述	邮件模板审核状态查询
URL	${prefix}/email/emailTemplate/{templateCode}
请求方式	get
请求类型	application/json
返回类型	/
参数名	数据类型	参数类型	是否必填	说明
1.templateCode	string	path	是	模板code。
状态码	描述		说明
200	OK		请求成功。
401	Unauthorized		请求未经授权。
403	Forbidden		请求被拒绝。
404	Not Found		请求的资源不存在。
返回属性名	类型		说明
1.platformName	string		服务方名称，与接口配置时填写的接口名称一致。
2.code	string		请求状态码，返回OK代表请求成功，其他为错误码。
3.createDate	string		模板的创建日期和时间，如：2019-01-08 16:44:13。
4.message	string		状态码描述。
5.reason	string		审核备注。如果审核状态为审核通过或审核中，参数Reason显示为“无审核备注”；如果审核状态为审核未通过，参数Reason显示审核的具体原因。
6.requestId	string		请求ID。
7.templateCode	string		模板code。
8.templateContent	string		模板内容。
9.templateName	string		模板名称。
10.templateStatus	integer(int32)		签名审核状态。0：审核中，1：审核通过，审核失败，请在返回参数Reason中查看审核失败原因。
示例
请求参数	无示例
返回值	{"templateStatus":0,"reason":"string","code":"string","templateName":"string","requestId":"string","templateContent":"string","platformName":"string","templateCode":"string","message":"string","createDate":"string"}

邮件发送接口

接口描述	大量邮件发送
URL	${prefix}/email/sendBatch
请求方式	post
请求类型	application/json
返回类型	/
参数名	数据类型	参数类型	是否必填	说明
1.model	object:SendBatchEmailModel	body	是	邮件发送请求参数。
1.1.accountName	string		是	发信地址。
1.2.addressType	string		是	地址类型。0：为随机账号，1：为发信地址。
1.3.clickTrace	string		否	0（默认）：为关闭数据跟踪功能，1：为打开数据跟踪功能。
1.4.fromAlias	string		否	发信人昵称，长度小于15个字符。例如：发信人昵称设置为”小红”，发信地址为test@example.com，收信人看到的发信地址为"小红"<test@example.com>。
1.5.subject	string		否	邮件主题。
1.6.htmlBody	string		否	邮件html正文，限制28KB。
1.7.limit	integer(int64)		否	发送人数限制。
1.8.outId	string		否	外部流水扩展字段，标签于统计。
1.9.receiversUrl	string		是	OSS上传的收件人地址文件URL。
1.10.templateCode	string		否	预先创建且通过审核的模板code，与fromAlias、subject、htmlBody参数互斥，同时填写以模板内容为准。
状态码	描述		说明
200	OK		请求成功。
201	Created		请求成功，并且创建了资源。
401	Unauthorized		请求未经授权。
403	Forbidden		请求被拒绝。
404	Not Found		请求的资源不存在。
返回属性名	类型		说明
1.bizId	string		发送回执ID，可根据该ID在接口QuerySendDetails中查询具体的发送状态。
2.platformName	string		服务方名称，与接口配置时填写的接口名称一致。
3.code	string		请求状态码，返回OK代表请求成功，其他为错误码。
4.message	string		状态码描述。
5.requestId	string		请求ID。
示例
请求参数	-d '{"accountName":"string","addressType":"string","clickTrace":"string","fromAlias":"string","htmlBody":"string","limit":0,"outId":"string","receiversUrl":"string","subject":"string","templateCode":"string"}'
返回值	{"bizId":"string","platformName":"string","code":"string","message":"string","requestId":"string"}

邮件发送明细查询接口

接口描述	邮件发送明细查询
URL	${prefix}/email/sendDetails
请求方式	post
请求类型	application/json
返回类型	/
参数名	数据类型	参数类型	是否必填	说明
1.model	object:QuerySendDetailModel	body	是	邮件发送明细查询请求参数。
1.1.outId	string		是	外部流水扩展字段，可根据该ID在接口QuerySendDetails中查询具体的发送状态。
1.2.currentPage	integer(int64)		是	分页查看发送记录，指定发送记录的的当前页码。
1.3.pageSize	integer(int64)		是	分页查看发送记录，指定每页显示的短信记录数量。取值范围为1~1000。
1.4.startDate	string		是	起始时间，时间不能早于30日，格式yyyy-MM-dd HH:mm。
1.5.endDate	string		是	结束时间，和起始时间跨度不能超出30天，格式yyyy-MM-dd HH:mm。
状态码	描述		说明
200	OK		请求成功。
201	Created		请求成功，并且创建了资源。
401	Unauthorized		请求未经授权。
403	Forbidden		请求被拒绝。
404	Not Found		请求的资源不存在。
返回属性名	类型		说明
1.platformName	string		服务方名称，与接口配置时填写的接口名称一致。
2.code	string		请求状态码，返回OK代表请求成功，其他为错误码。
3.message	string		状态码描述。
4.requestId	string		请求ID。
5.sendDetailDTOs	array:EmailSendDetailDTO		发送明细。
5.1.accountName	string		发信地址。
5.2.code	string		返回投递错误码。
5.3.message	string		投递详情信息。
5.4.outId	string		外部流水扩展字段。
5.5.receiveTime	string		接收日期和时间，10位时间戳。
5.6.status	integer(int32)		投递状态。
5.7.toAddress	string		收信地址。
6.totalCount	integer(int32)		发送总条数。
示例
请求参数	-d '{"bizId":"string","currentPage":0,"pageSize":0,"startDate":"string","endDate":"string"}'
返回值	{"platformName":"string","code":"string","message":"string","totalCount":0,"requestId":"string","sendDetailDTOs":[{"accountName":"string","code":"string","message":"string","outId":"string","receiveDate":"string","status":0,"toAddress":"string"}]}

邮件发件箱地址查询接口

接口描述	邮件发件箱地址查询
URL	${prefix}/email/thirdSender
请求方式	get
请求类型	application/json
返回类型	/
参数名	数据类型	参数类型	是否必填	说明
1.address	string	query	是	发件箱地址。
状态码	描述		说明
200	OK		请求成功。
401	Unauthorized		请求未经授权。
403	Forbidden		请求被拒绝。
404	Not Found		请求的资源不存在。
返回属性名	类型		说明
1.accountName	string		发信地址。
2.accountStatus	integer(int32)		账号状态。冻结：1，正常：0。
3.platformName	string		服务方名称，与接口配置时填写的接口名称一致。
4.code	string		请求状态码，返回OK代表请求成功，其他为错误码。
5.createDate	string		创建日期和时间，如：2019-01-08 16:44:13。
6.mailAddressId	string		发信地址ID。
7.message	string		状态码描述。
8.requestId	string		请求ID。
示例
请求参数	address={email}
返回值	{"accountStatus":0,"code":"string","accountName":"string","requestId":"string","platformName":"string","message":"string","mailAddressId":"string","createDate":"string"}

短信模板审核接口

接口描述	短信模板审核
URL	${prefix}/sms/smsTemplate
请求方式	post
请求类型	application/json
返回类型	/
参数名	数据类型	参数类型	是否必填	说明
1.model	object:AddSmsTemplateModel	body	是	模板信息。
1.1.remark	string		是	短信模板申请说明。请在申请说明中描述您的业务使用场景，长度为1~100个字符。
1.2.templateContent	string		是	模板内容，长度为1~500个字符。
1.3.templateName	string		是	模板名称，长度为1~30个字符。
1.4.templateSubject	string		否	模板主题，长度为1~20个字符。
1.5.templateType	integer(int32)		是	短信类型。0：验证码，1：短信通知，2：推广短信，3：国际/港澳台消息。
状态码	描述		说明
200	OK		请求成功。
201	Created		请求成功，并且创建了资源。
401	Unauthorized		请求未经授权。
403	Forbidden		请求被拒绝。
404	Not Found		请求的资源不存在。
返回属性名	类型		说明
1.platformName	string		短信服务方名称，与接口配置时填写的接口名称一致。
2.code	string		请求状态码，返回OK代表请求成功，其他为错误码。
3.message	string		状态码描述。
4.requestId	string		请求ID。
5.templateCode	string		短信模板code，用于查看模板申请状态和结果
示例
请求参数	-d '{"remark":"string","templateContent":"string","templateName":"string","templateSubject":"string","templateType":0}'
返回值	{"platformName":"string","code":"string","templateCode":"string","message":"string","requestId":"string"}

短信模板修改接口

接口描述	短信模板修改
URL	${prefix}/sms/smsTemplate/{templateCode}
请求方式	put
请求类型	application/json
返回类型	/
参数名	数据类型	参数类型	是否必填	说明
1.model	object:AddSmsTemplateModel	body	是	模板信息。
1.1.remark	string		否	短信模板申请说明。请在申请说明中描述您的业务使用场景，长度为1~100个字符。
1.2.templateContent	string		否	模板内容，长度为1~500个字符。
1.3.templateName	string		否	模板名称，长度为1~30个字符。
1.4.templateSubject	string		否	模板主题，长度为1~20个字符。
1.5.templateType	integer(int32)		否	短信类型。0：验证码，1：短信通知，2：推广短信，3：国际/港澳台消息。
状态码	描述		说明
200	OK		请求成功。
201	Created		请求成功，并且创建了资源。
401	Unauthorized		请求未经授权。
403	Forbidden		请求被拒绝。
404	Not Found		请求的资源不存在。
返回属性名	类型		说明
1.platformName	string		短信服务方名称，与接口配置时填写的接口名称一致
2.code	string		请求状态码，返回OK代表请求成功，其他为错误码。
3.message	string		状态码描述。
4.requestId	string		请求ID。
5.templateCode	string		短信模板code，用于查看模板申请状态和结果。
示例
请求参数	-d '{"remark":"string","templateContent":"string","templateName":"string","templateSubject":"string","templateType":0}'
返回值	{"platformName":"string","code":"string","templateCode":"string","message":"string","requestId":"string"}

短信签名审核状态查询接口

接口描述	短信签名审核状态查询
URL	${prefix}/sms/smsSign/{signName}
请求方式	get
请求类型	application/json
返回类型	/
参数名	数据类型	参数类型	是否必填	说明
1.signName	string	path	是	短信签名。
状态码	描述		说明
200	OK		请求成功。
401	Unauthorized		请求未经授权。
403	Forbidden		请求被拒绝。
404	Not Found		请求的资源不存在。
返回属性名	类型		说明
1.platformName	string		短信服务方名称，与接口配置时填写的接口名称一致。
2.code	string		请求状态码，返回OK代表请求成功，其他为错误码。
3.createDate	string		短信签名的创建日期和时间，如：2019-01-08 16:44:13。
4.message	string		状态码描述。
5.reason	string		审核备注。如果审核状态为审核通过或审核中，参数Reason显示为“无审核备注”；如果审核状态为审核未通过，参数Reason显示审核的具体原因。
6.requestId	string		请求ID。
7.signName	string		短信签名。
8.signStatus	integer(int32)		签名审核状态。0：审核中，1：审核通过，审核失败，请在返回参数Reason中查看审核失败原因。
示例
请求参数	无示例
返回值	{"reason":"string","code":"string","signName":"string","requestId":"string","signStatus":0,"platformName":"string","message":"string","createDate":"string"}

短信模板审核状态查询接口

接口描述	短信模板审核状态查询
URL	${prefix}/sms/smsTemplate/{templateCode}
请求方式	get
请求类型	application/json
返回类型	/
参数名	数据类型	参数类型	是否必填	说明
1.templateCode	string	path	是	模板code。
状态码	描述		说明
200	OK		请求成功。
401	Unauthorized		请求未经授权。
403	Forbidden		请求被拒绝。
404	Not Found		请求的资源不存在。
返回属性名	类型		说明
1.platformName	string		服务方名称，与接口配置时填写的接口名称一致。
2.code	string		请求状态码，返回OK代表请求成功，其他为错误码。
3.createDate	string		模板的创建日期和时间，如：2019-01-08 16:44:13。
4.message	string		状态码描述。
5.reason	string		审核备注。如果审核状态为审核通过或审核中，参数Reason显示为“无审核备注”；如果审核状态为审核未通过，参数Reason显示审核的具体原因。
6.requestId	string		请求ID。
7.templateCode	string		模板code。
8.templateContent	string		模板内容。
9.templateName	string		模板名称。
10.templateStatus	integer(int32)		签名审核状态。0：审核中，1：审核通过，审核失败，请在返回参数Reason中查看审核失败原因。
11.templateType	integer(int32)		短信模板类型。0：验证码，1：短信通知，2：推广短信，3：国际/港澳台消息。邮件忽略。
示例
请求参数	无示例
返回值	{"templateStatus":0,"templateType":0,"reason":"string","code":"string","templateName":"string","requestId":"string","templateContent":"string","platformName":"string","templateCode":"string","message":"string","createDate":"string"}

短信发送接口

接口描述	大量短信发送
URL	${prefix}/sms/sendBatch
请求方式	post
请求类型	application/json
返回类型	/
参数名	数据类型	参数类型	是否必填	说明
1.model	object:SendBatchSmsModel	body	是	短信发送请求参数。
1.1.limit	integer(int64)		否	发送人数限制。
1.2.outId	string		是	外部流水扩展字段。
1.3.phoneOssUrl	string		是	接收短信的手机号码文件所在的oss路径。文件格式txt。国内短信：11位手机号码，例如15951955195；国际/港澳台消息：国际区号+号码，例如85200000000。每个号码一行。
1.4.signName	string		是	短信签名名称。
1.5.templateCode	string		是	模板code。
1.6.templateParam	string		否	短信模板变量对应的实际值，JSON格式。
状态码	描述		说明
200	OK		请求成功。
201	Created		请求成功，并且创建了资源。
401	Unauthorized		请求未经授权。
403	Forbidden		请求被拒绝。
404	Not Found		请求的资源不存在。
返回属性名	类型		说明
1.bizId	string		发送回执ID，可根据该ID在接口QuerySendDetails中查询具体的发送状态。
2.platformName	string		服务方名称，与接口配置时填写的接口名称一致。
3.code	string		请求状态码，返回OK代表请求成功，其他为错误码。
4.message	string		状态码描述。
5.requestId	string		请求ID。
示例
请求参数	-d '{"limit":0,"outId":"string","phoneOssUrl":"string","signName":"string","templateCode":"string","templateParam":"string"}'
返回值	{"bizId":"string","channelName":"string","code":"string","message":"string","requestId":"string"}

短信发送明细查询接口

接口描述	短信发送明细查询
URL	${prefix}/sms/sendDetails
请求方式	post
请求类型	application/json
返回类型	/
参数名	数据类型	参数类型	是否必填	说明
1.model	object:QuerySendDetailModel	body	是	短信发送明细查询请求参数。
1.1.outId	string		是	外部流水扩展字段，可根据该ID在接口QuerySendDetails中查询具体的发送状态。
1.2.currentPage	integer(int64)		是	分页查看发送记录，指定发送记录的的当前页码。
1.3.pageSize	integer(int64)		是	分页查看发送记录，指定每页显示的短信记录数量。取值范围为1~1000。
1.4.startDate	string		是	起始时间，时间不能早于30日，格式yyyy-MM-dd HH:mm。
1.5.endDate	string		是	结束时间，和起始时间跨度不能超出30天，格式yyyy-MM-dd HH:mm。
状态码	描述		说明
200	OK		请求成功。
201	Created		请求成功，并且创建了资源。
401	Unauthorized		请求未经授权。
403	Forbidden		请求被拒绝。
404	Not Found		请求的资源不存在。
返回属性名	类型		说明
1.platformName	string		短信服务方名称，与接口配置时填写的接口名称一致
2.code	string		请求状态码，返回OK代表请求成功，其他为错误码。
3.message	string		状态码描述。
4.requestId	string		请求ID。
5.sendDetailDTOs	array:SmsSendDetailDTO		短信发送明细。
5.1.content	string		短信内容。
5.2.errCode	string		运营商短信状态码。短信发送成功：DELIVERED。短信发送失败：给出错误码。
5.3.outId	string		外部流水扩展字段。
5.4.phoneNum	string		接收短信的手机号码。
5.5.receiveDate	string		短信接收日期和时间。
5.6.sendDate	string		短信发送日期和时间。
5.7.sendStatus	integer(int64)		短信发送状态。1：发送失败，2：发送成功。
5.8.templateCode	string		短信模板ID。
6.totalCount	integer(int32)		短信发送总条数。
示例
请求参数	-d '{"bizId":"string","currentPage":0,"pageSize":0,"sendDate":"string"}'
返回值	{"platformName":"string","code":"string","message":"string","totalCount":0,"requestId":"string","sendDetailDTOs":[{"content":"string","errCode":"string","outId":"string","phoneNum":"string","receiveDate":"string","sendDate":"string","sendStatus":0,"templateCode":"string"}]}