心蓝邮箱助手BHMailer HTTP API接口说明

文档中心

技术文档 | 帮助文档 | 常用下载 | 新闻动态

分类目标

心蓝邮箱助手BHMailer HTTP API接口说明

加入时间: 2021/11/25 17:51:05

心蓝邮件助手远程HTTP API接口使用HTTP通讯，参数名称全部为小写。采用UTF-8编码，使用HTTPS访问。通过HTTP API请求可实现获取及添加邮箱，查收邮件，截取邮件内容中的关键字等便捷功能。

心蓝邮箱助手客户端：打开登录后，点击左上角文件-插件管理-HTTP API插件菜单中勾选启用HTTP API接口，请勿关闭软件。 (如未安装请先下载)

API请求地址（第三方软件开发者首选，请根据邮件助手登录的服务器位置选择相应的地址）：
内地：https://bsh.bhdata.com:30015/bhmailer
香港：https://authhk.bhdata.com:30015/bhmailer

请求方式：GET

API测试页面：https://www.bhdata.com/app/bhmailer.aspx（模拟点击及手机用户使用。建议点击软件击左上角文件-插件管理-HTTP API插件-API测试页面进入该网址。）

返回结果为JSON格式文本，其中code为0时表示执行成功，执行成功时msg或data标示执行结果。非0时表示失败，msg表示相应的错误描述。

返回code值参照下表说明：

Code	含意
0	执行成功
1	参数错误
2	时间戳错误，当前电脑时间与标准时间相差不能超过120秒
3	签名错误，检查MD5时字符串的拼接顺序和API KEY是否正确
4	邮件助手不在线，请先启用邮件助手
5	等待执行结果超时，在msg中返回请求的ID，后续可以通过getResult接口根据此ID获取执行结果。如：{"code":5,"msg":"123456"}
6	读取新邮件失败(如没有新邮件，网络连接失败，登录失败等)
7	没有发现匹配的邮件
8	没有发现指定的请求ID
9	超出请求次数限制
255	非法操作

每个接口请求必须包含以下参数：

参数名	值	可选	说明
act	命令	否	命令值，不同功能对应不同命令值，区分大小写
uid	授权ID	否	在邮件助手文件-插件管理-HTTP API插件中查看
t	时间戳，从1970年1月1日（UTC/GMT的午夜）开始所经过的毫秒数	否	JavaScript：parseInt(new Date().getTime()) C#: (DateTime.UtcNow.Ticks - 621355968000000000) / 10000
sign	将前面所有字段值+其它参数值+API Key按顺序拼接后MD5，使用UNICODE编码。也可以只将API Key直接MD5得到sign或者将API Key直接赋值给sign	否	API Key在邮件助手文件-插件管理-HTTP API插件中查看

1、获取API基本信息

命令：getApiInfo

功能：返回Api的到期时间，每日最大请求次数和当前已用请求次数。（目前接口调用次数初始每天10次，包月后每天10000次。）

额外参数表：

<无>

请求示例：https://bsh.bhdata.com:30015/bhmailer?uid=您的授权ID&sign=您的API Key&act=getApiInfo&t=1649780855934

正常返回结果：{"code":0,"data":{"uid":123456789,"endTime":"2022-11-23 23:48:36","maxTimes":10000,"times":3,"timesTime":"2021-11-26 00:38:07"}}

2、获取一个邮箱账号

命令：getAccount

功能：从已登录的心蓝邮件助手中按顺序获取一个邮箱地址，同时返回邮箱账号总数和当前序号

额外参数表：

参数名	值	可选	说明
pass	是否返回邮箱密码，默认0不返回，为1返回	是

请求示例：https://bsh.bhdata.com:30015/bhmailer?uid=您的授权ID&sign=您的API Key&act=getAccount&pass=0&t=1649778851581

正常返回结果：{"code":0,"data":{"email":"asdfasf@126.com","total":14,"no":2}}

3、请求检查新邮件

命令：checkMail

功能：指定从某个邮箱账号中获取满足指定条件的邮件，返回按截取规则截取到的邮件内容。

额外参数表：

参数名	值	可选	说明
email	邮箱账号，即邮箱地址	否	请求检查新邮件的邮箱账号
pass	邮箱账号的密码	是	如果指定了密码，在助手中邮箱账号不存在时自动添加
rule	邮件客户端定义的邮件规则名称	是	根据该规则的定义查找符合条件的邮件
title	邮件标题查找关键字	是	标题中包含指定关键字即为满足条件
from	发件人查找关键字	是	发件人中包含指定关键字即为满足条件
to	收件人查找关键字	是	收件人中包含指定关键字即为满足条件
cc	抄送人查找关键字	是	抄送人中包含指定关键字即为满足条件
sent	邮件发送时间，使用时间戳表示，同参数t。如果为负数，使用当前时间减去相应的秒数。如sent=-180，表示三分钟内的邮件。	是	邮件发送时间大于或等于此时间时为满足条件。如果指定了此参数，则如果在新邮件中没有找到匹配的邮件时则搜索已下载的邮件。注意:rule,title,from,sent必须指定一个，推荐使用title+from+sent，当指定了rule时，title,from,sent三个参数无效，使用rule中的定义。
fields	截取字段定义，定义规则参照邮件助手中的自定义导出规则说明，多个用\n分隔。如果不指定则默认为$BODYTEXT$	是	导出规则说明请查看附：自定义邮件导出规则
separator	有多个导出字段时，拼接的分隔符。如果不指定默认为逗号(,)	是
exmode	是否为扩展模式，1或0。默认为0。	是	当为1时，正常返回结果值在Json对象中的data属性中，返回结果包含邮件id，可用于delMail命令。

请求示例：https://bsh.bhdata.com:30015/bhmailer?uid=您的授权ID&sign=您的API Key&act=checkMail&email=asdfasf@126.com&from=xxx@xxx.com&fields=$BODYTEXT-R|[0-9]{6}$&t=1649780119125

正常返回结果：exmode为0时返回{"code":0,"msg":"截取到的连续的6个数字"}，exmode为1时返回{"code":0,"data":{"result":"截取到的连续的6个数字","id":"abcdefgxx"}}

异常返回结果：{"code":3,"msg":"sign error"}

如果code为5表示超时，可以后续尝试获取结果。

注：如果使用同一个邮箱测试，请求一次后务必在该邮箱上右键-删除所有邮件(仅本地)，再右键-清空本地的删除标志以便可以再次请求获取新邮件。

特别提醒：如果没有指定sent参数，此命令仅搜索命令请求后软件收到的邮件，即请确保软件中没有收到目标邮件之前去请求API，以便请求后软件开始收邮件，有目标邮件就返回。

4、获取执行结果

命令：getResult

功能：当执行结果code的值为5时，表示在等待的时间内，动作还没有执行完成，需要稍后主动发起获取结果请求。
比如检查新邮件，默认只有10秒时间，如果10秒收取到需要的邮件则立即返回截取结果。
如果因网络慢或邮件过多，需要时间超过10秒，则返回code为5，需要此接口主动发起请求获取执行结果。

额外参数表：

参数名	值	可选	说明
id	请求ID，即请求检查新邮件时返回的ID	否

请求示例：https://bsh.bhdata.com:30015/bhmailer?uid=您的授权ID&sign=您的API Key&act=getResult&id=xxxxx&t=1649780751911

正常返回结果：exmode为0时返回{"code":0,"msg":"这是结果"}，exmode为1时返回{"code":0,"data":{"result":"这是结果","id":"abcdefgxx"}}

5、删除邮件

命令：delMail

功能：删除checkMail返回的邮件。

额外参数表：

参数名	值	可选	说明
email	邮箱账号，即邮箱地址	否	请求删除的邮件所在的邮箱账号
id	邮件id，即请求检查新邮件时返回的邮件id	否
mode	删除方式: 0为本地删除，1为本地和服务器删除，2为仅服务器删除。默认为0	是

请求示例：https://bsh.bhdata.com:30015/bhmailer?uid=您的授权ID&sign=您的API Key&act=delMail&email=xxxxxx&id=xxxxx&mode=1&t=1649780751911

正常返回结果：{"code":0,"msg":"Done"}

6、删除邮箱账号

命令：delAccount

功能：删除指定的邮箱账号。已收取的邮件将被同时删除(仅本地)。

额外参数表：

参数名	值	可选	说明
email	邮箱账号，即邮箱地址	否	指定要删除的邮箱账号

请求示例：https://bsh.bhdata.com:30015/bhmailer?uid=您的授权ID&sign=您的API Key&act=delAccount&email=xxxxxx&t=1649780751911

正常返回结果：{"code":0,"msg":"Done"}

附：自定义邮件导出规则

说明：自定义导出的规则以$标识符作为开头和结尾，在程序的字段列表中每行一个字段定义规则，导出时程序将列表中的所有行字段用指定的"字段分隔符"相连成为一行。

支持的内置字段：

$EMAIL$：邮箱
$PASS$：密码
$COMMENTS$：备注
$TITLE$：邮件标题
$RECEIVED$：邮件接收时间
$FROMEMAIL$：发件人邮箱地址
$RECEIVER$：收件人
$CC$：抄送
$IP$: 发件人IP

$SOURCE$：包含邮件头的邮件原始内容

$HEADER$：邮件头源代码

$BODY$：不包含邮件头的邮件内容源代码

$BODYTEXT$：邮件文本内容，如果是HTML格式将被转换为文本格式

$BODYCLEAR$: 邮件文本内容且去掉所有空白换行符号，如果是HTML格式将被转换为文本格式

以上字段为常见的邮件的标准字段，直接调用即可导出。如需要提取特殊的关键字内容，请使用下面的几种方法。

1、从指定内容（参照上述内置字段）中按正则表达式提取符合的结果：

举例：
如从邮件显示所见的文本内容中提取6位连续的数字：$BODYTEXT-R|\d{6}$；获取连续10位数字或英文字符串：$BODYTEXT-R|[\da-zA-Z]{10}$。

2、从指定内容中按起始与结束关键字提取第一个符合的结果：

举例：
A、如从标题中提取: 如果邮件标题为"欢迎abc成为会员"，要截取出abc，则字段定义为: $TITLE|欢迎|成$

如邮件内容为："您的激活码为123456。"，要提取的内容是123456，则字段定义为：$BODYTEXT|激活码为|。$

B、如果邮件内容为HTML格式，需要提取HTML中的字符，如提取HTML代码中的某个链接，则定义为：$BODY| href="|"$

C、如果要提取邮件标头中的Message-ID，则可以从源代码中提取，定义为: $SOURCE|Message-ID:|\n$

3、从指定内容中按起始与结束关键字提取所有符合的结果：

举例：
如邮件内容中多次出现："您的可用KEY是：XXXXXX。"，要提取每个不同的XXXXXX，则字段定义为：$BODY-A|KEY是：|。$

其他说明：

1、推荐使用$BODYTEXT$，即HTML格式将被转换为文本格式再做提取。

2、<START>与<END>是一组起始和结尾关键字组合，可以有多个组合，即在第一组截取后再对第一组的截取结果进行第2组关键字截取，依次进行N次截取。

如：原始文本为"您的激活码为ABC-123456。"，如果要提取"123456"，则字段定义为"$BODY|您的激活码为|。|-|"

3、有三个常用的符号：\r表示回车，\n表示换行，\t表示制表符。实际应用中很多看到的换行是由回车+换行组成的，即使用\r\n来表示。

BHMailer HTTP POST说明

网站用户名密码忘记了怎么找回？