RIVALSA文档中心

APIv2

发送 E-mail 邮件

发布时间:2022-05-04 15:05:54

接口描述

您可以通过本接口发送 E-mail 邮件。若收件人回复邮件,则会回复到 sa@rivalsa.cn。此接口仅支持发送触发类邮件(用户进行某操作后自动向用户发送的邮件,如验证码等)。此接口会在您发送的邮件正文后自动添加退订链接。

本接口服务地址:https://api.rivalsa.net/v2/sendemail.php

本接口的 action:sendEmail

输入参数

下表列出的参数需要放在请求体中,除此之外还需要在请求头部中添加公共请求头部

字段 必选 类型 描述
fromEmailAddress String 发件人邮箱地址
destination Array of String 收件人邮箱地址,最多支持群发50人。注意:邮件内容会显示所有收件人地址。
subject String 邮件主题
template Object 邮件正文模板

template 字段中包含如下内容:

字段 必选 类型 描述
TemplateID Integer 模板 ID
TemplateData String json 字符串格式的模板变量,变量中不支持 HTML,注意:此值需要是 json 格式的字符串,而不是 json 对象,且 json 字符串中的每个字段的值也需要是字符串。

下表是 TemplateData 字段的正确用法和错误用法的示例。

错误的 TemplateData 字段 错误原因 正确的 TemplateData 字段
{"name":"Rivalsa","age":"18"} 值应是 json 格式的字符串,而不是 json 对象。 "{\"name\":\"Rivalsa\",\"age\":\"18\"}"
"{\"name\":\"Rivalsa\",\"age\":18}" json 字符串中的每个字段的值都应该是字符串格式。
"{\"text\":\"这是是文字的第一行\n这里是文字的第二行\"}" 转义字符 \n 将内容分成了两行,这样的值不是一个 json 字符串,无法转换为 json 对象。 "{\"text\":\"这是是文字的第一行\\n这里是文字的第二行\"}"

输出参数

您调用本接口后,会返回公共响应头部公共响应体

本接口为较复杂的多层结构接口,返回成功响应仅代表本层处理成功,并不代表发送 E-mail 邮件成功。只有同时满足以下所有条件才表示 E-mail 邮件发送成功:

若出现返回成功响应,但未成功发送 E-mail 邮件的情况,请参考 response.Response.Error.Code 字段和 response.Response.Error.Message 字段的描述,或者联系我们处理。

错误码

下表列出的是本接口独有的错误码,除此之外错误码还包括公共错误码

错误码 描述
400 不支持您使用的请求方式。本接口仅支持 POST 请求。
401 不支持您使用的 Content-Type。Content-Type必须严格为 application/json;charset=UTF-8 一个字符都不能错。
402 输入参数 fromEmailAddress 的类型不正确。fromEmailAddress 必须为 String 类型。
403 输入参数 fromEmailAddress 的值不受支持,请更换或联系我们处理。
404 输入参数 destination 的格式不正确。destination 必须为 Array 类型。
405 输入参数 destination 中存在类型不正确的元素,或者 destination 中存在不是 E-mail 地址的元素。destination 中的元素必须为 String 类型,且必须为真实有效的 E-mail 地址。
406 输入参数 subject 类型不正确。subject 必须为 String 类型。
407 输入参数 template 的类型不正确。template 必须为 Object 类型。
408 输入参数 template 对象中不存在 TemplateID 字段。
409 输入参数 TemplateID 类型不正确。TemplateID 必须为 Integer 类型。
410 输入参数 template 对象中不存在 TemplateData 字段。
411 输入参数 TemplateData 类型不正确。TemplateData 必须为 String 类型。
412 输入参数 TemplateData 的格式必须为 json 字符串。

示例

请求示例
POST https://api.rivalsa.net/v2/sendemail.php

Content-Type:application/json;charset=UTF-8
Host:api.rivalsa.net
<公共响应头部>

{
    "fromEmailAddress":"noreply@rivalsa.com",
    "destination":[
        "user@example.com",
        "test@example.net"
    ],
    "subject":"修改密码验证码",
    "template":{
        "TemplateID":12345,
        "TemplateData":"{\"code\":\"000000\",\"t\":\"5\"}"
    }
}
成功响应体示例
{
    "code":0,
    "response":{
        "Response":{
            "RequestId":"f8xxxxxx-51a8-xxxx-xxxx-6bxxxxxxxxx0",
            "MessageId":"xxxxxxxxx-00-12xxxxx706-xxxx-20220430xxxxxx-K5xxxxxxxxxxx"
        }
    },
    "requestID":5
}
失败响应体示例
{
    "code":403,
    "msg":"fromEmailAddress不受支持",
    "requestID":6
}