U-Mail群发平台

Transcription

1 群发终端客户接口 V22 版本号 :V22 更新时间 :2019 年 12 月 11 日 使用备注 1 老接口地址/api/ 可继续使用, 但是不建议对接使用, 对接建议使用 /apinew/ 接口地址 接口调用前 请先验证用户名和密码, 验证方式请参照第九章 用户认证方式示例代码以及接口调用示例代码 说明 使用新功能建议使用新接口 /apinew/ 2 所有接口采用 utf-8 编码格式 ; 如果需要传入中文 韩文 西班牙语时, 请务必将接口 http 的 header 头的编码格式设为 utf-8, 并将参数的字符编码 gbk,ascii BIG5 等原编码转为 utf-8 编码传入, 方可避免编码不一致乱码情况 Php 转码请用 rawurlencode 函数 3 smtp 对接发送示例代码请参照第十章节, 无需进行 api 接口的对接 API 接口对接发送的应用场景和特点要求 1 适合批量同类型邮件对接发送, 如单批次需要发送的邮箱数量超过 5000 个及以上数量的电子期刊 广告营销等邮件 ; 2 发送速度快, 可跟踪, 使用流程 : 用 API 接口上传地址池, 上传邮件模板, 建立发送任务, 然后平台后台开始发送邮件 ; 3 整合较复杂, 需要用户有二次开发能力, 调用群发平台 API 和用户自有系统进行业务整合 ; SMTP 协议对接发送的应用场景和特点要求 1 适合和客户业务系统对接发送触发类邮件, 例如账单, 注册信, 验证码等非营销类邮件 ; 2 因为是标准协议, 很多系统都已经支持 SMTP 邮件发送, 所以无需二次开发, 或开发工作量较小, 即可和广泛的业务系统整合 ; 3 用户只需在用户登录后台的 发送域名管理 --- 账号管理 添加 SMTP 发送账号和密码即可使用 ; 4 smtp 对接暂时无法获取无效地址列表详情, 请悉知 1

2 目录 一 帐号信息相关接口 查询用户信息 查询群发服务信息... 4 二 群发统计相关接口 取得指定的群发任务或者指定发送日期的群发任务列表 (Web 群发专用 ) 获取指定日期的群发统计概览 导出发送失败地址 指定日期邮件批次发送扣点返点统计信息 指定日期扣点信息 发送日志信息查询 三 跟踪统计相关接口 (Web 群发专用 ) 获取指定群发任务的跟踪统计概览 获取指定任务邮件打开统计详情 获取指定任务链接打开统计详情 导出指定群发任务跟踪邮箱信息 指定批次的邮件各链接的点击统计 四 联系人分类相关接口 取得联系人分类列表 取得联系人分类详情 添加联系人分类 修改联系人分类 删除联系人分类 导出联系人分类地址 导出退订地址 分类地址列表 新增分类地址 修改分类地址 删除分类地址 清空联系人分类 邮件订阅 邮件退订 导入分类地址记录查询 31 五 邮件模板相关接口 创建群发任务 上传邮件模板 获取邮件模板检测状态和模板信息 模板列表 删除模板 修改模板

3 5.7 上传模板附件 删除模板附件 六 群发任务相关接口 群发任务列表 创建群发任务 修改群发任务 删除群发任务 七 域名及域名下的邮箱账号 域名列表 添加域名 验证域名 为指定子账号用户添加域名 ( 管理员账号才可调用 ) 删除指定子帐号的域名 ( 管理员账号才可调用 ) 删除域名 指定域名下的账号列表 添加账号到指定域名 删除指定域名下的账号 修改指定域名的账号 八 其他 客户自定义群发登录页面说明 九 用户认证方式示例代码以及接口调用示例代码 Python 用户认证示例代码 C# 用户认证示例代码 : java 用户认证示例代码 : php 用户认证示例代码 Ruby On Rails 示例代码 : JS 用户认证示例代码 : php 验证用户名密码并调用接口的示例代码 java 验证用户密码并调用上传附件接口示例代码 十 群发 smtp 对接方式发送邮件代码样例 php 版本 smtp 对接发送 demo 代码 python 版本 smtp 对接发送 demo 代码 java 版本 smtp 对接发送 demo 代码

4 一 帐号信息相关接口 1.1 查询用户信息 接口功能 : 查询用户信息 接口地址 : 输出格式 : <?xml version="1.0" encoding="utf-8"?> <customer> <id> 用户 ID</id> <username> 用户名称 </username> <company> 公司名称 </company> <contact> 联系人 </contact> <phone> 联系电话号码 </phone> <mobile> 移动电话号码 </mobile> < > 联系邮件地址 </ > <im> 即时聊天工具地址 </im> <address> 通信地址 </address> </customer> 1.2 查询群发服务信息 接口功能 : 查询群发服务信息 接口地址 : 输出格式 : <?xml version="1.0" encoding="utf-8"?> <service> <id> 用户 ID</id> <service_status> 群发服务状态 </service_status> <service_type> 群发服务类型 </service_type> <send_type> 发送方式 </send_type> <beginning_date> 服务开始日期 </beginning_date> <expiration_date> 服务截止日期 </expiration_date> 4

5 <qty_available> 剩余有效群发量 </qty_available> <qty_buytotal> 群发量购买总计 </qty_buytotal> </service> 说明 : 1. "service_status" : 用户群发服务状态, "enabled" 为允许用户使用群发服务 ; "disabled" 为禁止用户使用群发服务 2. "service_type": 群发服务类型,"all" 为按群发总量进行发送,"day" 为按每日发送量进行发送 3. "send_type": 群发发送方式,"remote" 为客户使用自已的服务器与平台对接发送, "local" 为使用平台服务器来进行发送 5

6 二 群发统计相关接口 2.1 取得指定的群发任务或者指定发送日期的群发任务列表 (Web 群发专用, 不适用 smtp) 接口功能 : 取得指定日期的群发任务列表 接口地址 : ( 备注 : 该接口只适用 api 和平台操作方式获取, 不适用 smtp 对接方式 ) GET 参数 ( 必要参数 ): 1. "date": 所要获取的群发任务的日期, 可不传, 不传则获取指定任务统计详情 2. ident : 具体的任务批次号 ( 批次号通过 3.1 章节接口获取 ), 可不传 3. id : 具体的任务 id, 可不传 4. state : 任务发送状态, 取值 -5 到 4 之间, 可不传备注 :date,ident,id 必须传一个输出格式 : <?xml version="1.0" encoding="utf-8"?> <task_list> <task> <id> 发送任务 send ID</id> <sn> 发送任务批次号 </sn> <sender> 发件人地址 </sender> <sender_name> 发件人名称 </sender_name> <replyto> 回复地址 </replyto> <tpl_id> 使用的模板 ID</tpl_id> <tpl_name> 使用的模板名称 </tpl_name> <addr_type> 发送地址类型 </addr_type> <list_id> 联系人分类 ID</list_id> <list_name> 联系人分类名称 </list_name> <send_qty> 预定发送数量 ( 用户指定 )</send_qty> <send_qty_remak> 预定发送数量 ( 实际发送 )</send_qty_remak> <send_time> 预定发送时间 </send_time> <send_satus> 任务发送状态 (-5 至 4 之间 )</send_satus> <time_start> 实际发送开始时间 </time_start> <time_end> 实际发送结束时间 </time_end> <send_count> 实际发送数量 </send_count> <error_count> 没有发送的失败数 ( 不等同于发送失败数 )</error_count> 6

7 </task> <track_status> 跟踪统计状态 </track_status> </task_list> 说明 : 1. "addr_type" 字段为 "0" 表示为使用用户联系人分类中的邮件地址来进行发送, 为 "1" 表示使用邮件订阅列表中的邮件地址来进行发送 2. "send_qty" 字段为用户设置的发送数量, 如为 "0" 则表示使用指定联系人分类的所有地址来发送 ; 此时 "send_qty_remark" 则显示添加此任务时指定联系人分类中的实际地址数量 "send_status" 字段各值含义如下 : 0 为等待发送 1 为等待启动发送 2 为正在发送 3 为发送完成 4 任务停止 -1 为暂不发送 -2 为暂停发送 -3 为取消发送 -4 为发送出错 -5 为等待入库启动 3. "track_status" 字段各值含义如下 :"0": 不踊跃 ;"1": 跟踪邮件打开情况 ;"2": 跟踪邮件打开与链接点击情况 2.2 获取指定日期的群发统计概览 接口功能 : 获取指定群发任务的跟踪统计概览 接口地址 : GET 参数 ( 必要参数 ): 1. "date": 所要获取的统计情况的日期 输出格式 : <?xml version="1.0" encoding="utf-8"?> <statistic> <date> 日期 </date> <ws_qty>web 发送统计任务量 </ws_qty> <ws_error>web 发送统计失败量 </ws_error> <ws_count>web 发送统计发送量 </ws_count> <invalid_addr> 无效地址量 </invalid_addr> <format_error> 格式错误量 </format_error> <send_count> 预统计发送量 </send_count> <deduc_count> 预扣点 </deduc_count> 7

8 <actual_send> 实际发送量 </actual_send> <send_error> 投递失败量 </send_error> <actual_deduc> 实际扣点量 </actual_deduc> <blacklist_count> 收件人黑名单数量 </blacklist_count> <refuse_count> 投诉地址量 </refuse_count> < _not_exist> 不存在邮箱地址数量 </ _not_exist> <jujue_count> 拒绝投递量 </jujue_count> </statistic> 2.3 导出发送失败地址 只导出发送失败地址 接口功能 : 只导出发送失败地址 接口地址 : ( 备注 : 该接口 api 和平台操作 smtp 对接方式均适用, 但是 smtp 对接方式无法准确获取 指定批次无效地址, 请悉知, 若要获取无效地址, 请务必不传 task_id 和 task_ident, 按 照日期获取, 或者使用 2.2 接口获取 ) GET 参数 : 1. "date"( 非必要参数,date,task_id,task_ident 必传其一即可 ): 所要导出失败地址批次任务的日期例 : , 不要传入 , 必须格式是 YYYY-MM-dd 2. "type"( 必要参数 ): 导出错误地址类型 "format_error" 或 9: 格式错误 ; "invalid_addr" 或 8: 无效地址 ; "not_exist" 或 1: 邮箱不存在 ; "over_quota" 或 2: 邮箱空间满 ; "user_reject" 或 3: 用户拒收 5: 拒绝投递 6: 地址是黑名单, 收件人黑名单 7: 投诉地址 4: 垃圾内容邮件 10: 连接异常 "all" 或 -1: 全部错误失败无效拒收等地址 3. task_id ( 非必要参数,date,task_id,task_ident 必传其一即可 ): 指定统计任务的 task_id, 非发送任务的任务 id(send_id), 而是根据 send_id 调用 3.1 获取指定群发任务的跟踪统计概览 获取返回的 task_id( 请特别注意 ) 8

9 4. task_ident ( 非必要参数,date,task_id,task_ident 必传其一即可 ): 指定的任务批次号, 就是获取该次任务批次相关的任务的错误地址记录 type 参数为 1,2,3 时,task_id 或者 task_ident 其一是必要参数 ( 批次号通过 3.1 接口获取 ) 5. out_type : out_type 参数省略时, 直接输出文本文件, 每行一个邮件地址 可取 file,json,xml 其中一个 输出格式 : 默认直接输出文本文件, 每行一个邮件地址 当 out_type 为空取 file,json, xml 分别表示导出 json,xml 格式数据 file 导出 csv;xml 结果返回示例 : <?xml version="1.0" encoding="utf-8"?> <fail_recipient_list> <recipient> < >violatte@coolreall.com</ > </recipient>... </fail_recipient_list> Json 结果返回示例 : [ " @qq.com", " @qq.com", ] 导出发送失败地址以及错误类型 (type) 以及任务 task_id 接口功能 : 导出发送失败地址以及错误类型以及 task_id 接口地址 : ( 备注 : 该接口 api 和平台操作 smtp 对接方式均适用, 但是 smtp 对接方式无法准确获取 指定批次无效地址, 请悉知, 若要获取无效地址, 请务必不传 task_id 和 task_ident, 按照 日期获取, 或者使用 2.2 接口获取 ) GET 参数 : 1. "date"( 非必要参数,date,task_id,task_ident 必传其一即可 ): 所要导出失败地址批次任务的日期例 : , 不要传入 , 必须格式是 YYYY-MM-dd 2. "type"( 必要参数 ): 导出错误地址类型 "format_error" 或 9: 格式错误 ; "invalid_addr" 或 8: 无效地址 ; "not_exist" 或 1: 邮箱不存在 ; "over_quota" 或 2: 邮箱空间满 ; "user_reject" 或 3: 用户拒收 9

10 5: 拒绝投递 6: 地址是黑名单, 收件人黑名单 7: 投诉地址 4: 垃圾内容邮件 10: 连接异常 "all" 或 -1: 全部错误失败无效拒收等地址 3. task_id ( 非必要参数,date,task_id,task_ident 必传其一即可 ): 指定统计任务的 task_id, 非发送任务的任务 id(send_id), 而是根据 send_id 调用 3.1 获取指定群发任务的跟踪统计概览 获取返回的 task_id( 请特别注意 ) 4. task_ident ( 非必要参数,date,task_id,task_ident 必传其一即可 ): 指定的任务批次号, 就是获取该次任务批次相关的任务的错误地址记录 type 参数为 1,2,3 时, task_id 或者 task_ident 其一是必要参数 ( 批次号通过 3.1 接口获取 ) 5. out_type : out_type 参数省略时, 直接输出文本文件, 每行一个邮件地址 可取 file,json,xml 其中一个 输出格式 : 默认直接输出文本文件, 每行一个邮件地址 当 out_type 为空取 file,json, xml 分别表示导出 json,xml 格式数据 返回的 task_id 指的是统计任务的 task_id, 非发送任务的任务 id(send_id), 而是根据 send_id 调用 3.1 获取指定群发任务的跟踪统计概览 获取返回的 task_id( 请特别注意 ), 返回的 type 参数代表意义如下 : 9: 格式错误 ; 8: 无效地址 ; 1: 邮箱不存在 ; 2: 邮箱空间满 ; 3: 用户拒收 5: 拒绝投递 6: 地址是黑名单, 收件人黑名单 7: 投诉地址 4: 垃圾内容邮件 10: 连接异常 file 导出 csv 格式 ; xml 结果返回示例 : <?xml version="1.0" encoding="utf-8"?> <fail_recipient_list> <recipient> 10

11 <type>3</type> <task_id> </task_id> </recipient> </fail_recipient_list> Json 格式结果样例 : [ { " ": " @qq.com", "type": "3", "task_id": " ", { " ": " @qq.com", "type": "3", "task_id": " ", ] 2.4 指定日期邮件批次发送扣点返点统计信息 接口功能 : 指定日期或者指定邮件批次发送统计表信息接口地址 : ( 备注 : 该接口 api 和平台操作 smtp 对接方式均适用, 但是 smtp 对接方式无法准确获取 指定批次无效地址, 请悉知, 若要获取无效地址数目, 请务必不传 ident, 按照日期获取, 或者使用 2.2 接口获取 ) GET 参数 : 1."date": 所要获取的统计情况的日期 2. ident : 具体的任务批次号 ( 批次号通过 3.1 章节接口获取 ) 3.id: 任务 id, 即 (6.2 章节接口 ) 创建任务时返回的 id 参数传值说明 : 只传 date 表示获取改发送日期的任务列表统计信息 ; 如果传 ident 和 id 其中之一代表获取具体任务的统计信息输出格式 : <?xml version="1.0" encoding="utf-8"?> <data> 11

12 <task> <task_id> 任务 id</task_id> <task_date> 日期 </task_date> <task_ident> 任务批次 </task_ident> <totalsum> 预计总发送量 (api 对接和平台包含格式错误的 投诉的等,smtp 对接则不包含包含格式错误的 投诉的等 )</totalsum> <total> 发送量 </total> <invalid> 无效地址和投诉 格式等未发送错误量 (smtp 方式传批次号时此数目会统计为 0,smtp 方式对接请 2.2 接口获取此数目 )</invalid> <failed> 总投递失败量包括发送失败和拒绝发送的數量 </failed> <send_failed> 总发送失败的數量 </send_failed> <success> 投递发送成功数 </success> < _not_exist> 邮箱不存在數 </ _not_exist> <spam_content> 垃圾内容数 </spam_content> <connect_error> 连接错误數 </connect_error> <actual> 实际扣点数 </actual> <over_quota> 空间不足 </over_quota> <user_reject> 用户拒收 </user_reject> <rubbish> 判为垃圾邮件拒绝发送的数量 </rubbish> <point> 任务当天扣点数 </point> <rebate> 返点数 </rebtae> </task>... </data> 2.5 指定日期扣点信息 接口功能 : 指定日期扣点信息 接口地址 : 此接口只能统计日扣点数, 需要统计某个任务实际扣点和返点请调用 2.4 接口 GET 参数 ( 必要参数 ): 1."date": 所要获取的统计情况的日期 输出格式 : <?xml version="1.0" encoding="utf-8"?> <data> <list> <date> 日期 </date> 12

13 <company> 公司名 </company> <deduction> 扣点类型 </deduction> <send_num> 发送数量 </send_num> <total> 扣量总计 </total> </list>... </data> 2.6 发送日志信息查询 接口功能 : 指定日期的发送日志查询接口地址 : 此接口只能统计固定日期的发送日志 GET 参数 ( 必要参数 ): 1."date": 所要获取的统计情况的日期 2 mail_to: 邮件发送给某人的输出格式 :json, 空日志格式返回 : {"lists": [] 13

14 三 跟踪统计相关接口 (Web 群发专用 ) 3.1 获取指定群发任务的跟踪统计概览 接口功能 : 获取指定群发任务的跟踪统计概览 ( 此接口可以通过任务 id 获取批次号 ident) 接口地址 : GET 参数 : 1. "id": 统计任务任务 id, 创建任务时返回的任务 id, 也就是 send_id 2. ident : 任务批次号参数 id,ident 三者必须有一个, 任意传一个即可输出格式 : <track> <track_id> 跟踪统计 id</track_id> 新增 <task_id> 统计任务 id</task_id> <task_sn> 任务批次号 ( 即 ident)</task_sn> <send_id> 任务 id</task_sn> <send_count> 发送量 </send_count> <real_send_count> 成功发送量 </real_send_count> <error_send_count> 失败量 </error_send_count> <open_unique> 唯一打开数 </open_unique> <open_total> 总打开数 </open_total> <open_first> 首次打开时间 </open_first> <open_last> 最后打开时间 </open_last> <click_unique> 唯一点击数 </click_unique> <click_total> 总点击数 </click_total> <click_first> 首次点击时间 </click_first> <click_last> 最后点击时间 </click_last> <open_ratio> 打开率 </open_ratio> <click_ratio> 点击率 </click_ratio> <link_statistic> <link> <link_id> 链接 id</link_id> <link> 链接 </link> <click_unique> 唯一点击数 </click_unique> <click_total> 总点击数 </click_total> <click_first> 首次点击时间 </click_first> 14

15 <click_last> 最后点击时间 </click_last> </link> <link>... </link>... </link_statistic> </track> 3.2 获取指定任务邮件打开统计详情 接口功能 : 获取指定群发任务邮件打开统计详情 接口地址 : GET 参数 : 1. "id": 群发任务 send_id, 也就是创建任务成功后返回的 task_id 2. ident : 任务批次号 ( 此批次号从接口 ) 参数 id,ident 两者必须有一个, 如果两个都存在, 取 ident 输出格式 : <?xml version="1.0" encoding="utf-8"?> <data> <user> < _id> 邮箱 id</ _id> < > 邮箱 </ > <browser> 浏览器 </browser> <os> 操作系统 </os> <addr_first> 首次打开地址 </addr_first> <ip_first> 首次打开 ip</ip_first> <ip_last> 最后打开 ip</ip_last> <addr_last> 最后打开地址 </addr_last> <open_total> 总打开数 </open_total> <click_total> 总点击数 </click_total> <open_first> 首次打开时间 </open_first> <open_last> 最后打开时间 </open_last> <click_first> 首次点击时间 </click_first> <click_last> 最后点击时间 </click_last> </user>... <data> 15

16 3.3 获取指定任务链接打开统计详情 接口功能 : 获取指定群发任务邮件打开统计详情 接口地址 : GET 参数 : 1. "id": 群发任务 send_id, 也就是创建任务成功后返回的 task_id 2. ident : 任务批次号 3. link_id : 链接 id, 指定任务指定链接点击统计详情参数 id,ident 两者必须有一个, 如果两个都存在, 取 ident 输出格式 : <?xml version="1.0" encoding="utf-8"?> <data> <click> <click_id> 点击 id</click_id> < > 邮箱地址 </ > <link> 链接地址 </link> <click_unique> 唯一点击数 </click_unique> <click_total> 总点击数 </click_total> <click_first> 首次点击时间 </click_first> <click_last> 最后点击时间 </click_last> </click>... <data> 3.4 导出指定群发任务跟踪邮箱信息 接口功能 : 导出指定群发任务跟踪统计邮箱信息接口地址 : GET 参数 : 16

17 1.track_id( 必须 ): 群发任务跟踪 id, 多模板任务发送此 track_id 有多个, 可以传入多个, 以英文逗号隔开, 例如 :38282, is_click:0 或 1,0 为导出所有邮箱,1 为只导出有点击的邮箱 3.link_id: 链接地址 id, 导出点击过该链接的邮箱 4. _id: 邮箱 id, 导出指定邮箱 17

18 3.5 指定批次的邮件各链接的点击统计 接口功能 : 指定批次的邮件各链接的点击统计 接口地址 : GET 参数 : 1. "id": 群发任务 send_id; 即创建任务时返回的 task_id 2. ident : 任务批次号 3. link_id : 链接 id, 指定任务, 指定链接点击统计参数 id,ident 两者必须有一个, 如果两个都存在, 取 ident 输出格式 : <?xml version="1.0" encoding="utf-8"?> <data> <link> <link_id> 链接 id</link_id> <link> 链接地址 </link> <click_unique> 唯一点击数 </click_unique> <click_total> 总点击数 </click_total> <click_first> 首次点击数 </click_first> <click_last> 最后点击数 </click_last> </link>... </data> 18

19 四 联系人分类相关接口 4.1 取得联系人分类列表 接口功能 : 取得联系人分类列表 接口地址 : 输出格式 : <?xml version="1.0" encoding="utf-8"?> <maillist> <item> <id> 联系人分类 ID</id> <subject> 联系人分类名称 </subject> <descrīption> 分类说明 </descrīption> <count> 地址数量统计 </count> <status> 联系人分类状态 </status> </item>... </maillist> 说明 : 1. "status": 当前联系人分类的状态,"enabled" 为正常使用,"disabled" 为禁止使用 4.2 取得联系人分类详情 接口功能 : 取得联系人分类详情 接口地址 : GET 参数 ( 必要参数 ): 1. "id": 联系人分类 ID 输出格式 : <?xml version="1.0" encoding="utf-8"?> <maillist> 19

20 <id> 联系人分类 ID</id> <subject> 联系人分类名称 </subject> <descrīption> 联系人分类说明 </descrīption> <count> 地址数量统计 </count> <status> 联系人分类状态 </status> </aillist> 说明 :"status" 字段含义同上 4.3 添加联系人分类 接口功能 : 添加联系人分类 接口地址 : POST 参数 : 1. "subject": 联系人分类名称 ( 必要参数 ) 2. "status": 联系人分类状态,"enabled" 为正常使用,"disabled" 为禁止使用 ( 必要参数 ) 3. "descrīption": 联系人分类说明 输出格式 : <?xml version="1.0" encoding="utf-8"?> <result> <status> 执行结果标识符 </status> <data>78</data> </result> 执行结果标识符说明 : 1. "add_maillist_error": 添加联系人分类时发生错误 2. "add_describe_error": 添加联系人分类描述信息时发生错误 3. "success": 添加联系人分类成功 4. "data": 添加联系人分类成功时 data 直接返回分类 id, 失败时则返回失败描述 4.4 修改联系人分类 接口功能 : 修改联系人分类 20

21 接口地址 : GET 参数 ( 必要参数 ): 1. "id": 联系人分类 ID POST 参数 : 1. "subject": 联系人分类主题 2. "status": 联系人分类状态,"enabled" 为正常使用,"disabled" 为禁止使用 3. "descrīption": 联系人分类说明 输出格式 : <?xml version="1.0" encoding="utf-8"?> <result> <status> 执行结果标识符 </status> <data> 执行结果说明 </data> </result> 执行结果标识符说明 : 1. "update_maillist_error": 修改联系人分类时发生错误 2. "update_describe_error": 修改联系人分类描述信息时发生错误 3. "success": 修改联系人分类成功 4.5 删除联系人分类 接口功能 : 删除联系人分类 接口地址 : GET 参数 ( 必要参数 ): 1. "id": 联系人分类 ID 输出格式 : <?xml version="1.0" encoding="utf-8"?> <result> <status> 执行结果标识符 </status> <data> 执行结果说明 </data> </result> 21

22 执行结果标识符说明 : 1. "delete_address_error": 删除联系人分类出错 2. "delete_describe_error": 删除联系人分类描述信息时发生错误 3. "delete_maillist_error": 删除联系人分类出错 4. "success": 删除联系人分类成功 4.6 导出联系人分类地址 接口功能 : 导入联系人分类地址 接口地址 : GET 参数 ( 必要参数 ): 1. "id": 联系人分类 ID 输出格式 : 直接输出文本文件, 每行格式为 邮件地址 \t 用户名称 邮件地址 4.7 导出退订地址接口功能 : 导出退订地址 接口地址 : GET 参数 ( 必要参数 ): 1. "id": 联系人分类 ID 输出格式 : 直接输出文本文件, 每行格式为 退订时间 \t 邮件地址 邮件地址 4.8 分类地址列表 接口功能 : 获取联系人分类下的地址信息或者单个地址信息 接口地址 : GET 参数说明 :( 红色必须 ) 22

23 1.list_id: 分类 id 必须以 get 方式传递, 如存在, 则查找该分类下的地址 否则查找全部 为 0 时查找未分类地址 2.address_id: 不传此参数, 代表获取当前分类, 当 address_id>0, 表示只获取此单个地址的信息返回 3.keyword: 在 address,fullname 两项中模糊查找 4.page: 分页数, 如果存在该参数, 则为分页查找, 否则为查找全部 5.limit: 分页查找时每页显示的数据记录数目, 默认为 50 输出格式 : <?xml version="1.0" encoding="utf-8"?> <data> <total_num> 地址总数目 </total_num > <addr> <id> 地址 id</id> <list_id> 邮件订阅 id</list_id> <address>![cdata[ 邮箱地址 ]]</address> <brithday> </brithday> <phone> </phone> <area>![cdata[ 深圳市福田区科技园中路 3 号 ]]</area> <fullname>![cdata[ 名称 ]]</fullname > <time> 添加时间 </time> <var1> 变量 1</var1> <var2> 变量 2</var2> <var3> 变量 3</var3> <var4> 变量 4</var4> <var5> 变量 5</var5> <var6> 变量 6</var6> <var7> 变量 7</var7> <var8> 变量 8</var8> <var9> 变量 9</var9> <var10> 变量 10</var10> </addr> <addr> <id> 地址 id</id> <list_id> 邮件订阅 id</list_id> <address>![cdata[ 邮箱地址 ]]</address> <brithday> </brithday> <phone> </phone> <area>![cdata[ 深圳市福田区科技园中路 3 号 ]]</area> <fullname>![cdata[ 名称 ]]</fullname > <time> 添加时间 </time> <var1> 变量 1</var1> <var2> 变量 2</var2> 23

24 <var3> 变量 3</var3> <var4> 变量 4</var4> <var5> 变量 5</var5> <var6> 变量 6</var6> <var7> 变量 7</var7> <var8> 变量 8</var8> <var9> 变量 9</var9> <var10> 变量 10</var10> </addr>... </data> 4.9 新增分类地址 添加一个 接口功能 : 增加联系人分类下的地址 接口地址 : GET 参数说明 :( 红色必须 ) 1.list_id: 分类 id 2.address: 邮箱地址 3.fullname: 用户名 4.var1,var2,,Var10: 变量 1~10 5.return_id: 成功返回信息包含新添加的地址 id,1 为包含,0 为不包含 默认为 0 6.sex 格式 :M (M 男 F 女 ) 7.birthday 格式 : phone 格式 : area 格式 : 北京市丰台 10.return_id: 成功是否返回地址主键 id,0 不返回,1 返回 说明 : 除 username,password,do 三个参数外, 其他的参数还可以通过 post 发送 批量添加 接口功能 : 增加联系人分类下的地址 接口地址 : 24

25 GET 参数说明 :( 红色必须 ) 1.list_id: 分类 id 2.addr_type: 地址信息数据类型, 默认为 string 3.separate: 每个地址信息之间的分隔符, 默认为 \n 换行符, 可以自定义任意字符 特别注意只在 addr_type 为 string 时生效 POST 参数说明 :( 红色必须 ) 1.ml_addr: 地址信息 说明 : ml_addr 为地址信息, 格式为 : 说明 : 邮箱地址 ; 名称 ; 性别 ; 生日 ; 手机 ; 地区 ; 变量 1; 变量 2; 变量 3; 变量 4; 变量 5; 变量 6; 变量 7; 变量 8; 变量 9; 变量 10( 换行 ) 格式 ( 一行一个地址信息 ): Coming1@bestdem.org;coming1;M; ; ; 北京 ;var1;var2;...var10; test@bestdem.org; test;f; ; ;area;var1;var2;...var10; 行行之间用换行符 \n 隔开, 同一行不同变量值之间用分号 ; 分割 适合批量添加, 但数目不 建议超过 500 以上, 如果超过 500 以上 ; 建议用 文件导入方式效率高 特别注意 \n 如果是代码拼接记得写成 %0A, 也就是 urlencode 后的值 从文件导入 接口功能 : 从文件中导入到联系人分类 接口地址 : GET 参数说明 :( 红色必须 ) 1.list_id: 分类 id, 也可通过 post 方式传送 POST 参数说明 :( 红色必须 ) 1.file: 文件信息示例 : 建立一个 html 表单, 上传文件 <form method="post" action=" ist_id=418804" 25

26 enctype="multipart/form-data"> <input type="file" name="file" /> <input type="submit" value="submit" /> </form> 说明 : 系统定时检测导入地址任务, 自动过滤无效地址和重复地址 从文件导入 Java 调用代码示例 ( 验证用户名密码并请参照第九章 java 上传代码 ): package cn.edu.ustc.file; import java.io.dataoutputstream; import java.io.file; import java.io.fileinputstream; import java.io.ioexception; import java.io.inputstream; import java.io.outputstream; import java.net.httpurlconnection; import java.net.malformedurlexception; import java.net.url; import java.util.uuid; public class UploadFileToPhp { private static final int TIME_OUT = 10 * ; // 超时时间 private static final String CHARSET = "utf-8"; // 设置编码 public static boolean uploadfile(file file) { String BOUNDARY = UUID.randomUUID().toString(); // 边界标识随机生成 String PREFIX = "--", LINE_END = "\r\n"; String CONTENT_TYPE = "multipart/form-data"; // 内容类型 String RequestURL = " 1"; System.out.println(RequestURL); try { URL url = new URL(RequestURL); HttpURLConnection conn = (HttpURLConnection) url.openconnection(); conn.setreadtimeout(time_out); conn.setconnecttimeout(time_out); conn.setdoinput(true); // 允许输入流 conn.setdooutput(true); // 允许输出流 conn.setusecaches(false); // 不允许使用缓存 conn.setrequestmethod("post"); // 请求方式 conn.setrequestproperty("charset", CHARSET); // 设置编码 conn.setrequestproperty("connection", "keep-alive"); conn.setrequestproperty("content-type", CONTENT_TYPE + ";boundary="+boundary); 26

27 if (file!= null) { /** * 当文件不为空, 把文件包装并且上传 */ OutputStream outputsteam = conn.getoutputstream(); DataOutputStream dos = new DataOutputStream(outputSteam); StringBuffer sb = new StringBuffer(); sb.append(prefix); sb.append(boundary); sb.append(line_end); /** * 这里重点注意 : name 里面的值为服务器端需要 key(php 里面需要是 file), 只有这个 key 才可以得到对应的文件 * filename 是文件的名字, 包含后缀名的比如 :abc.png, 可以看到下面在开始与结束都写入了一些分隔符等标示. */ sb.append("content-disposition: form-data; name=\"file\"; filename=\"" + file.getname() + "\"" + LINE_END); sb.append("content-type: application/octet-stream; charset=" + CHARSET + LINE_END); sb.append(line_end); dos.write(sb.tostring().getbytes()); InputStream is = new FileInputStream(file); byte[] bytes = new byte[1024]; int len = 0; while ((len = is.read(bytes))!= -1) { dos.write(bytes, 0, len); is.close(); dos.write(line_end.getbytes()); byte[] end_data = (PREFIX + BOUNDARY + PREFIX + LINE_END).getBytes(); dos.write(end_data); dos.flush(); /** * 获取响应码 200= 成功当响应成功, 获取响应的流 */ int res = conn.getresponsecode(); System.out.println(res); if (res == 200) { 27

28 /** * 获取内容在此写代码 */ return true; catch (MalformedURLException e) { e.printstacktrace(); catch (IOException e) { e.printstacktrace(); return false; public static void main(string[] args) { File file = new File("/dir/address.txt"); boolean res = uploadfile(file); System.out.println(res); address.txt 格式说明 : 邮箱地址 ; 名称 ; 性别 ; 生日 ; 手机 ; 地区 ; 变量 1; 变量 2; 变量 3; 变量 4; 变量 5; 变量 6; 变量 7; 变量 8; 变量 9; 变量 10( 换行 ) 格式 : Coming1@bestdem.org;coming1;M; ; ; 北京 ;var1;var2;...var10; test@bestdem.org; test;f; ; ;area;var1;var2;...var10; 一行一个地址信息 ; 每行各个参数之间用 ; 隔开 适合批量添加输出格式 : <?xml version="1.0" encoding="utf-8"?> <result> <status>success</status> <data><![cdata[10]]></data>;//10 为查询是否解析成功的标识 id, 需要记录 </result> Eg: 28

29 4.9.4 从文件导入查询地址是否解析成功 接口功能 : 文件导入到联系人分类后查询地址是否解析成功接口地址 : 1 GET 参数说明 :( 红色必须 ) 1.id: 文件导入后返回的 id 输出格式 : <?xml version="1.0" encoding="utf-8"?> <result> <status>success</status> <data><![cdata[ 解析完成 ]]></data>; </result> Status 返回值说明 : success/not_exist/error/no_complete 解析完成 / 不存在 id/ 参数错误 / 正在解析 4.10 修改分类地址 接口功能 : 修改联系人分类下的地址 接口地址 : GET 参数说明 :( 红色必须 ) 1.id: 地址 id 2.address: 邮箱地址 3.fullname: 用户名 4.var1,var2. Var10: 变量 1~10 6.sex 格式 :M (M 男 F 女 ) 7. birthday 格式 : phone 格式 : area 格式 : 北京市丰台 说明 : 除 username,password,do 三个参数外, 其他的参数还可以通过 post 发送 4.11 删除分类地址 接口功能 : 删除联系人分类下的地址 29

30 接口地址 : GET 参数说明 :( 红色必须 ) 1.id: 地址 id 4.12 清空联系人分类 接口功能 : 清空联系人分类下的地址 接口地址 : GET 参数说明 :( 红色必须 ) 1.list_id: 联系人分类 id 4.13 邮件订阅接口功能 : 添加地址到订阅列表 接口地址 : 邮件订阅 id&address=xxx@xxx.com&name= 邮箱用户名称 GET 参数 ( 必要参数 ): 1,"list_id": 邮件订阅 ID 2,"address": 订阅邮箱 3,"name": 邮箱用户名称 4,"maillist": 批量订阅邮箱地址 说明 : name 参数如果没有提供, 默认取邮箱名 如 test@bestedm.com, 名称就取 test address,name 两参数, 添加一个地址时使用 maillist 批量添加时使用, 可通过 get 或者 post 传递, 格式为 : 格式 1: 邮箱 1, 名称 1; 邮箱 2, 名称 2;... test1@bestedm.com,test1;test2@bestedm.com,test2;... 格式 2: 一行为一个地址信息, 邮箱与名称之间用 tab 键或者, 分隔 邮箱 1 名称邮箱 2 名称... test1@bestedm.com test1 test2@bestedm.com test2 30

31 4.14 邮件退订 接口功能 : 删除邮件订阅中的地址 接口地址 : 邮件订 阅 id&address=xxx@xxx.com GET 参数 ( 必要参数 ): 1,"list_id": 邮件订阅 ID 2,"address": 退订邮箱 说明 : address 可通过 get 或者 post 传递, 格式为 : 格式 1: 邮箱 1, 邮箱 2,... test1@bestedm.com,test2@bestedm.com,... 格式 2: 一行为一个地址信息邮箱 1 邮箱 2... test1@bestedm.com test2@bestedm.com 4.15 导入分类地址记录查询 接口功能 : 导入分类地址记录查询 接口地址 : 说明 : 返回数据说明 <?xml version="1.0" encoding="utf-8"?> <result> <status>success</status> <data> <address_log> <filename> list2017.csv</filename> // 文件名称 <filepath>/usr/local/umail/data/web/mm-ms/cache/ _71607.csv</filepath> 31

32 // 文件服务器路径 <time_import> :42:20</time_import>// 上传时间 <count_all>0</count_all>// 导入地址总量 <count_err_1>0</count_err_1>// 无效地址数 <count_err_2>0</count_err_2>// 重复的地址数 <status>-2</status>// 导入的状态 1 成功 -1/-2/-3 失败 <subject>ddd</subject>// 导入列表 </address_log> </data> </result> 五 邮件模板相关接口 5.1 创建群发任务 接口功能 : 创建群发任务 接口地址 : nd_domain=comingchina.com&send_account=linbihuan@comingchina.com&send _fullname=linbihuan&maillist_id=5&time= :00 GET 参数说明 :( 红色必须 ) 1.tpl_id: 模板 id 单个模板请传入 2, 该任务有多个模板则 1,2,3,78 逗号隔开格式 ( 可以填写自己和子帐号共享模板 id) 2.send_domain: 发件人域名 3.send_account: 发件人 4.send_fullname: 发件人名称 5.maillist_id: 联系人分类 id 6.send_qty : 联系人发送地址数量范围最大值, 默认为 0, 表示全部地址, 结合 send_qty_start 代表发送地址范围 2-30,50-100, 如 :send_qty_start=10,send_qty=100 表示到从第 个地址开始发送 7.send_qty_start: 联系人发送地址范围开始最小值, 为 1, 表示从第一个地址开始, 注意必须大于 1, 此值不能传 0 8.status: 发送状态, 默认为 1, 等待启动发送 ;-1 为暂不发送 ;-2 暂停发送,-3 取消发送, 2 为立即发送,3 发送完成 0 为等待发送, 1 为等待启动发送 2 为正在发送 32

33 3 为发送完成 4 任务停止 -1 为暂不发送 -2 为暂停发送 -3 为取消发送 -4 为发送出错 -5 为等待入库启动 9.time: 发送时间, 必须 格式 %2016:08, 即 :08 经过 urlencode 转义后的值, 否则空格无法识别 10.subs_link: 是否在邮件中加入退订订阅链接 默认为 1, 加入 11 track_status: 是否开启邮件跟踪 默认为 0, 不开启, 默认为 0, 不开启 1 只开 启打开统计 2 开启打开统计和点击链接跟踪统计 12 track_domain: 自定义跟踪统计链接域名 13.send_replyto: 指定发送回复邮箱地址 例如 :repaly@126.com 14.hour_speed: 指定发送速率 ; 取值 100 至 75000( 单位 : 每小时最大发送量设置 ) 15.is_need_receipt: 阅读回执 ;1 则可以阅读回执,0 则不行. 默认不传则为 0, 注意此参 数依赖于是否开通阅读回执服务, 没开通则任务无法修改此参数, 即无法进行阅读回执 备注 : 1. 除参数 username,password,do 之外, 其它参数均可通过 get 或者 post 方式发送 2. 如果发件人是某个域名下的所有发件人, 参数 send_domai 为域名,send_account 为 all 如:&send_domain=comingchina.com&send_account=all 3. 如果发件人是所有域名下的所有发件人, 参数 send_domain,send_account 两个都为 all 如 :&send_domain=all&send_account=all 4. 如果发件人只是某个域名下的一个发件人 Send_domain 可以不需要 如 : &send_account=test@comingchina.com 备注 : 调用此接口 1 小时调用次数不呢超过 100 次 输出格式 : 成功 : <?xml version="1.0" encoding="utf-8"?> <result> <status>success</status> <id> 新创建的任务 id</id> <data><![cdata[ 添加群发任务成功!]]></data> </result> 33

34 错误 : <?xml version="1.0" encoding="utf-8"?> <result> <status> 错误状态 </status> <data><![cdata[ 错误描述 ]]></data> </result> 5.2 上传邮件模板 接口功能 : 上传邮件模板 ( 可上传附件 ) 接口地址 : GET 参数说明 : 1.do: 操作类型, 必须 POST 参数说明 : 1.name: 邮件名称, 必须 2.subject: 邮件主题, 必须, 多个模板主题请以 隔开 ; 如 : 主题一 主题二 3.content: 邮件内容, 必须 4.text_content: 纯文本内容,html 邮件内容无法显示时, 显示纯文本内容 5.encoding: 邮件发送编码,base64 或者 quoted-printable 6.file: 附件参数 Input 标签中 name 属性的值为 file, 如果是上传多个文件, 那么 name 属性值为 file[] 说明 : 成功返回新建模板的 id 值 Php 上传附件演示代码 : <?php /** * Created by api 接口对接群发新增带附件模板附件 php 演示代码. * User: yzg * Date: 2018/4/18 * Time: 16:55 */ function sendcurlpost() { $vars = array(); $vars['list_id'] = ;// 联系人分类 id $vars['name'] ='cesshi';// 模板名称 $vars['subject'] ='subsject';// 模板主题 34

35 件 $vars['content'] ='test';// 模板内容 $vars['file'] = '@'. dirname( FILE ).'\121.jpg';// 要上传的附 /* 初始化并执行 curl 请求 */ $ch = curl_init(); $opts = array( CURLOPT_TIMEOUT => 50, CURLOPT_HTTPAUTH=>CURLAUTH_BASIC, CURLOPT_USERPWD=>' 你的用户名 : 你的密码 ', CURLOPT_RETURNTRANSFER => 1, CURLOPT_BINARYTRANSFER=>1, CURLOPT_URL => ' ); CURLOPT_POST => 1, CURLOPT_POSTFIELDS CURLOPT_USERAGENT CURLOPT_SSL_VERIFYPEER CURLOPT_SSL_VERIFYHOST CURLOPT_HEADER=>0 curl_setopt_array($ch, $opts); => $vars, => $_SERVER['HTTP_USER_AGENT'], => FALSE, => FALSE, $status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); status code ; $data = curl_exec($ch); curl_close($ch); return $data; var_dump(sendcurlpost()); //get C# 示例代码 : string url = " string username = "mxxxxxx"; string password = "xsxxxxxx"; string sub = " 中国 ( 上海 ) 国际婚纱摄影器材展览会展周边报价单 < 盟轩 : 客服 -admin>"; string name = "admin 中国 ( 上海 ) 国际婚纱摄影器材展览会模版 "; FileStream fs = new FileStream(@"c:\test\1.html", FileMode.OpenOrCreate, FileAccess.Read); StreamReader sr = new StreamReader(fs, Encoding.Default); 35

36 string mcontent = sr.readtoend(); sr.close(); fs.close(); string postdata = string.format("&name={0&subject={1&content={2",name, sub, mcontent); byte[] data = Encoding.UTF8.GetBytes(postData); Encoding encoding = Encoding.Default; HttpWebRequest myreq = (HttpWebRequest)WebRequest.Create(url); myreq.method = "POST"; myreq.contenttype = "application/x-www-form-urlencoded; charset=utf-8"; // 注意这里的格式哦, 为 "username:password" string username_password = username + ":" + password; CredentialCache mycache = new CredentialCache(); mycache.add(new Uri(url), "Basic", new NetworkCredential(username, password)); myreq.credentials = mycache; myreq.headers.add("authorization", "Basic " + Convert.ToBase64String(new ASCIIEncoding().GetBytes(username_Password))); myreq.contentlength = data.length; Stream newstream = myreq.getrequeststream(); // Send the data. newstream.write(data, 0, data.length); newstream.close(); WebResponse wr = myreq.getresponse(); Stream receivestream = wr.getresponsestream(); StreamReader reader = new StreamReader(receiveStream, Encoding.UTF8); string content = reader.readtoend(); 5.3 获取邮件模板检测状态和模板信息 接口功能 : 查看模板是否已经可以使用以及模板大小, 检测状态 接口地址 : GET 参数说明 : 1 do: 操作类型, 必须 GET 参数说明 : 2 tpl_id: 模板 id, 必须 36

37 输出格式 : <?xml version="1.0" encoding="utf-8"?> <template> <id>53</id> <name> 模板名称 </name> <status>1</status> <colour>green</colour><update_date> :11:11</update_date> <size_status>1</size_status> <size>78</size> <subject> 模板主题 </subject> </template> 说明 :size 的单位大小为 kb;size_status=-1 表示模板大小正在统计中,size_status=1 表示模板大小已经统计完毕 ;size 为真实模板邮件大小 status 为 -1 代表模板正在检测中,0 标识检测为红色模板不予通过 (red),1 表示检测通过为绿色或者黄色或者红绿色 (yellow,green,red_pass);update_date 模板更新时间,name 代表模板名称 ;colour 代表模板检测后的标识颜色, 正在检测中则为空 5.4 模板列表 接口功能 : 获取用户模板列表 接口地址 : GET 参数说明 :( 红色必须 ) 1. tpl_id : 模板 id, 如果存在, 则只获取该 id 值的模板信息 否则获取全部模板信息 输出格式 : <?xml version="1.0" encoding="utf-8"?> <template_list> <template> <id>53</id> <user_id> 模板 id</user_id> <name> <![CDATA[ 模板名称 ]]> </name> <subject> <id> 模板主题一 id</id> <name><![cdata[ 模板主题 1]]></name> 37

38 </subject> <subject> <id> 模板主题二 id</id> <name><![cdata[ 模板主题 2]]></name> </subject> <content> <![CDATA[ 模板内容 ]]> </content> <content_type> 模板类型 </content_type> <attachments> 新增附件信息 <attachment> <atta_id> 附件 id</atta_id> <atta_name> 附件文件名 </atta_name> </attachment> </attachments> <created> 创建时间 </created> <updated> 更新时间 </updated> </template> <template>... </template>... </template_list> 5.5 删除模板 接口功能 : 删除指定 id 模板 接口地址 : GET 参数说明 : 1. tpl_id : 模板 id 38

39 5.6 修改模板 接口功能 : 修改指定模板接口地址 : bihuan&subject=sub&content=con GET 参数说明 : 1. tpl_id : 模板 id, 也可通过 post 上传, 必须 2. name : 模板名称, 也可通过 post 上传 3. subject : 模板主题, 也可通过 post 上传, 多个模板主题请以 隔开 ; 如主题一 主题二 4. content : 模板内容, 也可通过 post 上传 5.text_content: 纯文本内容,html 邮件内容无法显示时, 显示纯文本内容 6.encoding: 邮件发送编码,base64 或者 quoted-printable 备注 : 1.tpl_id 参数必须,name subject content 三个参数必须至少有一个 2. 四个参数均可以通过 post 或者 get 方式上传 5.7 上传模板附件 接口功能 : 上传模板附件接口地址 : 7 GET 参数说明 : 1. tpl_id : 模板 id, 也可通过 post 上传, 必须 POST 参数说明 : 1. file : 附件参数名 Input 标签中 name 属性的值为 file, 如果是多附件, 该属性 值为 file[] Php 上传演示代码 /** * Created by api 接口对接群发上传制定模板附件 php 演示代码. * User: yzg * Date: 2018/4/18 39

40 * Time: 16:55 */ function sendcurlpost() { 件 $vars = array(); $vars['file'] = '@'. dirname( FILE ).'\122.jpg';// 要上传的附 /* 初始化并执行 curl 请求 */ $ch = curl_init(); $opts = array( CURLOPT_TIMEOUT => 300, CURLOPT_HTTPAUTH=>CURLAUTH_BASIC, CURLOPT_USERPWD=>' 你用户名 : 你的密码 ', CURLOPT_RETURNTRANSFER => 1, CURLOPT_BINARYTRANSFER=>1, CURLOPT_URL => ' nt-add&tpl_id=255288', ); CURLOPT_POST => 1, CURLOPT_POSTFIELDS CURLOPT_USERAGENT CURLOPT_SSL_VERIFYPEER CURLOPT_SSL_VERIFYHOST CURLOPT_HEADER=>0 curl_setopt_array($ch, $opts); => $vars, => $_SERVER['HTTP_USER_AGENT'], => FALSE, => FALSE, $status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); status code ; $data = curl_exec($ch); curl_close($ch); return $data; var_dump(sendcurlpost()); //get 5.8 删除模板附件 接口功能 : 删除模板附件接口地址 : 7&attachment_id=1 GET 参数说明 : 40

41 1. tpl_id : 模板 id, 也可通过 post 上传, 必须 2. attachment_id : 附件 id, 默认为 all, 删除模板中所有附件 六 群发任务相关接口 6.1 群发任务列表 接口功能 : 获取用户群发任务列表 接口地址 : GET 参数说明 :( 红色必须 ) 1. do : 操作类型 2. id : 任务 id, 如存在该参数, 则只返回该任务的信息, 否则返回所有任务信息 3. page : 页数, 从 1 开始 4. limit : 每页显示的任务数, 如果没有指定, 默认为 date : 发送日期, 如 send_status : 任务发送状态 默认为 all, 表示所有群发任务 0 为等待发送 1 为等待启动发送 2 为正在发送 3 为发送完成 4 任务停止 -1 为暂不发送 -2 为暂停发送 -3 为取消发送 -4 为发送出错 -5 为等待入库启动 备注 :page,limit 两个参数如果都没有指定, 默认获取全部任务列表 输出格式 : <?xml version="1.0" encoding="utf-8"?> <task_list> 41

42 <task> <id> 任务 id</id> <sn> 任务号 </sn> <acct_type> 发件人类型 (all,domain,address)</acct_type> <acct_domain> 发件人域名, 发件人类型为 domain 时存在 </acct_domain> <acct_address> 发件人, 发件人类型为 address 时存在 </acct_address> <sender> 发件人 </sender> <replyto> 回复地址 </replyto> <sender_name> 发件人姓名 </sender_name> <templates> <template> <tpl_id> 模板 id</tpl_id> <tpl_name> 模板名称 </tpl_name> </template> <template> <tpl_id> 模板 id</tpl_id> <tpl_name> 模板名称 </tpl_name> </template> </templates> <addr_type> 地址类型 </addr_type> <listes> <item> <list_id> 联系人分类 id</list_id> <list_name> 联系人分类名称 </list_name> </item> </listes> <send_qty> 预定发送数量 ( 用户指定 )</send_qty> <send_qty_remak> 预定发送数量 ( 实际发送 )</send_qty_remak> <send_time> 预定发送时间 </send_time> <time_start> 实际发送开始时间 </time_start> <time_end> 实际发送结束时间 </time_end> <send_count> 实际发送数量 </send_count> <error_count> 发送失败数量 </error_count> <send_status> 发送状态 </send_status> <track_status> 跟踪统计状态数字 (0 不跟踪 1 跟踪邮件打开情况 2 跟踪邮件打开与链接点击情况 ) </track_status> </task> <task>...</task>... </task_list> 42

43 6.2 创建群发任务接口功能 : 创建群发任务 接口地址 : nd_domain=comingchina.com&send_account=linbihuan@comingchina.com&send _fullname=linbihuan&maillist_id=5&time= %3a54%3a01 GET 参数说明 :( 红色必须 ) 1.tpl_id: 模板 id 单个模板请传入 2, 该任务有多个模板则 1,2,3,78 逗号隔开格式 ( 可 以填写自己和子帐号共享模板 id) 2.send_domain: 发件人域名 3.send_account: 发件人 4.send_fullname: 发件人名称 5.maillist_id: 联系人分类 id 6.send_qty_start: 联系人发送地址范围开始最小值, 为 1, 表示从第一个地址开始, 此值 不能传 0 7.send_qty : 联系人发送地址数量范围最大值, 默认为 0, 表示全部地址, 结合 send_qty_start 代表发送地址范围 2-30,50-100, 如 :send_qty_start=10,send_qty=100 表示到从第 个地址开始发送 8.status: 发送状态, 默认为 2,1 为等待启动发送 ;2 为立即发送,-2 暂停发送,-3 取消 发送,3 发送完成 ;-1 为暂不发送 ;-2 暂停发送,-3 取消发送,2 为立即发送,3 发送完成 0 为等待发送, 1 为等待启动发送 2 为正在发送 3 为发送完成 4 任务停止 -1 为暂不发送 -2 为暂停发送 -3 为取消发送 -4 为发送出错 -5 为等待入库启动 9.time: 发送时间, 必须 格式 :08:56 或者 :08 或者 请 urlencode 传入 当 status=2 时 time 大于等于当前时间即可立即发送 10.subs_link: 是否在邮件中加入退订订阅链接 默认为 1, 加入 11.track_status: 是否开启邮件跟踪 默认为 0, 不开启 1 只开启打开统计 2 开启打开统 计和点击链接跟踪统计 12.track_domain: 自定义跟踪统计链接域名 13.hour_speed: 指定发送速率 ; 取值 100 至 75000( 单位 : 每小时最大发送量设置 ) 14.track_domain: 自定义跟踪域名 15.send_replyto: 指定回复地址 43

44 16.is_need_receipt: 阅读回执 ;1 则可以阅读回执,0 则不行. 默认不传则为 0, 注意此参 数依赖于是否开通阅读回执服务, 没开通则任务无法修改此参数, 即无法进行阅读回执 备注 : 1. 除参数 username,password,do 之外, 其它参数均可通过 get 或者 post 方式发送 2. 如果发件人是某个域名下的所有发件人, 参数 send_domain 为域名,send_account 为 all 如:&send_domain=comingchina.com&send_account=all 3. 如果发件人是所有域名下的所有发件人, 参数 send_domain,send_account 两个都为 all 如 :&send_domain=all&send_account=all 4. 如果发件人只是某个域名下的一个发件人 Send_domain 可以不需要 如 : &send_account=test@comingchina.com 6.3 修改群发任务 接口功能 : 修改群发任务 接口地址 : domain=comingchina.com&send_account=linbihuan@comingchina.com&send_fu llname=linbihuan&maillist_id=5&time= %2012:00 GET 参数说明 :( 红色必须 ) 1.id: 任务 id 2.tpl_id: 模板 id 单个模板请传入 2, 该任务有多个模板则 1,2,3,78 逗号隔开格式 ( 可以填写自己和子帐号共享模板 id) 3.send_domain: 发件人域名, 默认填 all 4.send_account: 发件人, 默认填 all 5.send_fullname: 发件人名称 6.maillist_id: 联系人分类 id 7.send_qty_start: 联系人发送地址范围开始最小值, 为 1, 表示从第一个地址开始, 此值不能传 0 8.send_qty : 联系人发送地址数量范围最大值, 默认为 0, 表示全部地址, 结合 send_qty_start 代表发送地址范围 2-30,50-100, 如 :send_qty_start=10,send_qty=100 表示到从第 个地址开始发送 9.send_status: 发送状态, 默认为 1 等待启动发送 0 为等待发送, 1 为等待启动发送 2 为正在发送 3 为发送完成 4 任务停止 -1 为暂不发送 -2 为暂停发送 44

45 -3 为取消发送 -4 为发送出错 -5 为等待入库启动 10.send_time: 发送时间, 格式 :08:56 或者 :08 或者 请 urlencode 传入 11.subs_link: 是否在邮件中加入退订订阅链接 (0,1) 12.track_status: 是否开启邮件跟踪 (0,1,2) 0 是否开启邮件跟踪 默认为 0, 不开启 1 只开启打开统计 2 开启打开统计和点击链接跟踪统计 13.track_domain: 自定义跟踪域名 14.send_replyto: 指定回复地址 15.hour_speed: 指定发送速率 ; 取值 100 至 75000( 单位 : 每小时最大发送量设置 ) 16.is_need_receipt: 阅读回执 ;1 则可以阅读回执,0 则不行. 默认不传则为 0, 注意此参 数依赖于是否开通阅读回执服务, 没开通则任务无法修改此参数, 即无法进行阅读回执 备注 : 1. 除参数 username,password,do 之外, 其它参数均可通过 get 或者 post 方式发送 2. 如果发件人是某个域名下的所有发件人, 参数 send_domain 为域名,send_account 为 all 如:&send_domain=comingchina.com&send_account=all 3. 如果发件人是所有域名下的所有发件人, 参数 send_domain,send_account 两个都为 all 如 :&send_domain=all&send_account=all 4. 如果发件人只是某个域名下的一个发件人 Send_domain 可以不需要 如 : &send_account=test@comingchina.com 6.4 删除群发任务 接口功能 : 删除群发任务 接口地址 : GET 参数说明 :( 红色必须 ) 1.id: 任务 id 七 域名及域名下的邮箱账号 45

46 7.1 域名列表接口功能 : 获取域名列表 接口地址 : GET 参数说明 :( 红色必须 ) 1.customer_id: 客户 id 2.user_type: 用户类型 manager 或 customer, 默认为 customer 如果是 manager,username 跟 password 两个参数必须是管理员的用户名跟密码, 需要加 customer_id user_type 两参数 输出格式 : <?xml version="1.0" encoding="utf-8"?> <domain_list> <data> <customer_id> 客户 id(0 为系统域名 )</customer_id> <domain> 域名 </domain> </data> <data>...</data>... </domain_list> 7.2 添加域名接口功能 : 添加域名 接口地址 : &domain=*** 返回 : 添加成功并域名配置成功返回结果 <result> <status>success_and_check_ok</status> <data>23</data> </result> 添加成功但域名配置没有成功返回结果 <result> <status>success</status> <data>23</data> </result> 46

47 Data 为域名主键 id 7.3 验证域名接口功能 : 验证域名 DNS 是否已经配置正确 接口地址 : POST 参数说明 : domains : 要检测域名列表 多个域名用逗号隔开格式 test.com,we.com,me.com 输出格式 : <?xml version="1.0" encoding="utf-8"?> <domain_list> <domain> <customer_id>2369</customer_id> <domain_id>3213</domain_id> <val>test.com</val> <status>3</status> <info> 添加成功并验证通过 </info> </domain> <domain> <customer_id>2369</customer_id> <domain_id>6731</domain_id> <val>we.com</val> <status>2</status> <info> 添加成功但验证不通过 </info> </domain> <domain> <customer_id>2369</customer_id> <domain_id>0</domain_id> <val>me.com</val> <status>0</status> <info> 系统不存在并验证不通过 </info> </domain> </domain_list> 说明 : 47

48 domain_id>0 表示系统已经存在此域名, 否则不存在 ;status=3 表示添加成功并验证 通过,status=2 表示添加成功但验证不通过 ;status=1 表示系统不存在但验证通过 ; status=0 表示系统中不存在并验证不通过 如果添加域名想验证通过 ; 需要 DNS 服务提供商处添加相关配置记录方可验证通过 具体配置如下 : 比如您的添加域名为 magvision.com 7.4 为指定子账号用户添加域名 ( 管理员账号才可调用 ) 接口功能 : 为指定子账号用户添加域名接口地址 : &domain=*** GET 参数说明 :( 红色必须 ) 1.customer_id: 指定客户的 id 如 2 2.domain: 需要添加的域名, 如 test.com 7.5 删除指定子帐号的域名 ( 管理员账号才可调用 ) 接口功能 : 删除域名 接口地址 : 48

49 &domain=*** GET 参数说明 :( 红色必须 ) 1.customer_id: 客户 id 2.domain: 需要添加的域名, 如 test.com 7.6 删除域名接口功能 : 删除域名 接口地址 : 说明 : 已经验证通过的域名不能删除 7.7 指定域名下的账号列表接口功能 : 获取指定域名下的账号列表 接口地址 : GET 参数说明 :( 红色必须 ) 1.customer_id: 客户 id 2.domain: 需要添加的域名, 如 test.com 3.user_type: 用户类型 manager 或 customer, 默认为 customer 如果是 manager,username 跟 password 两个参数必须是管理员的用户名跟密码, 需要加 customer_id user_type 两参数 4.page: 分页数, 如果存在该参数, 则为分页查找, 否则为查找全部 5.limit: 分页查找时每页显示的数据记录数目, 默认为 30 输出格式 : <?xml version="1.0" encoding="utf-8"?> <mailbox_list> <data> <customer_id> 客户 id</customer_id> <domain> 域名 </domain> <name> 账号 </name> <mailbox> 完整账号 </mailbox> </data> 49

50 <data>...</data>... </mailbox_list> 7.8 添加账号到指定域名接口功能 : 添加账号到指定域名 接口地址 : &pwd=*** GET 参数说明 :( 红色必须 ) 1.pwd: 添加账号的密码 2.mailbox: 需要添加的账号, 如 test@test.com 3.customer_id: 客户 id 4.user_type: 用户类型 manager 或 customer, 默认为 customer 如果是 manager,username 跟 password 两个参数必须是管理员的用户名跟密码, 需要加 customer_id user_type 两参数 7.9 删除指定域名下的账号接口功能 : 删除指定域名下的账号 接口地址 : GET 参数说明 :( 红色必须 ) 50

51 1.mailbox: 需要删除的账号, 如 2.customer_id: 客户 id 3.user_type: 用户类型 manager 或 customer, 默认为 customer 如果是 manager,username 跟 password 两个参数必须是管理员的用户名跟密码, 需要加 customer_id user_type 两参数 7.10 修改指定域名的账号接口功能 : 修改指定域名下的账号 接口地址 : *&pwd=*** GET 参数说明 :( 红色必须 ) 1.pwd: 修改账号的密码 2.mailbox: 需要修改的账号, 如 test@test.com 3.customer_id: 客户 id 4.user_type: 用户类型 manager 或 customer, 默认为 customer 如果是 manager,username 跟 password 两个参数必须是管理员的用户名跟密码, 需要加 customer_id user_type 两参数 51

52 八 其他 8.1 客户自定义群发登录页面说明说明 : form 表单的 action 属性为 如果用户名或者密码错误返回页面也是自定义的, 在表单中另外 post 提交一个参数 errurl, 该参数值为错误返回的 url, 必须要有 示例 : <form action=" method="post"> <input type="hidden" name="errurl" value=" /> <input type="text" name="username" /> <input type="password" name="password" /> <select name="user_type"> <option value=""> 普通用户 </option> <option value="agents"> 代理商 </option> <option value="manager"> 管理员 </option> </select> <input name="submit" type="submit" value=" 提交 " /> </form> 九 用户认证方式示例代码以及接口调用示例代码 调用接口前, 请务必知晓此更改, 验证方式已经更改 为加强平台的安全性, 现更新修改群发所有接口的认证方式 old 认证方式 : 将 username 和 password 以 GET 参数传递, password 为 md5 加密后的密码 ; 如接口 : 取得指定日期的群发任务列表 接口地址 : new 修改后的认证方式 :HTTP Basic Authentication, 在请求头中添加 Authorization 注意 : 传递的 password 是没有加密以前的密码 52

53 9.1 Python 用户认证示例代码 下面用 curl 命令和 python 代码实现请求 1.curl 命令 #curl -u username:password 2.python 代码请求 import urllib2, base64 username = 'XXXX' password = 'XXXXX' url = ' request = urllib2.request(url) base64string = base64.encodestring('%s:%s' % (username, password)).replace('\n', '') request.add_header("authorization", "Basic %s" % base64string) result = urllib2.urlopen(request) 9.2 C# 用户认证示例代码 : HttpWebRequest myreq = (HttpWebRequest)HttpWebRequest.Create(" 接口地址 "); string username="username"; string password="password"; // 注意这里的格式哦, 为 "username:password" string usernamepassword = username + ":" + password; CredentialCache mycache = new CredentialCache(); mycache.add(new Uri(url), "Basic", new NetworkCredential(username, password)); myreq.credentials = mycache; myreq.headers.add("authorization", "Basic " + Convert.ToBase64String(new ASCIIEncoding().GetBytes(usernamePassword))); WebResponse wr = myreq.getresponse(); Stream receivestream = wr.getresponsestream(); StreamReader reader = new StreamReader(receiveStream, Encoding.UTF8); string content = reader.readtoend(); 53

54 9.3 java 用户认证示例代码 : HttpGet request = new HttpGet(URL_SECURED_BY_BASIC_AUTHENTICATION); String auth = DEFAULT_USER + ":" + DEFAULT_PASS; byte[] encodedauth = Base64.encodeBase64(auth.getBytes(Charset.forName("US-ASCII"))); String authheader = "Basic " + new String(encodedAuth); request.setheader(httpheaders.authorization, authheader); HttpClient client = HttpClientBuilder.create().build(); HttpResponse response = client.execute(request); int statuscode = response.getstatusline().getstatuscode(); assertthat(statuscode, equalto(httpstatus.sc_ok)); 特别注意 : 在调用 api 接口时如果需要传入中文请务必指定 http 头为 utf-8 格式, 并把所传中 文转为 utf-8 格式, 如下图代码所示 : 54

55 9.4 php 用户认证示例代码 方法一 ://--- 使用 fsocket 的方式验证用户名和密码 $url = 'api 地址 ; $fp = fsockopen("$url",80); fputs($fp,"get /downloads HTTP/1.0"); fputs($fp,"host: $url"); fputs($fp,"authorization: Basic ". base64_encode("user:pass"). ""); 55

56 fpassthru($fp); 推荐方法二 ://--- 使用 CURL 扩展的方式验证密码并调用接口 //--- 使用 CURL 扩展的方式 if(extension_loaded('curl')){ $username ="1xx2";// 用户名 $password ="xxxxxx";// 密码 $url = ' t&list_id=461253&page=1&limit=1'; // $params =array(); // $vars = http_build_query($params); //post 方式 // $opts = array( // CURLOPT_TIMEOUT => 5, // CURLOPT_HTTPAUTH=>CURLAUTH_BASIC, // CURLOPT_USERPWD=>"$username:$password", // CURLOPT_RETURNTRANSFER => 1, // CURLOPT_URL => $url, // CURLOPT_POST => 1, // CURLOPT_POSTFIELDS => $vars, // CURLOPT_USERAGENT => $_SERVER['HTTP_USER_AGENT'] // ); //get 方式 $opts = array( ); CURLOPT_TIMEOUT => 5, CURLOPT_HTTPAUTH=>CURLAUTH_BASIC, CURLOPT_USERPWD=>"$username:$password", CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $url, CURLOPT_HEADER =>0, CURLOPT_USERAGENT => $_SERVER['HTTP_USER_AGENT'] /* 初始化并执行 curl 请求 */ $ch = curl_init(); curl_setopt_array($ch, $opts); $status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); status code //get 56

57 $data = curl_exec($ch); $error = curl_error($ch); curl_close($ch); 9.5 Ruby On Rails 示例代码 : import mx.rpc.events.faultevent; import mx.rpc.events.resultevent; import mx.utils.base64encoder; import mx.rpc.http.httpservice; URLRequestDefaults.authenticate = false;// 设默认为 false, 否则用户较验错误时会弹出验证框 private var result:xml; private function initapp():void { var base64enc:base64encoder = new Base64Encoder; base64enc.encode("user:password"); // 用户名和密码需要 Base64 编码 var user:string = base64enc.tostring(); var = new HTTPService; http.addeventlistener(resultevent.result,resulthandler);// 监听返回事件 http.addeventlistener(faultevent.fault,faulthandler); // 监听失败事件 http.resultformat = "e4x";// 返回格式 http.url = "api 地址 "; http.headers = {"Authorization":"Basic " + user; http.send(); private function resulthandler(e:resultevent):void { result = XML(e.result); test.dataprovider = result.status;// 绑定数据 private function faulthandler(e:resultevent):void { // 处理失败 57

58 9.6 JS 用户认证示例代码 : <script type="text/javascript"> // 需要 Base64 见 : function make_base_auth(user, password) { var tok = user + ':' + pass; var hash = Base64.encode(tok); return "Basic " + hash; var auth = make_basic_auth('qleelulu','mypassword'); var url = 'api url address'; // 原始 JavaScript xml = new XMLHttpRequest(); xml.setrequestheader('authorization', auth); xml.open('get',url); // ExtJS Ext.Ajax.request({ url : url, method : 'GET', headers : { Authorization : auth ); // jquery $.ajax({ url : url, method : 'GET', beforesend : function(req) { req.setrequestheader('authorization', auth); ); </script> 9.7 php 验证用户名密码并调用接口的示例代码 //--- 使用 CURL 扩展的方式验证用户名密码并调用接口 if(extension_loaded('curl')){ 58

59 $username ="lixxx"; $password ="xxxxx"; $url = ' 3269&send_domain=all&send_account=all&send_fullname=negoo&status= 2&track_status=1&track_domain=follow .51negoo.com&maillist_id =241293&time= %3A38%3A40'; $params =array(); $params['name']=' 季度经济数据时代 '; // $params['name'] =iconv('gbk','utf-8',$params['name']); $params['subject']=' 季度经济数据时代 '; $params['content']=' 基金基, 金基金 '; $params['text_content']=' 基金基金基金, 舅舅家 '; $vars = http_build_query($params); //psot 方式 // $opts = array( // CURLOPT_TIMEOUT => 5, // CURLOPT_HTTPAUTH=>CURLAUTH_BASIC, // CURLOPT_USERPWD=>"$username:$password", // CURLOPT_RETURNTRANSFER => 1, // CURLOPT_URL => $url, // CURLOPT_POST => 1, // CURLOPT_POSTFIELDS => $vars, // CURLOPT_USERAGENT => $_SERVER['HTTP_USER_AGENT'] // ); //get 方式 $opts = array( ); CURLOPT_TIMEOUT => 5, CURLOPT_HTTPAUTH=>CURLAUTH_BASIC, CURLOPT_USERPWD=>"$username:$password", CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $url, CURLOPT_HEADER =>0, CURLOPT_USERAGENT /* 初始化并执行 curl 请求 */ $ch = curl_init(); curl_setopt_array($ch, $opts); => $_SERVER['HTTP_USER_AGENT'] $status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); status code $data = curl_exec($ch); $error = curl_error($ch); //get 59

60 curl_close($ch); 9.8 java 验证用户密码并调用上传附件接口示例代码 public static void main(string[] args) throws Exception { String urlstr = " // 参数 Map < String, String > params = new HashMap <> (); params. put("list_id", "418315"); // 文件 Map < String, Map < String, byte[] >> filemap = new HashMap <> (); filemap. put("file", new HashMap < String, byte[] > ()); FileInputStream fis = new FileInputStream("address.txt"); byte[] buf = new byte[fis. available()]; fis. read(buf); filemap. get("file"). put("test.txt", buf); fis.close(); String authstr = " 用户名 "+":"+" 密码 "; byte[] autnencbyte = Base64.encodeBase64(authStr.getBytes()); String authbase64 = New String(autnEncByte); // 请求验证用户账号密码 Map < String, String >requestproperties = new HashMap<>(); requestproperties.put("authorization", "Basic "+authbase64);// 你的用户名密码编码 String contenttype = "multipart/form-data"; String s = fileupload(urlstr, params, filemap, requestproperties, contenttype); 60

61 /** * 上传文件流 * url params filemap:name:{filename:byte[] requestproperties */ public static String fileupload(string urlstr, Map<String, String> params, Map<String, Map<String, byte[]>> filemap, Map<String, String> requestproperties, String contenttype) { String res = "";// 响应 String boundary = " " + new Date().getTime(); // boundary 就是 request 头和上传文件内容的分隔符 HttpURLConnection conn = null; try { if (StringUtils.isBlank(contentType)) { contenttype = "text/plain"; contenttype = "multipart/form-data";// TODO URL url = new URL(urlStr); conn = (HttpURLConnection) url.openconnection(); conn.setconnecttimeout(con_timeout); conn.setreadtimeout(read_timeout); conn.setdooutput(true); conn.setdoinput(true); conn.setusecaches(false); conn.setrequestmethod("post"); conn.setrequestproperty("connection", "Keep-Alive"); conn.setrequestproperty("user-agent", "Mozilla/5.0 (Windows; U; Windows NT 6.1; zh-cn; rv: )"); conn.setrequestproperty("content-type", "multipart/form-data; boundary=" + boundary); if(requestproperties!= null && requestproperties.size() > 0){ for (String key : requestproperties.keyset()) { conn.setrequestproperty(key, requestproperties.get(key)); OutputStream out = new 61