EDM API接口文档
Version 1.0
2018-7-18
目录
1. 权限认证 3
2. 获取用户组信息 3
3. 获取模板列表 4
4. 获取历史任务列表 4
5. 邮箱表单订阅 4
6. 创建基本任务 5
7. 创建临时任务 5
8. 地址变量参数说明
1.
A) 描述
为了保证API接口安全，所有API操作都需要进行权限认证，权限验证主要有三个因素，1)时间戳，为了防止重放攻击，要求参数中必须提供时间戳(otime)参数，且要求时间戳与服务器时间误差不超过600秒;2)IP限制，发起API调用的IP地址必须在EDM中进行授权，未授权的请求将被拒绝;3)hash验证，每一个API请求中，必须提供sig参数用于hash验证，hash值的计算公式为：md5(email+md5(key)+otime+Action) 32位MD5,其中email表示EMD登陆邮箱，key表示在EDM管理中心设置的密匙，otime为时间戳,Action为API的具体操作，hash值不区分大小写。
参数（必须） |
参数说明 |
EDM登陆邮箱 |
|
otime |
时间戳:(十位当前时间戳) |
sig |
验证签名，其值为md5(email+md5(key)+otime+Action)，key是在邮局管理页面申请的api秘钥,Action是操作方法，比如check,getgrpid |
B) 公共参数说明
注意，所有操作必须带上公共参数作为校验使用，否则操作将被拒绝
示例url:
https://api.0752173.com/api/v1/check?email=xxx@myhostadmin.cn&otime=1531895947&sig=98e9561d9db414a1eaa323cdfa1c91f2
C) 返回值（json格式)
返回值 |
说明 |
200 |
验证成功 |
5000 |
系统错误 |
5001 |
参数错误 |
5002 |
时间戳超时5分钟! |
5004 |
用户(email)不存在 |
5005 |
调用IP未在白名单 |
5006 |
效验失败检查密钥 |
5008 |
未知Action |
5009 |
API配置错误,可能后台未正确配置API接口 |
5015 |
数据效验错误,提交的数据格式不符 |
D)POST方法数据使用json格式
{”email”:”xxx@myhostadmin.cn”,”otime”:1531981556,”sig”:”98e9561d9db414a1eaa323cdfa1c91f2”}
E)返回数据例如：
{“action”:”check”,”status”:200,”msg”:”验证成功”}
2. 获取用户组信息
A) 描述
用户获取已创建的用户组信息
B) 请求URL
/api/v1/getgrpid
C) Action(用于生成sig hash值)
getgrpid
参数 |
参数说明 |
无 |
无 |
D) 参数说明
示例url:
https://api.0752173.com/api/v1/getgrpid?email=xxx@myhostadmin.cn&otime=1531895947&sig=98e9561d9db414a1eaa323cdfa1c91f2
E) 返回值
返回值 |
说明 |
200 |
命令成功 |
5007 |
没有查询到用户组数据 |
例如：{"status":200,"action":"getgrpid","data":{"id":144,"name":"重庆问题"},"msg":"命令成功"}
3.
A)描述
用于获取所有模板信息
B)请求URL
/api/v1/gettmp
C)Action(用于生成sig hash值)
gettmp
参数 |
参数说明 |
无 |
无 |
D)参数说明
示例url： https://api.0752173.com/api/v1/gettmp?email=xxx@myhostadmin.cn&otime=1531895947&sig=98e9561d9db414a1eaa323cdfa1c91f2
E) 返回值
返回值 |
说明 |
200 |
命令成功 |
例如：
{"status":200,"action":"gettmp","data":{"id":215,"attlist":null,"subject":"新会员注册免费赠送1000元","name":"EDM测试邮件","audit":2,"size":6296},"msg":"命令成功"}
4. 历史任务列表
A)描述
用于获取历史任务列表
B)请求URL
/api/v1/getjoblist
C)Action(用于生成sig hash值)
getjoblist
D)参数说明
参数 |
参数说明 |
无 |
无 |
示例url:
https://api.0752173.com/api/v1/getjoblist?email=xxx@myhostadmin.cn&otime=1531895947&sig=98e9561d9db414a1eaa323cdfa1c91f2
E) 返回值
例如：
5. 邮箱表单订阅
A) 描述
用于访客浏览网站提交Email邮箱订阅
B) 请求URL
/api/v1/subscribe
D) Action(用于生成sig hash值)
subscribe
E) 参数说明
参数 |
参数说明 |
gid（必须） |
地址所在的地址池组ID |
semail（必须） |
订阅的email地址 |
name（选填） |
姓名 |
title（选填） |
称谓 |
birthday（选填） |
生日 |
org（选填） |
公司 |
city（选填） |
城市 |
phone（选填） |
电话 |
v1 - v9（选填） |
自定义变量 |
F)返回值说明
返回值 |
说明 |
5000 |
订阅失败 |
5007 |
收信组ID不存在 |
5015 |
数据效验错误,提交的数据格式不符 |
示例
https://api.0752173.com/api/v1/subscribe?email=xxx@myhostadmin.cn&otime=1531895947&sig=98e9561d9db414a1eaa323cdfa1c91f2&gid=12&semail=test@myhostadmin.cn
例如：
{“action”:”subscribe”,”status”:200,”msg”:”订阅成功”}
6. 邮件取消订阅
A)描述
取消用户订阅
B) 请求URL
/api/v1/unsubscribe
A) Action(用于生成sig hash值)
unsubscribe
D)参数说明
参数 |
参数说明 |
usemail（必填） |
退订的Email地址 |
E)返回值说明
返回值 |
说明 |
200 |
退订成功 |
5000 |
退订失败 |
5007 |
Email不在地址池 |
5015 |
数据效验错误,提交的数据格式不符 |
示例url:
https://api.0752173.com/api/v1/unsubscribe?email=xxx@myhostadmin.cn&otime=1531895947&sig=98e9561d9db414a1eaa323cdfa1c91f2&usemail=noreply@myhostadmin.cn
返回值：
{“action”:”unsubscribe”,”status”:200,”msg”:”退订成功”}
API发信
A) 描述
为方便用户创建触发式单邮箱或者多邮箱临时发信事件,如注册确认邮件、触发式发信......等。支持邮件模板变量，自定义变量。
B) 请求URL
/api/v1/createoncejob
A) Action(用于生成sig hash值)
createoncejob
D)参数说明
参数 |
参数说明 |
tmpid（必填） |
模板ID |
sendemail（必填） |
收信Email地址。多个使用逗号分割。如:xxx@0752173.com,yyy@0752173.com |
fromdomain（必填） |
发信域名 |
smtpuser（必填） |
发信的SMTP用户 |
fromcompany(选填) |
发信人昵称,不填将系统默认域名的发信人名称 |
repy（必填） |
回信邮件地址 |
emailobj（选择填） |
收信Email参数。格式如:{"1640762152@qq.com":{"name":"王麻子","title":"老王","phone":"18011221478"}} |
tracedomain（选填） |
跟踪域名(请填写EDM系统中验证成功的域名,或解析到edm.agentsys.cn的域名) |
trace(选填) |
跟踪类型:0-不跟踪/1-跟踪打开/2-跟踪点击.默认为0不跟踪(默认跟踪地址:edm.agentsys.cn) |
extdate（选填） |
排除距今几天的已发送过相同模板ID的Email地址 |
E)返回值说明
返回值 |
说明 |
200 |
任务创建成功并执行 |
5000 |
任务创建执行失败 |
5000 |
系统错误，临时组ID查询失败 |
5000 |
系统错误，创建临时组失败 |
5000 |
系统错误，临时任务创建失败 |
5000 |
系统错误，临时任务ID查询失败 |
5007 |
模板ID数据库验证为空 |
5007 |
可用点数不足，请充值! |
5007 |
发信域名数据库验证为空 |
5007 |
发信域名解析验证失败 |
5007 |
跟踪域名解析验证失败 |
5010 |
API超出频率限制!（每小时3600次） |
5015 |
数据效验错误,提交的数据格式不符 |
示例url:
https://api.0752173.com/api/v1/createoncejob?email=xxx@myhostadmin.cn&otime=1531895947&sig=98e9561d9db414a1eaa323cdfa1c91f2&tmpid=12&sendemail=test@myhostadmin.cn&fromdomain=myhostadmin.cn&smtpuser=noreply2&repy=noreply@myhostadmin.cn&fromcompany=EDM发信
F)返回值：
{“action”:”createoncejob”,”status”:200,”msg”:”任务创建成功并执行”}
8.地址变量参数说明
| KEY |
说明 |
| name | 姓名 |
| title | 称谓 |
| birthday | 生日 |
| org | 公司 |
| city | 城市 |
| phone | 电话 |
| v1 ~ v9 | 自定义变量 |
PHP demo:
header("Content-type: text/html; charset=utf-8");
$apiurl = "https://api.0752173.com/api/v1/";
$edmuser = "edm@0752173.com"; #EDM登陆账号
$key = "dasf2das"; #API密钥,在EDM管理--系统管理--其他设置 API配置中的KEY
$action = "createoncejob"; #API动作,check 测试AIP;getgrpid 获取组ID;gettmp 获取模板ID;createoncejob 创建发信任务
$otime = time(); #获取当前时间戳
$sig = md5($edmuser.md5($key).$otime.$action); #组装sig
$tmpid = 12; #模板ID,可在模板管理中查看
$sendemail = "2151465@qq.com"; #收信邮箱地址
$fromdomain = "0752173.com"; #发信域名
$smtpuser = "xxxx"; #发信smtp 不加域名,如(notice)
$repy= "fdfas@myadmin.net"; #回信地址(收件方回复邮件的接收地址)
$fromcompany = "hhhh"; #发信人昵称
$geturl = $apiurl.$action."?email=".$edmuser."&otime=".$otime."&sig=".$sig."&tmpid=".$tmpid."&sendemail=".$sendemail."&fromdomain=".$fromdomain."&smtpuser=".$smtpuser."&repy=".$repy."&fromcompany=".$fromcompany;
$ch = curl_init();
$timeout = 5;
curl_setopt ($ch, CURLOPT_URL, $geturl);
curl_setopt ($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt ($ch, CURLOPT_CONNECTTIMEOUT, $timeout);
$file_contents = curl_exec($ch);
curl_close($ch);
echo $file_contents;
?>