# 获取邮件会话邮件列表
获取指定邮件会话下的邮件列表，包含邮件元数据及主题、正文等内容。支持获取会话中位于垃圾邮件文件夹和已删除文件夹的邮件。
## 请求
基本 |
---|---
HTTP URL | https://open.feishu.cn/open-apis/mail/v1/user_mailboxes/:user_mailbox_id/threads/:thread_id
HTTP Method | GET
接口频率限制 | [10 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App
权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用** | 查询用户邮件(mail:user_mailbox.message:readonly)
字段权限要求 | **注意事项**：该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请
获取邮件内容中地址相关字段(mail:user_mailbox.message.address:read)
获取邮件正文(mail:user_mailbox.message.body:read)
获取邮件主题(mail:user_mailbox.message.subject:read)
### 请求头
名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`
或
`user_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer u-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
### 路径参数
名称 | 类型 | 描述
---|---|---
user_mailbox_id | string | 用户邮箱地址。当使用用户身份访问时，可以输入"me"代表当前调用接口用户
**示例值**："user@xxx.xx 或 me"
thread_id | string | 邮件会话ID。可通过发送邮件、回复邮件的接口返回值或获取邮件详情接口查询获得。
**示例值**："th_xxxxxxxxxxxx"
### 查询参数
名称 | 类型 | 必填 | 描述
---|---|---|---
format | string | 否 | 指定返回的邮件内容格式。支持 full、plain_text_full、metadata。默认值为 full，即返回标签、文件夹、主题、发件人、HTML 正文、纯文本正文等完整内容。
**示例值**：full
**可选值有**：
- full：全文，包括标签、文件夹、主题、收发件人、纯文本、HTML等信息
- plain_text_full：全文，只返回纯文本正文内容，不返回HTML。返回内容包括标签、文件夹、主题、收发件人、纯文本等信息
- metadata：邮件元数据信息，包括标签、文件夹、主题、收发件人、摘要等信息，不返回正文内容
include_spam_trash | boolean | 否 | 是否包含垃圾邮件文件夹（SPAM）和已删除文件夹（TRASH）中的邮件。true 表示包含，false 表示不包含。默认 false。
**示例值**：false
## 响应
### 响应体
名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
thread | thread | 邮件会话
id | string | 会话ID
body_preview | string | 会话内的最新的一封邮件摘要，用于快速预览邮件核心内容
messages | message\[\] | 会话中的邮件列表
subject | string | 主题
**字段权限要求**：
获取邮件主题(mail:user_mailbox.message.subject:read)
to | mail_address\[\] | 收件人
**字段权限要求**：
获取邮件内容中地址相关字段(mail:user_mailbox.message.address:read)
mail_address | string | 邮件地址
name | string | 名称
cc | mail_address\[\] | 抄送
**字段权限要求**：
获取邮件内容中地址相关字段(mail:user_mailbox.message.address:read)
mail_address | string | 邮件地址
name | string | 名称
bcc | mail_address\[\] | 密送
**字段权限要求**：
获取邮件内容中地址相关字段(mail:user_mailbox.message.address:read)
mail_address | string | 邮件地址
name | string | 名称
head_from | mail_address | 发件人
**字段权限要求**：
获取邮件内容中地址相关字段(mail:user_mailbox.message.address:read)
mail_address | string | 邮件地址
name | string | 名称
body_html | string | 正文(base64url)
**字段权限要求**：
获取邮件正文(mail:user_mailbox.message.body:read)
internal_date | string | 创建/收/发信时间（毫秒）
message_state | int | 邮件状态，1（收信）2（发信）3（草稿）
smtp_message_id | string | RFC协议id
message_id | string | 邮件id
attachments | attachment\[\] | 邮件附件列表
**字段权限要求**：
获取邮件正文(mail:user_mailbox.message.body:read)
filename | string | 附件文件名
id | string | 附件 id
attachment_type | int | 附件类型
**可选值有**：
- 1：普通附件
- 2：超大附件
is_inline | boolean | 是否为内联图片，true 表示是内联图片
cid | string | 内容 ID，HTML 中通过 cid: 协议引用该图片
body_plain_text | string | 正文纯文本(base64url)
**字段权限要求**：
获取邮件正文(mail:user_mailbox.message.body:read)
thread_id | string | 会话id
body_preview | string | 邮件正文纯文本内容的前100个字符，基于base64url编码，用于快速预览邮件核心内容，无需解码完整正文
label_ids | string\[\] | 标签ID
folder_id | string | 文件夹ID
in_reply_to | string | In-Reply-To邮件头
reply_to | string | Reply-To邮件头
priority_type | string | 邮件优先级
**可选值有**：
- 0：无优先级
- 1：高优先级
- 3：正常优先级
- 5：低优先级
security_level | security_level | 安全信息
is_risk | boolean | 是否风险邮件
risk_banner_level | string | 风险邮件等级
**可选值有**：
- WARNING：警告
- DANGER：危险
- INFO：提示
risk_banner_reason | string | 风险邮件原因
**可选值有**：
- NO_REASON：未知
- IMPERSONATE_DOMAIN：相似域名仿冒
- IMPERSONATE_KP_NAME：KP姓名仿冒
- UNAUTH_EXTERNAL：未认证外部域名
- MALICIOUS_URL：恶意链接
- MALICIOUS_ATTACHMENT：高危附件
- PHISHING：钓鱼邮件
- IMPERSONATE_PARTNER：仿冒合作伙伴
- EXTERNAL_ENCRYPTION_ATTACHMENT：外部邮件携带加密附件
is_header_from_external | boolean | 发件人是否外部邮件
via_domain | string | 代发或伪造邮件展示SPF或DKIM域名
spam_banner_type | string | 垃圾邮件原因
**可选值有**：
- USER_REPORT：用户曾标记邮件是垃圾邮件
- USER_BLOCK：用户曾将发件人的邮件标记为垃圾邮件
- ANTI_SPAM：系统判为垃圾邮件
- USER_RULE：命中收信规则进入垃圾邮件
- BLOCK_DOMIN：用户已拦截来自该域名的邮件
- BLOCK_ADDRESS：用户已拦截来自该邮件地址的邮件
spam_user_rule_id | string | 命中的收信规则ID
spam_banner_info | string | 命中用户黑名单的地址或域名信息
references | string | References邮件头
### 响应体示例
```json
{
"code": 0,
"msg": "success",
"data": {
"thread": {
"id": "197c5d72e22e1d78",
"body_preview": "hello world",
"messages": [
{
"subject": "邮件标题",
"to": [
{
"mail_address": "mike@outlook.com",
"name": "Mike"
}
],
"cc": [
{
"mail_address": "mike@outlook.com",
"name": "Mike"
}
],
"bcc": [
{
"mail_address": "mike@outlook.com",
"name": "Mike"
}
],
"head_from": {
"mail_address": "mike@outlook.com",
"name": "Mike"
},
"body_html": "PHA-SGVsbG8sIHRoaXMgaXMgYSBkcmFmdCBlbWFpbC48L3A-",
"internal_date": "1682377086000",
"message_state": 1,
"smtp_message_id": "ay0azrJDvbs3FJAg@outlook.com",
"message_id": "tfuh9N4WnzU6jdDw=",
"attachments": [
{
"filename": "helloworld.txt",
"id": "YQqYbQHoQoDqXjxWKhJbo8Gicjf",
"attachment_type": 1,
"is_inline": false,
"cid": "image1@example.com"
}
],
"body_plain_text": "SGVsbG8sIHRoaXMgaXMgYSBkcmFmdCBlbWFpbC4",
"thread_id": "tfuh9N4WnzU6jdDw=",
"body_preview": "Hello, this is a draft email.",
"label_ids": [
"FLAGGED"
],
"folder_id": "INBOX",
"in_reply_to": "06d20.dbf451a3.808a.475a.acc9.1363dfd20f36@larksuite.com",
"reply_to": "06d20.dbf451a3.808a.475a.acc9.1363dfd20f36@larksuite.com",
"priority_type": "0",
"security_level": {
"is_risk": false,
"risk_banner_level": "WARNING",
"risk_banner_reason": "IMPERSONATE_DOMAIN",
"is_header_from_external": false,
"via_domain": "larksuite.com",
"spam_banner_type": "USER_REPORT",
"spam_user_rule_id": "7618365627924925388",
"spam_banner_info": "larksuite.com"
},
"references": "<5678.abcd@test.com>\r\n\t<1234.abcd@message-id>"
}
]
}
}
}
```
### 错误码
HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
404 | 1234013 | user mailbox not found or user mailbox not active | 指定邮箱地址不存在或邮箱地址状态不正确，请检查输入的邮箱地址
403 | 1234017 | permission deny | 无权限访问，请检查权限申请状态
500 | 1234008 | internal server error | 服务器内部错误，请稍后重试
500 | 1236019 | internal server error | 服务器内部错误，请稍后重试
404 | 1236022 | mail thread not found | 指定邮件会话不存在，请检查输入的邮件会话参数