API Reference

集成指南

一、注册账号并申请API密钥

注册mambasms账号并申请开发者密钥

mamba系统中发生邮件是以店铺为单位，一个店铺对应一个站点

进入店铺创建发件人邮件地址，并配置发件人域

二、订阅邮件事件

支持邮件事件列表

描述eventType推送body
邮件接收成功，送达推送delivery{
"eventData": {
"reason": null,
"msg_from": "msprvs1=19591MTYiPLLl=[email protected]",
"rcpt_to": "[email protected]",
"error_code": null,
"transmission_id": "7263131452386267250",
"timestamp": "1692087550"
},
"eventType": "delivery"
}
邮件接收失败bounce{
"eventData": {
"reason": "554 5.7.1 [internal] recipient address was suppressed due to customer policy",
"msg_from": "msprvs1=19591MTYiPLLl=[email protected]",
"rcpt_to": "[email protected]",
"error_code": "554",
"transmission_id": "7267352687971264007",
"timestamp": "1692087720"
},
"eventType": "bounce"
}
用户打开邮件initial_open{
"eventData": {
"msg_from": "msprvs1=19591MTYiPLLl=[email protected]",
"rcpt_to": "[email protected]",
"transmission_id": "7263131452386267250",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36",
"timestamp": "1692087571"
},
"eventType": "initial_open"
}
用户点击某个链接click{
"eventData": {
"msg_from": "msprvs1=19591MTYiPLLl=[email protected]",
"rcpt_to": "[email protected]",
"target_link_url": "https://www.mambasms.com/",
"transmission_id": "7263131452386267250",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36",
"timestamp": "1692087571"
},
"eventType": "click"
}
用户点击列表退订list_unsubscribe{
"eventData": {
"rcpt_to": "[email protected]",
"transmission_id": "7267210421474857068"
},
"eventType": "list_unsubscribe"
}

创建 webhook 订阅邮件事件。邮件送达、打开、点击等事件会以post方式推送

curl --request POST \
     --url https://api.mambasms.com/api/v1/webhooks \
     --header 'X-Mamba-Access-Token: 2cf3144e51524c56bce0109cc06fecd1' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
    "topic": "transmission/callback",
    "url": "填写接收地址，地址最大长度不超过500字符"
}
'

三、调用群发接口

  • 邮件群发API域名和主域名不相同
  • 单次最大发送系人数量为2000
curl --request POST \
     --url https://sending.mambasms.com/api/v1/sending \
     --header 'X-Mamba-Access-Token: 2cf3144e51524c56bce0109cc06fecd1' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
    "subject": "sending",
    "preheader": "sending description",
    "html": "<span> hello sending</span>",
    "text": "",
    "from": {
        "name": "zhaoqt",
        "email": "[email protected]"
    },
    "recipients": [
        {
            "address": {
                "name": "zhaoqt",
                "email": "[email protected]"
            }
        }
    ]
}

请求体参数

参数类型说明是否必填
subjectstring邮件主题行，utf-8 字符集Y
preheaderstring邮件主题行备注，utf-8 字符集N
htmlstring邮件的 text/html MIME 部分的 HTML 内容。至少需要 html 或text，utf-8 字符集Y
textstring邮件的text/plainMIME 部分的文本内容。至少需要 html 或text，utf-8 字符集N
fromobj发件人
from.namestring邮件发件人名称Y
from.emailstring邮件发件人地址，邮件域名必须DKIM签名后使用Y
recipientsarray收件人列表 单次最大2000个
recipients[0].address.namestring收件人名称N
recipients[0].address.emailstring收件人邮件地址Y
recipients[0].address.substitutionDataobj收件人专属变量，例如：{"lastName","tom"}
replyTostring设置用户默认的回复邮件地址，如果 replyTo 没有或者为空，则默认的回复邮件地址为 fromN
headersobj邮件头部信息， 例如：{"header1": "value1", "header2": "value2"}N
substitutionDataobj批量发送邮件共有变量，例如：{"brand","mambasms"}N

如果需要替换html模板变量参考 模板变量

发送成功返回

{
	"totalAccepted": 1, 
	"totalRejected": 0,
	"id": "7267210421474857068",
	"code": "200",
	"succeed": true,
	"message": "succeed"
}
  • totalAccepted 发送成功接收数量
  • totalRejected 发送拒绝接收数量
  • id 发送返回批次 id 与推送事件中 transmission_id相同
  • succeed 成功返回 true

建议每次群发接口返回 succeed = true， 为批次id和本次发送收件人邮件做本地映射存储。邮件推送事件回调可以根据transmission_id + rcpt_to 找到具体发件人做后续业务处理