跳转至

五、用户邮件接口

接口访问 URL：http://mail.demo.com/openapi.php

5.1 用户登录

参数 参数名称 参数说明 必须 样例
method 方法名 login Y
user 用户名 登录用户名 Y test
pass 登录密码 登录密码 Y aYe_se683

登录成返回 sessid , 这是一个会话 token，以下所有操作接口都需要携带此 sessid 参数

登录成功返回值 

    { 
        "result": "ok", 
        "info": 
        {
            “sessid”: "1a2db1b0edda735295508723d8c6a962",
            “uid”: "test",
            “email”: " test@cnu.com ",
            “fullname”: "测试用户",
            “mobile”: "13900000000",
            “company”: "华兆科技",
            “department”: "系统研发部",
            “jobtitle”: "工程帅",
            “office”: "",
            “officephone”: "",
            “homeaddress”: "",
            “homephone”: ""
        } 
    }

登录成功后，开发者一直可以使用此 sessid 进行操作其他接口。会话是有有效期限的，长 时间不操作会过期，生存时间与 Webmail 的会话时间一致（默认是 30 分钟）。

开发者可以在有效期内定时更新 session 保持一直有效。

参数 参数名称 参数说明 必须 样例
method 方法名 updatesession Y
sessid 登录sesssion 登录成返回sessid Y 参考“5.1 用户登录”

成功返回值 

{ "result": "ok"}

※可以直接重定向到 http://mail.demo.com/main.php?act=login&sessid=xxxxxxxxx xxxxxxxx 是登录成返回 sessid ，实现单点登录功能。

5.2 邮件夹操作

5.2.1 列邮件夹

参数 参数名称 参数说明 必须 样例
method 方法名 folders Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录”

成功返回值

    { 
        "result": "ok", 
        "info": { 
            “private”: 个人邮件夹, 
            “public”: 公共邮件夹, 
            “archive”: 归档邮件夹, 
            “label”: 标签
        } 
    }

5.2.2 新建邮件夹

参数 参数名称 参数说明 必须 样例
method 方法名 folders.newfolder Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录”
newfolder 新邮件夹名 Y

成功返回值 

{ "result": "ok"}

5.2.3 重命名邮件夹

参数 参数名称 参数说明 必须 样例
method 方法名 folders.renamefolder Y
sessid 登录session 登录成返回sessid Y 参考“5.1 管理员登录”
folder 要操作的邮件夹名 Y
newfolder 新邮件夹名 Y

成功返回值 

{ "result": "ok"}

5.2.4 删除邮件夹

参数 参数名称 参数说明 必须 样例
method 方法名 folders.delfolder Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录”
folder 要操作的邮件夹名 Y

成功返回值

{ "result": "ok"}

5.2.5 清空邮件夹

参数 参数名称 参数说明 必须 样例
method 方法名 folders.emptyfolder Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录”
folder 要操作的邮件夹名 Y

成功返回值 

{ "result": "ok"}

5.3 邮件列表

5.3.1 邮件列表

参数 参数名称 参数说明 必须 样例
method 方法名 msglist Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录”
folder 文件夹 指定邮件夹
系统默认邮件夹
INBOX –收件箱
Sent –已发邮件
Draf –草稿箱
Trash –已删除
Spam –垃圾邮件夹		 Y
pag 页码 分页序号，以1开始 N

成功返回值 

    { 
        "result": "ok", 
        "info": 
        {
            “messagelist”: 邮件列表信息,
            “totalpage”: 总分页数
            “newmsg”: 新邮件数
            “msgtotal”: 邮件总数
        } 
    }

如果想显示某些特殊的读邮件列表

参数 参数名称 参数说明 必须 样例
method 方法名 msglist.search Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录”
folder 文件夹 Y
pag 页码 分页序号，以1开始 N
listype 查看方式 unread –未读邮件
read –已读邮件
answered –己回复邮件
forwarded –已转发邮件
fagged –星标邮件		 N

5.3.2 删除邮件

参数 参数名称 参数说明 必须 样例
method 方法名 msglist.delete Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录”
folder 文件夹 Y
msgid 邮件标识 Y

成功返回值

{ "result": "ok"}

5.3.3 移动邮件

参数 参数名称 参数说明 必须 样例
method 方法名 msglist. move Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录”
folder 文件夹 Y
msgid 邮件标识 Y
tofolder 目标邮件夹 Y

成功返回值 

{ "result": "ok"}

5.3.4 置顶邮件

参数 参数名称 参数说明 必须 样例
method 方法名 msglist.top Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录”
folder 文件夹 Y
msgid 邮件标识 Y

成功返回值 

{ "result": "ok"}

5.3.5 取消置顶邮件

参数 参数名称 参数说明 必须 样例
method 方法名 msglist.untop Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录”
folder 文件夹 Y
msgid 邮件标识 Y

成功返回值 

{ "result": "ok"}

5.3.6 设置已读标记

参数 参数名称 参数说明 必须 样例
method 方法名 msglist.read Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录”
folder 文件夹 Y
msgid 邮件标识 Y

成功返回值 

{ "result": "ok"}

5.3.7 设置未读标记

参数 参数名称 参数说明 必须 样例
method 方法名 msglist.unread Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录”
folder 文件夹 Y
msgid 邮件标识 Y

成功返回值 

{ "result": "ok"}

5.3.8 设置星标邮件

参数 参数名称 参数说明 必须 样例
method 方法名 msglist.fag Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录”
folder 文件夹 Y
msgid 邮件标识 Y

成功返回值 

{ "result": "ok"}

5.3.9 取消星标邮件

参数 参数名称 参数说明 必须 样例
method 方法名 msglist.unfag Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录”
folder 文件夹 Y
msgid 邮件标识 Y

成功返回值 

{ "result": "ok"}

5.4 文件夹未读邮件数

参数 参数名称 参数说明 必须 样例
method 方法名 msgnum Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录”

成功返回值 

    { 
        "result": "ok", 
        "info": 各文件夹的未读邮件数
    }

5.5 阅读邮件

参数 参数名称 参数说明 必须 样例
method 方法名 readmsg Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录”
folder 文件夹 Y
msgid 邮件标识 Y

成功返回值

{ 
    "result": "ok", 
    "info": 
    {
        “from”: 发件人信息,
        “reply-to”: 回复信息
        “to”: 收件人信息
        “cc”: 抄送信息
        “subject”: 主题
        “date”: 发件日期
        “body”: 信体内容
        “attachment”: 邮件附件
        “memo”: 邮件备注信息
    } 
}

5.6 发送邮件

参数 参数名称 参数说明 必须 样例
method 方法名 newmsg.send Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录”
to 收件人 多个地址用分号(;)分隔 Y
cc 抄送 多个地址用分号(;)分隔 N
subject 邮件主题 Y
msgbody 邮件信体 Y
ishtml Html邮件 0 -文本邮件；1 – HTML邮件 N
priority 优先级 0 -正常；1 -优先 N
requestnotfy 请求阅读回条 0 -不需要；1 -需要 N

成功返回值 

{ "result": "ok"}
如果要发送带附件的邮件，要先重置写邮件缓存，然后上传附件，最后再发送邮件。

重置写邮件缓存，如要发送含附件邮件建议先进行重置操作。

参数 参数名称 参数说明 必须 样例
method 方法名 newmsg.reset Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录”

成功返回值 

{ "result": "ok"}

上传附件，可以一次上传多个文件，也可以分多次上传

参数 参数名称 参数说明 必须 样例
method 方法名 upload.upload Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录”
atachfle 上传文件 构造 multpart/form-data 格式的内容提交
atachfle 值不需要作为 url 参数生成 sign		 Y

成功返回值 

{ 
    "result": "ok", 
    “list”:[
    { 
        "name":"readme.txt",
        "localname":"C:\Winmail\server\webmail\temp\_attachments\test_baa065a52e3859e4e1a0ee2ca9188713_3a077176425dd745941ee40cd3dc5914",
        "type":"text/plain",
        "size":156894
    },
    { 
        "name":" 20180705141449.jpg",
        "localname":"C:\Winmail\server\webmail\temp\_attachments\test_baa065a52e3859e4e1a0ee2ca9188713_052c4b360ca824741aaa873077e8570d",
        "type":"image/jpg",
        "size": 54954
    }
    ]
}

multipart/form-data介绍 https://www.ietf.org/rfc/rfc1867.txt
http 请求中的 multipart/form-data,它会将表单的数据处理为一条消息，以标签为单元，用分隔符分开。既可以上传键值对，也可以上传文件。当上传的字段是文件时，会有 Content-Type 来表名文件类型；content-disposition，用来说明字段的一些信息；用 boundary 分离。

删除某封附件

参数 参数名称 参数说明 必须 样例
method 方法名 upload.delete Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录”
attachid 附件ID 上传后返回的附件数组， 所删除附件在数组中序号，序号以 0 开始 Y

成功返回值 

{ "result": "ok"}

5.7 个人地址簿

5.7.1 列地址簿

参数 参数名称 参数说明 必须 样例
method 方法名 addressbook Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录”
pag 页码 分页序号，以0开始 N

成功返回值

{ 
    "result": "ok", 
    "info": 
    {
        “group”: 地址组列表,
        “address”: 联系人列表
        “totalpage”: 总页数
        “addresscount”: 邮件总数
    } 
}

5.7.2 增加联系人

参数 参数名称 参数说明 必须 样例
method 方法名 addressbook.addcontact Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录”
name 姓名 Y
email 邮件地址 Y
mobile 手机 N
phone 电话 N
fax 传真 N
address 联系地址 N
zipcode 区号 N
company 工作单位 N
depart 部门 N
jobttle 职位 N
homephone 家庭电话 N
homeaddress 家庭地址 N
homezipcode 家庭区号 N
im 即时通信 N
url 个人网址 N
email1 备份邮箱地址 N
birthday 生日 N
memo 备注 N

成功返回值 

{ "result": "ok"}

5.7.3 修改联系人

参数 参数名称 参数说明 必须 样例
method 方法名 addressbook.savecontact Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录
id 联系人标识 Y
name 姓名 Y
email 邮件地址 Y
mobile 手机 N
phone 电话 N
fax 传真 N
address 联系地址 N
zipcode 区号 N
company 工作单位 N
depart 部门 N
jobttle 职位 N
homephone 家庭电话 N
homeaddress 家庭地址 N
homezipcode 家庭区号 N
im 即时通信 N
url 个人网址 N
email1 备份邮箱地址 N
birthday 生日 N
memo 备注 N

成功返回值 

{ "result": "ok"}

5.7.4 删除联系人

参数 参数名称 参数说明 必须 样例
method 方法名 addressbook.delecontact Y
sessid 登录session 登录成返回 sessid Y 参考”5.1 用户登录”
id 联系人标识 Y

成功返回值 

{ "result": "ok"}

5.7.5 增加地址组

参数 参数名称 参数说明 必须 样例
method 方法名 addressbook.addgroup Y
sessid 登录session 登录成返回sessid Y 参考”5.1 用户登录”
name 分组名称 Y
member 组成员 多个联系人地址用分号(;)分隔 Y

成功返回值 

{ "result": "ok"}

5.7.6 修改地址组

参数 参数名称 参数说明 必须 样例
method 方法名 addressbook.savegroup Y
sessid 登录session 登录成返回sessid Y 参考“5.1 用户登录”
id 组标识 Y
name 分组名称 Y
member 组成员 多个联系人地址用分号(;)分隔 Y

成功返回值 

{ "result": "ok"}

5.7.7 删除地址组

参数 参数名称 参数说明 必须 样例
method 方法名 addressbook.delegroup Y
sessid 登录session 登录成返回sessid Y 参考”5.1 用户登录”
id 组标识 Y

成功返回值 

{ "result": "ok"}