SMTP API


概览


SUBMAIL 的 SMTP API 使用电子邮件协议的自定义指令。开发者通过在邮件头中插入 x-submail-smtp-api 指令灵活地控制发送请求,如添加联系人、将地址簿添加至发送队列,或使用文本变量或超链接变量来灵活地控制邮件内容,甚至在SMTP API 中使用模板。

要使用 SUBMAIL SMTP API,开发者需要在邮件头中插入 x-submail-smtp-api 指令,并将请求的参数编码成 JSON 字符串。

一个简单的请求看起来是这样的:


代码示例

{
  "to":[
           "leo <leo>",
           "retro@submail.cn"
          ],
 "addressbook":[
           "subscribe",
           "WbRfn3"
          ]
}


X-SUBMAIL-SMTP-API 邮件标头指令


x-submail-smtp-api 指令是一个标准的 JSON 格式,包含几个部分的关联数组。使用 SMTP 协议请求 SUBMAIL 发送的邮件中包含有效的 x-submail-smtp-api 指令时,SUBMAIL 将会对此指令进行解析并将其应用到邮件事务。



to 指令


to : 联系人组数,包含可选的显示名称。SUBMAIL 支持完整的RFC 822 电邮地址协议,请在提交请求前检查邮件地址的有效性。

{
   "to":[
          "leo <leo>",
          "retro <retro>",
          "<service>",
          "account@submail.cn"
          ]
}


addressbook 指令


addressbook:地址簿指令。使用地址簿指令将地址簿中的联系人添加到发送队列,你可以在 addressbook 指令中加入 subscribe 来添加订阅用户,或使用地址簿标示。请参见获取项目或地址簿的开发者标识

{
   "addressbook":[
             "subscribe",
             "j5lVv1"
            ]
}


template 指令


template:邮件模板指令。邮件模板指令允许开发者使用在 SUBMAIL MAIL 应用中创建的邮件项目,要使用该项目发送,请在此指令中添加邮件项目标示。请参见获取项目或地址簿的开发者标识

{
     "template":"DKFzD4"
}


vars 指令


vars:文本变量指令。使用 vars 文本变量灵活的控制邮件内容。请参见文本变量

{
     "vars":{
               "key1":"value",
               "key2":"value",
               "key3":"value"
             }
}


links 指令


links:超链接变量指令。使用 links 超链接变量灵活的控制邮件中的超链接。请参见超链接变量

{
     "links":{
               "key1":"value",
               "key2":"value",
               "key3":"value"
             }
}


代码示例


完整功能的 x-submail-smtp-api JSON 字符串示例

{
  "to":[
        "leo <leo>",
  ],
 "addressbook":[
        "subscribe",
        "WbRfn3"
  ],
  "template":"DKFzD4",
  "vars":{
        "key1":"value",
        "key2":"value",
        "key3":"value"
  },
 "links":{
        "key1":"value",
        "key2":"value",
        "key3":"value"
  }

}


使用 perl 语言编写的 x-submail-smtp-api 指令示例

#!/usr/local/bin/perl -w

use strict;
use JSON;

my $header = {
        to => ['leo '],
        addressbook => ['subscribe','WbRfn3'],
        template => 'DKFzD4',
        vars => { 'key1' => 'value', 'key2' => 'value', 'key3' => 'value' },
        links => { 'key1' => 'value', 'key2' => 'value', 'key3' => 'value' }
};

my $json = JSON->new;
$json->space_before(1);
$json->space_after(1);
my $js = $json->encode($header);
$js =~ s/(.{1,72})(\s)/$1\n /g;
my $headers = "X-SUBMAIL-SMTP-API: $js";
print "$headers\n";


错误代码


x-submail-smtp-api 无返回码,它通常返回 SMTP 错误代码。通常在测试 x-submail-smtp-api 时,开发者可前往 API 错误日志 中查看 x-submail-smtp-api 返回的错误代码。

参阅 API 错误代码