API: MMS/template


概览


MMS/template 是 SUBMAIL 的彩信模板 API。

使用 MMS/template 可以获取、创建、编辑或删除您的彩信模板。

MMS/templateAPI 使用 HTTP 规范中的 GET, POST, PUT, DELETE 方法对模板进行操作,使用 GET 方法获取单个或全部模板、POST 方法创建新的彩信模板并提交至 SUBMAIL 人工审核、PUT 方法更新或编辑一个彩信模板,或使用 DELETE 方法删除一个模板。

彩信模板引擎支持 SUBHOOK 异步推送状态,彩信模板在后台人工审核后,会使用 SUBHOOK 进行主动推送状态。



URL


<备> https://api.mysubmail.com/mms/template

<备> https://api.submail.cn/mms/template



支持格式


格式URL
jsonhttps://api.mysubmail.com/mms/template.json (默认)
xmlhttps://api.mysubmail.com/mms/template.xml


http 请求方式


GET获取全部模板列表,或获取指定的单个模板
POST创建一个新的彩信模板,并提交至 SUBMAIL 进行人工审核
PUT编辑或更新一个彩信模板,并提交至 SUBMAIL 进行人工审核
DELETE删除一个彩信模板


是否需要授权


参阅 API 授权和验证机制


MMS/template GET 方法(获取模板列表)请求参数


参数类型必需/可选默认描述
appidstring必需在 SUBMAIL 应用集成中创建的彩信应用 ID
template_idstring可选模板ID(可选)
要获取单个模板,请将在此参数中提交该模板ID。为空则获取最新的1000个彩信模板
timestampUNIX 时间戳可选参阅 API 授权与验证机制 > Timestamp UNIX 时间戳
sign_typestring可选normalAPI 授权模式( md5 or sha1 or normal
参阅 API 授权与验证机制 > 授权和验证方式
signaturestring必需应用密匙 数字签名
参阅 API 授权与验证机制 > 授权和验证方式


MMS/template POST 方法(创建模板)请求参数


参数类型必需/可选默认描述
appidstring必需在 SUBMAIL 应用集成中创建的彩信应用 ID
mms_titlestring可选模板标题
创建模板时可以在此参数中提交当前模板的标题,作为模板备注信息
mms_signaturestring必需彩信模板签名
请使用您的公司名或应用、APP、网站名作为您的彩信签名,请将彩信签名和彩信标题的字符总和控制在64个字符以内。
mms_subjectstring必需彩信模板主题
彩信标题通常显示在彩信的顶部,请将彩信签名和彩信标题的字符总和控制在64个字符以内。
mms_contentjson必需彩信模板正文
彩信正文为jsonArray类型,具体参数展示参考MMS_CONTEANT参数表,以及参数示列。
timestampUNIX 时间戳可选参阅 API 授权与验证机制 > Timestamp UNIX 时间戳
sign_typestring可选normalAPI 授权模式( md5 or sha1 or normal
参阅 API 授权与验证机制 > 授权和验证方式
signaturestring必需应用密匙 数字签名
参阅 API 授权与验证机制 > 授权和验证方式


MMS/template PUT 方法(更新模板)请求参数


参数类型必需/可选默认描述
appidstring必需在 SUBMAIL 应用集成中创建的彩信应用 ID
template_idstring必需需要更新的模板 ID
在 SUBMAIL >MMS >项目中查看你所创建的短信项目标记。请参见 获取项目或地址薄的开发者标识
mms_titlestring可选模板标题(可选)
创建模板时可以在此参数中提交当前模板的标题,作为模板备注
mms_signaturestring必需短信模板签名
请使用您的公司名或应用、APP、网站名作为您的彩信签名,请将彩信签名和彩信标题的字符总和控制在64个字符以内。
mms_subjectstring必需彩信模板主题
彩信标题通常显示在彩信的顶部,请将彩信签名和彩信标题的字符总和控制在64个字符以内。
mms_contentjson必需彩信模板正文
彩信正文为jsonArray类型,具体参数展示参考MMS_CONTEANT参数表,以及参数示列。
timestampUNIX 时间戳可选参阅 API 授权与验证机制 > Timestamp UNIX 时间戳
sign_typestring可选normalAPI 授权模式( md5 or sha1 or normal
参阅 API 授权与验证机制 > 授权和验证方式
signaturestring必需应用密匙 数字签名
参阅 API 授权与验证机制 > 授权和验证方式


MMS/template DELETE 方法(删除模板)请求参数


参数类型必需/可选默认描述
appidstring必需在 SUBMAIL 应用集成中创建的彩信应用 ID
template_idstring必需需要删除的模板 ID
在 SUBMAIL >MMS >项目中查看你所创建的彩信项目标记。请参见 获取项目或地址薄的开发者标识
timestampUNIX 时间戳可选参阅 API 授权与验证机制 > Timestamp UNIX 时间戳
sign_typestring可选normalAPI 授权模式( md5 or sha1 or normal
参阅 API 授权与验证机制 > 授权和验证方式
signaturestring必需应用密匙 数字签名
参阅 API 授权与验证机制 > 授权和验证方式


MMS_CONTENT参数


参数类型必需/可选默认描述
textstring可选文字内容
jsonArray数组中text参数与媒体(image或者audio)文件参数不能同时为空。
imagejson可选彩信图片
image参数为json类型还包含image.data ,image.type两个参数。具体数据格式参考代码示列。
image.database64携带图片时必需图片BASE64数据
image.typestring携带图片时必需图片类型
支持类型 image/jpg, image/jpeg, image/png, image/gif
audiojson可选音频文件
audio参数为json类型还包含audio.data ,audio.type两个参数。具体数据格式参考代码示列。
audio.database64携带音频时必需音频BASE64数据
audio.typestring携带音频时必需音频类型
支持类型 audio/mp3, audio/wav, audio/midi



注意:

  1. mms_content 为json数组类型。
  2. 彩信模板最大支持9页,mms_content参数中每一组数据为一页,并且依次排序。
  3. 彩信模板每一页必须至少包含一种类型数据,媒体文件或者文字。
  4. 单模板仅支持一种媒体类型,图片或音频,即图片+文字,或音频+文字,并将彩信标题+签名+媒体文件+正文文字的大小总和控制在 85KB 以内。
  5. 媒体文件中的数据必须是 base64 编码,并通过 type 参数正确的说明文件类型。
  6. 单个图片或音频文件的大小应控制在 85 KB以内。



MMS_CONTENT参数JSON数据示列


图片+文字
[
    {
        "image":{
            "data":"/9j/4QAYRXhpZgAASUkqAAgAAAAAAAAAAAAAAP/sABFEdWNr………………", 
            "type":"image/jpeg"
        },
        "text":"test-image"
    }
]


音频+文字
[
    {
        "audio":{
            "data":"/9j/4QAYRXhpZgAASUkqAAgBBBBBBBBBBP/sABFEdWNr………………",
            "type":"audio/wav"
        },
        "text":"test-audio"
    }
]


图片+文字:多页
[
    {
        "image":{
            "data":"/9j/4QAYRXhpZgAASUkqAAgAAAAAAAAAAAAAAP/sABFEdWNr………………", 
            "type":"image/jpeg"
        },
        "text":"text1"
    },{
        "image":{
            "data":"/9j/4QAYRXhpZgAASUkqBBBBBBBBBBBBBBBBBBBP/sABFEdWNr………………", 
            "type":"image/jpeg"
        },
        "text":"text2"
    },{
        "image":{
            "data":"/9j/4QAYRXhpZgAASUkqAAgCCCCCCCCCCCCCCCP/sABFEdWNr………………", 
            "type":"image/jpeg"
        },
        "text":"text3"
    }
] 


代码示例


使用 CURL GET方法获取模板列表


发送 CURL
curl -s "https://api.mysubmail.com/mms/template.json?appid=your_appid&signature=your_appkey&template_id=FIJe14"


返回
{
"status": "success",
"template": {
    "template_id": "FIJe14",
    "mms_title": "账户更改邮箱验证码",
    "mms_signature": "【SUBMAIL】",
    "mms_content": [
    {
        "image":{                           
                     "url":"https://xxxxxxxxxxx/xxxl32d5a1.png", 
                      "type":"image/png"
                      },
       "text":"您的验证码是1234."
    }
                             ]
    "mms_subject":"邮箱更改通知",
    "create_at": "2016-01-08 21:28:04",
    "edit_at": "2016-01-08 21:28:04",
    "template_status": "2",
    "template_status_description": "通过审核"
    }
}


使用 CURL POST方法提交彩信模板


发送 CURL
curl -d 'appid=your_appid&signature=your_appkey&mms_title=POST方法测试&mms_signature=【SUBMAIL】&mms_subject=post标题提交测试&mms_content=[
    {
        "image":{
                        "data":"/9j/4QAYRXhpZgAASUkqAAgAAAAAAAAAAAAAAP/sABFEdWNr…", 
                        "type":"image/jpeg"
                      },
       "text":"text1"
    },{
        "image":{
                        "data":"/9j/4QAYRXhpZgAASUkqAAgBBBBBBBBBBBBBBBAP/sABFEdWNr…", 
                        "type":"image/jpeg"
                      },
        "text":"text2"
    },{
        "image":{
                        "data":"/9j/4QAYRXhpZgAASUkqCCCCCCCCCCCCCCCCCC/sABFEdWNr…", 
                        "type":"image/jpeg"
                     },
       "text":"text3"
    }
]
 ' http://api.mysubmail.com/mms/template.json


返回
{
    "status": "success",
    "template_id": "FsoAF3"    // API 返回的模板ID,作为请求 API 的 PROJECT 参数
}


使用 CURL PUT 方法修改短信模板


发送 CURL
curl --data 'appid=your_appid&signature=your_appkey&mms_title=POST方法测试&mms_signature=【SUBMAIL】&mms_subject=post标题提交测试&mms_content=[
    {
        "image":{
                        "data":"/9j/4QAYRXhpZgAASUkqAAgAAAAAAAAAAAAAAP/sABFEdWNr…", 
                        "type":"image/jpeg"
                      },
        "text":"text1"
    },{
        "image":{
                        "data":"/9j/4QAYRXhpZgAASUkqAAgABBBBBBBBBBBBAP/sABFEdWNr…", 
                        "type":"image/jpeg"
                       },
        "text":"text2"
    },{
        "image":{
                        "data":"/9j/4QAYRXhpZgAASUkqAAgCCCCCCCCCCCCP/sABFEdWNr…", 
                        "type":"image/jpeg"
                      },
       "text":"text3"
    }
]'
   http://api.mysubmail.com/mms/template.json


返回
{
    "status":"success"
}


使用 CURL DELETE 方法删除短信模板


发送 CURL
curl --data "appid=your_appid&signature=your_appkey&template_id=FsoAF3" -X delete http://api.mysubmail.com/mms/template.json


返回
{
    "status":"success"
}


template_status 模板状态描述


template_status : 0未提交审核
template_status : 1正在审核
template_status : 2审核通过
template_status : 3未通过审核


返回值


请求成功
{
    "status":"success"
}


请求失败
{
    "status":"error",
    "code":"1xx",
    "msg":"error message"
}


错误代码


参阅 API 错误代码