全部产品

第三方短信邮件平台接口规范

为了在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"}]}