跳转至

三、基本参数说明

3.1 请求URL

3.1.1 基本参数

参数 参数名称 参数说明 必须 样例
apikey ApiKey API 平台分配请求方的唯一编号 Y ec880a9d4b
sign 签名 请求方根据 http 请求的参数通过 md5 生成的签名，与提交的参数字符集编码一致 Y 5c5f3b87357750a3f6dd23e59d1089f1
timestamp 时间戳 客户端的当前UNIX时间戳 Y 当前时间:2026-01-20 12:05:00 timestamp 值 1768910700
应用参数 参考各个 接口参数的说明
method 方法名 需要请求的方法名 Y user.added
felds 请求参数 各方法的调用参数,参数是ut-8字符集编码

3.1.2 样例

http://mai.demo.com/admin/openapi.php?apikey=ec880a9d4b&domain=cnu.com&method=user.delete&name=abc&sessid=efd24f9f63d69d6f6f169b235822ca5875eb2bae&timestamp=1455759653&sign=0ce5b7cdeca218e2dd0ca0fe9e8c5665

其中 mail.demo.com 是访问 Webmail 的主机名，也可以改成 IP 地址

3.2 返回结果

3.2.1 含义

  Winmail OpenAPI 平台对请求方提供的请求数据进行验证处理后，返回给请求方处理结果，以便请求方根据这些数据进一步处理。响应返回处理成功或者失败信息，需要请求方对相关错误进行处理。

3.2.2 样例

请求成功返回数据如下 

{ 
    "result": "ok", 
    "info": 
    {
        “sessid”: "efd24f9f63d69d6f6f169b235822ca5875eb2bae",
        “user”: "admin"
    } 
}
请求错误返回数据如下 
{ 
    "result": "error", 
    "error": "url sign invalid" 
}

常见错误信息参考本文档末尾的 “六、常见错误”

3.3 签名机制

3.3.1 签名算法

  • 1）所有请求参数按参数名升序排序；

  • 2）按请求参数名及参数值相互连接组成一个字符串，各参数的字符集与提交时的参数字符集必须一致；

  • 3）将应用密钥分别添加到以上请求参数串的头部和尾部；

  • 4）对该字符串进行 MD5 运算，得到一个 32 位小写字串；

  • 5）该字符串即是本次请求参数对应的签名；

  • 6）该签名值使用 sign 系统级参数一起和其它请求参数一起发送给服务 API 平台。 

 sign md5(apisecret+k1+v1+k2+v2+...+kn+vn+apisecret)

3.3.2 调用示例

调用 API：login 
应用参数: user,pass 
ApiKey: ec880a9d4b 
ApiSecret: aff54e78f6871aea3714a3916eb35199b7affb19

因为各语言语法不一致，以下实例只体现逻辑。
输入参数为 

 method= login 
 apikey= ec880a9d4b 
 timestamp=1455764753 
 user=test 
 pass=123456

按照参数名称升序排列

 apikey= ec880a9d4b 
 method= login 
 pass=123456 
 timestamp=1455764753 
 user=test

连接字符串 连接参数名与参数值，并在首尾加上 secret，如下： 

 aff54e78f6871aea3714a3916eb35199b7affb19apikeyec880a9d4bmethodloginpass123456timestamp1455764753usertestaff54e78f6871aea3714a3916eb35199b7affb19

生成签名 32 位小写 MD5 值: 496c4156bc32ca11fe81899e1b6a242c

拼装 http 请求 将所有参数值，然后拼装，通过浏览器访问该地址，即成功调用一次 接口， 如下：

http://mail.demo.com/openapi.php?apikey=ec880a9d4b&method=login&pass=123456&tmestamp=1455764753&user=test&sign=496c4156bc32ca11fe81899e1b6a242c

这是用户端接口，管理端接口 URL 是 http://mail.demo.com/admin/openapi.php