HTTP API插件

提示

菜单路径：【文件】 - 【插件管理】 - 【HTTP API 插件】

插件功能： 第三方程序通过HTTP API接口获取本程序中的邮箱和邮件

插件简介：
第三方软件开发者通过如手机APP等其它程序通过HTTP API请求到您电脑中的心蓝邮箱助手，实现添加邮箱，查收邮件，截取返回邮件内容中的关键字等便捷功能。
HTTP API接口使用HTTPS访问，采用UTF-8编码，只统计checkMail的调用次数。

准备工作

心蓝邮箱助手客户端：打开登录后，点击左上角【文件】-【插件管理】-【HTTP API插件】菜单中勾选 【启用HTTP API接口】。请勿关闭软件，否则无法收到请求。

HTTP API请求地址：
内地：https://bsh.bhdata.com:30015/bhmailer
香港：https://authhk.bhdata.com:30015/bhmailer
注：请根据邮件助手登录的授权服务器选择相应的地址

HTTP API请求方式：GET

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

HTTP API测试页面：https://www.bhdata.com/app/bhmailer.aspx
（建议点击左上角【文件】-【插件管理】-【HTTP API插件】-【API测试页】面进入该网址。）

返回code值参照下表说明：

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

调用方式

心蓝邮件助手远程HTTP API接口具有如下两种调用方式：

A、简易直链调用方式

该调用方式简单易用，无需了解接口的参数含义，不用写代码就可以实现需求的功能。具体操作如下：

【邮件规则】中添加规则，添加条件用来定义目标唯一邮件，如邮件主题，发件人，邮件发送时间(默认10分钟内)等；
规则的动作选择HTTP API；
截取字段即自定义导出字段，参照 导出提取关键字 ,可支持多个字段；
选择对应的邮箱，右键-【导出HTTP API链接】-选择上一步中建立的规则名称；
导出的结果即为每个对应邮箱的专属HTTP API链接，访问后可得到符合该规则最新目标邮件关键字；

专属HTTP API链接格式：
xxxxxxx@mailxw.com----https://bsh.bhdata.com:30015/?mail=VyJlGQcmEY7kXurEfqvbDAOkobSmxFBZUpAnpoIMTjihfx4y

B、高级自定义调用方式

该调用方式需具备一定的网络编程基础，了解接口各个参数的含义后，用自己的编程语言实现需求的高级功能。每个接口请求必须包含以下参数：

参数	值	说明
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	在文件-插件管理-HTTP API插件中查看

上述act命令可使用以下6个命令值：

1、获取API基本信息

命令：getApiInfo
功能： 返回Api的到期时间，每日最大请求次数和当前已用请求次数。
额外参数表：
<无>

请求示例：
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
功能： 从已登录的心蓝邮件助手中按顺序获取一个邮箱地址，同时返回邮箱账号总数和当前序号
额外参数表：

参数名	值	可选	说明
email	指定要获取的邮箱账号	是
pass	是否返回邮箱密码，默认0不返回，为1返回。如果账号有clientid和refreshtoken，在返回密码的同时也一同返回。	是

请求示例：
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是必选参数，其它为可选)

参数名	值	说明
email	邮箱账号，即邮箱地址	请求检查新邮件的邮箱账号
pass	邮箱账号的密码	如果指定了密码，在助手中邮箱账号不存在时自动添加
clientid	OAuth登录的ClientId	OAuth中用于获取access_token的clientid
refreshtoken	OAuth登录的refresh_token	如果指定了clientid和refreshtoken，则使用OAuth登录邮箱账号
proofemail	辅助邮箱	当需要自动OAuth登录且需辅助邮箱时
proofemailpwd	辅助邮箱密码	当需要自动OAuth登录且需辅助邮箱时
rule	邮件客户端定义的邮件规则名称	根据该规则的定义查找符合条件的邮件
title	邮件主题查找关键字	标题中包含指定关键字即为满足条件多个关键字用\|分隔，每个关键字为或者关系。
from	发件人查找关键字
to	收件人查找关键字	收件人中包含指定关键字即为满足条件多个关键字用\|分隔，每个关键字为或者关系。
cc	抄送人查找关键字	抄送人中包含指定关键字即为满足条件多个关键字用\|分隔，每个关键字为或者关系。
sent	邮件发送时间，可用3种赋值方式： 1.使用时间戳表示，即从1970年1月1日（UTC/GMT的午夜）开始所经过的毫秒数。 2.使用负整数，即表示当前时间减去相应的秒数。如sent=-180，表示三分钟内的邮件。 3.使用格式化的时间值，如2024-06-20 10:20:35（仅支持v182及以后版本）。注：推荐使用该参数，以便小于该参数时间的邮件将不接收，加快API返回速度。	邮件发送时间大于或等于此时间时为满足条件。如果指定了此参数，则如果在新邮件中没有找到匹配的邮件时则搜索已下载的邮件。注：rule,title,from,sent必须指定一个，推荐使用title+from+sent。当指定了rule时，title,from,sent三个参数无效，使用rule中的定义。
tempkeys	临时关键字	临时关键字，多个用换行符号(\n)分隔。用于替换导出字段中的$TEMPKEY#$。
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表示超时，可以后续使用getResult尝试获取结果。

特别提醒

此命令仅搜索请求API后软件收到的新邮件，如果请求之前软件中已存在目标邮件，则请加上sent参数。
或在目标邮件上右键-从本地删除，再该邮箱上右键-【清空本地的删除标志】后再次请求，以便请求可以获取该目标邮件为新邮件。

4、获取执行结果

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

参数名	值	说明
id	请求ID，即上一步`checkMail`请求检查新邮件时返回的邮件id	建议`checkMail`时加上sent参数，避免收取大量邮件导致超时返回`"code":5,"`,以省去本地请求。

请求示例：
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，即上一步`checkMail`请求检查新邮件时返回的邮件id	否
mode	删除方式:（默认为0） 0为本地删除，1为本地和服务器删除，2为仅服务器删除。	是

请求示例：
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"}

代码示例

C# Demo代码示例

Demo程序实现了每个接口的调用，可在自己的工程中直接使用。下载C# Demo程序

触动代码示例

Lua

tim = ts.ms() 
str = tim  ---获取时间戳 触动
str = tostring(str)
new = str:split(".")
tim=new[1]---精确分割
local url = "https://bsh.bhdata.com:30015/bhmailer"

status,header,content = http.get(url,{headers={},params={uid=用户ID,sign=apikey,act='checkMail',email=收件邮箱,title=邮件标题,from=发件邮箱,sent=-999999,fields='$BODYTEXT-R|[0-9]{6}$',t=tim}
  }
)

按键代码示例

JavaScript

Dim 邮箱名称 = "xxxxxx@yahoo.com"
Dim 邮箱密码="xxxxxxxx"

邮箱_取指定邮箱最新验证码(授权ID,key,邮箱名称,邮箱密码)
Function 邮箱_取指定邮箱最新验证码(授权ID,key,邮箱名称,邮箱密码)
    Dim 时间戳=time()*1000
    Dim  请求网址="https://bsh.bhdata.com:30015/bhmailer?uid="&授权ID&"&sign="&key&"&act=checkMail&sent=-999999&exmode=1&email="&邮箱名称&"&pass="&邮箱密码&"&title=xxxxxxx&fields=$BODYCLEAR|验证码是：|($&t="&时间戳
    Dim 发送请求 = URL.Get(请求网址, 60)
    TracePrint  发送请求
    Dim 返回结果 = Encode.JsonToTable(发送请求)
    Dim code = 返回结果["code"]
    Dim msg= 返回结果["msg"]
    TracePrint code
    TracePrint msg
    If CInt(code) = 5 Then 
        请求网址= "https://bsh.bhdata.com:30015/bhmailer?uid="&授权ID&"&sign="&key&"&act=getResult&id="&msg&"&t="&时间
        Dim 再次发送请求 = URL.Get(请求网址, 60)
        TracePrint  再次发送请求
    End If
End Function

易语言代码示例（需引用精易模块）：

JavaScript

.版本 2
.支持库 spec

.程序集 程序集1

.子程序 _启动子程序, 整数型, , 本子程序在程序启动后最先执行
.局部变量 请求网址, 文本型
.局部变量 授权ID, 文本型
.局部变量 APIKey, 文本型
.局部变量 API地址, 文本型
.局部变量 email, 文本型
.局部变量 局_返回, 文本型
.局部变量 json, 类_json
.局部变量 code, 文本型
.局部变量 msg, 文本型
.局部变量 bool, 逻辑型
.局部变量 title, 文本型
.局部变量 from, 文本型
.局部变量 fields, 文本型
.局部变量 sent, 文本型


' 1、基本信息
email ＝ “xxxxxx@outlook.com”  ' 要接收邮件的邮箱地址
授权ID ＝ “123456789”  ' 左上角文件-插件管理 HTTP API插件中查看
APIKey ＝ “xxxxxxxxxxxxxxxxxx”  ' 同上
API地址 ＝ “https://bsh.bhdata.com:30015/bhmailer”
' 2、确定目标邮件
title ＝ “xxxx xxx”  ' 目标邮件的标题
from ＝ “xxxxxxx@xxxx.com”  ' 目标邮件的发件人
sent ＝ “-180”  ' 距离当前请求时间3分钟内发送的邮件
' 3、定义需截取的返回字段
fields ＝ “$TITLE-R|[0-9]{5,}$”  ' 从邮件标题中截取返回连续5个以上数字 详见官网接口说明自定义邮件导出规则部分
请求网址 ＝ API地址 ＋ “?uid=” ＋ 授权ID ＋ “&sign=” ＋ APIKey ＋ “&act=checkMail&title=” ＋ title ＋ “&from=” ＋ from ＋ “&email=” ＋ email ＋ “&fields=” ＋ fields ＋ “&sent=” ＋ sent ＋ “&t=” ＋ 时间_取现行时间戳 ()
' 调试输出 (请求网址)
局_返回 ＝ 到文本 (网页_访问_对象 (请求网址, 0, , , , , , , , , , 30))
局_返回 ＝ 编码_utf8到gb2312 (局_返回)  ' 转码，不然乱码显示
bool ＝ json.解析 (局_返回)
.如果真 (bool)
    调试输出 (局_返回)
    code ＝ json.取通用属性 (“code”)
    msg ＝ json.取通用属性 (“msg”)
    ' 调试输出 (code)
    ' 调试输出 (msg)
.如果真结束

.判断循环首 (code ＝ “5”)  ' 当返回code 5时说明邮件还没接收完成，延时10秒后再次获取结果
    延时 (10000)
    请求网址 ＝ API地址 ＋ “?uid=” ＋ 授权ID ＋ “&sign=” ＋ APIKey ＋ “&act=getResult&id=” ＋ msg ＋ “&t=” ＋ 时间_取现行时间戳 ()
    调试输出 (请求网址)
    局_返回 ＝ 到文本 (网页_访问_对象 (请求网址, 0, , , , , , , , , , 30))
    局_返回 ＝ 编码_utf8到gb2312 (局_返回)  ' 转码，不然乱码显示
    bool ＝ json.解析 (局_返回)
    .如果真 (bool)
        code ＝ json.取通用属性 (“code”)
        msg ＝ json.取通用属性 (“msg”)
    .如果真结束

.判断循环尾 ()
调试输出 (code)
调试输出 (msg)
返回 (0)  ' 可以根据您的需要返回任意数值

python代码示例

Python

import requests
import time

# 修改为自己的基本信息
uid='xxxxxxxxx' #左上角文件-插件管理 HTTP API插件中查看
sign='xxxxxxxxxxxxxxxxxx' #同上
APIurl = 'https://bsh.bhdata.com:30015/bhmailer'

# 修改为自己需求的目标邮件
title = 'security code' #目标邮件的标题
from1 = 'microsoft.com' #目标邮件的发件人 from不能用作python变量，所以用了任意如from1
fields = '$BODY|href="|"$' #从邮件HTML源代码中截取第一个链接 详见官网接口说明自定义邮件导出规则部分

# 定义函数无需修改       
def checkMail(email,password):
    timestamp = round(time.time()*1000) # 13位时间戳
    sent = timestamp - 60000 #指定邮件发送时间为当前请求时间减去60秒防止时差
    # 发送GET请求
    response = requests.get(APIurl+'?uid='+uid+'&sign='+sign+'&act=checkMail&email='+email+'&pass='+password+'&title='+title+'&from='+from1+'&sent='+str(sent)+'&fields='+fields+'&t='+str(timestamp))
    # 获取接口返回的JSON数据
    jsonlist = response.json()
    # 解析返回值
    code = jsonlist["code"]
    msg = jsonlist["msg"]

    while code == 5:
        # print(jsonlist)
        time.sleep(15)
        response = requests.get(APIurl+'?uid='+uid+'&sign='+sign+'&act=getResult&id=' +msg+'&t='+str(timestamp))
        # 获取接口返回的JSON数据
        jsonlist = response.json()
        # 解析返回值
        code=jsonlist["code"]
        msg=jsonlist["msg"]         
    else:
        print(msg)


# 调用函数 密码为空时则邮箱必须提前导入到心蓝助手里，带上密码则自动添加邮箱到心蓝里收信
checkMail('xxxxx@hotmail.com','')

HTTP API插件 ​

准备工作 ​

调用方式 ​

A、简易直链调用方式 ​

B、高级自定义调用方式 ​

1、获取API基本信息 ​

2、获取一个邮箱账号 ​

3、请求检查新邮件 ​

4、获取执行结果 ​

5、删除邮件 ​

6、删除邮箱账号 ​

代码示例 ​

C# Demo代码示例 ​

触动代码示例 ​

按键代码示例 ​

易语言代码示例（需引用精易模块）： ​

python代码示例 ​