API接口说明

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) 32MD5,其中email表示EMD登陆邮箱key表示在EDM管理中心设置的密匙,otime为时间戳,ActionAPI的具体操作,hash值不区分大小写。                                                    

参数(必须)                

参数说明                

email                

EDM登陆邮箱                

otime                

时间戳:1531903156()                

sig                

验证签名,其值为md5(email+md5(key)+otime+Action)key是在邮局管理页面申请的api秘钥,Action是操作方法,比如check,getgrpid                

B) 公共参数说明

注意,所有操作必须带上公共参数作为校验使用,否则操作将被拒绝

示例url:

https://api.myhostadmin.net/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.myhostadmin.net/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.myhostadmin.net/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.myhostadmin.net/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.myhostadmin.net/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.myhostadmin.net/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@west.cn,yyy@west.cn                

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选填                

排除距今几天的已发送过相同模板IDEmail地址                

E)返回值说明


返回值                

说明                

200                

任务创建成功并执行                

5000                

任务创建执行失败                

5000                

系统错误,临时组ID查询失败                

5000                

系统错误,创建临时组失败                

5000                

系统错误,临时任务创建失败                

5000                

系统错误,临时任务ID查询失败                

5007                

模板ID数据库验证为空                

5007                

可用点数不足,请充值!                

5007                

发信域名数据库验证为空                

5007                

发信域名解析验证失败                

5007                

跟踪域名解析验证失败                

5010                

API超出频率限制!每小时3600                

5015                

数据效验错误,提交的数据格式不符                



示例url:
 

    https://api.myhostadmin.net/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自定义变量



发布日期:2018-12-05 16:32:52.0