# 搜索邮件
搜索用户当前账户下的邮件
## 请求
基本 |
---|---
HTTP URL | https://open.feishu.cn/open-apis/mail/v1/user_mailboxes/:user_mailbox_id/search
HTTP Method | POST
接口频率限制 | [1000 次/分钟、50 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App
权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用** | 查询用户邮件(mail:user_mailbox.message:readonly)
### 请求头
名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `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)
Content-Type | string | 是 | **固定值**："application/json; charset=utf-8"
### 路径参数
名称 | 类型 | 描述
---|---|---
user_mailbox_id | string | 用户邮箱地址。当使用用户身份访问时，可以输入"me"代表当前调用接口用户
**示例值**："user@xxx.xx or me"
**数据校验规则**：
- 长度范围：`1` ～ `256` 字符
### 查询参数
名称 | 类型 | 必填 | 描述
---|---|---|---
page_size | int | 否 | 翻页参数：单页返回结果数量。
默认值：15。
范围：1～15。
**示例值**：10
page_token | string | 否 | 分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果
**示例值**：eVQrYzJBNDNONlk4VFZBZVlSdzlKdFJ4bVVHVExENDNKVHoxaVdiVnViQT0=
### 请求体
名称 | 类型 | 必填 | 描述
---|---|---|---
query | string | 否 | 搜索关键词。
**数据校验规则：**
- 长度范围：0 ～ 50 字符
**示例值**："合同审批通知"
filter | mail_search_filter | 否 | 用于对搜索结果进行精细化筛选，支持按发件人、收件人、文件夹、时间范围等多维度组合过滤，缩小查询范围，提升搜索精准度。
**示例值：** {"from":["user@example.com"],"is_unread":true}
from | string\[\] | 否 | 发件人姓名或邮箱地址筛选，仅返回来自该发件人的邮件
**示例值**：["zhangsan"]
**数据校验规则**：
- 长度范围：`0` ～ `100`
to | string\[\] | 否 | 收件人姓名或邮箱地址筛选，仅返回收件人列表包含该收件人的邮件。
**示例值**：["lisi"]
**数据校验规则**：
- 长度范围：`0` ～ `100`
cc | string\[\] | 否 | 抄送人姓名或邮箱地址筛选，仅返回抄送人列表包含该抄送人的邮件。
**示例值**：["wangwu"]
**数据校验规则**：
- 长度范围：`0` ～ `100`
bcc | string\[\] | 否 | 密送人姓名或邮箱地址筛选，仅返回秘送人列表包含该秘送人的邮件。
**示例值**：["yiming"]
**数据校验规则**：
- 长度范围：`0` ～ `100`
subject | string | 否 | 邮件主题搜索，仅返回主题中能搜到搜索词的结果。
**示例值**："合同签署"
folder | string\[\] | 否 | 文件夹名称筛选，仅返回在所选目录下的邮件。仅支持传入系统文件夹名称（固定值 inbox/sent/draft/trash/spam/archive/priority/flagged/other/scheduled，其中，priority指重要邮件）、自定义文件夹名称。子文件夹需使用 parent_name/child_name格式，可通过 folder list 接口查看文件夹名称。
**示例值**：["trash"]
**数据校验规则**：
- 长度范围：`0` ～ `100`
label | string\[\] | 否 | 自定义标签名称筛选，仅返回包含指定自定义标签的邮件。子标签需使用parent_name/child_name 格式，可通过 label list 接口查看标签名称。
**示例值**：["自定义标签"]
**数据校验规则**：
- 长度范围：`0` ～ `100`
has_attachment | boolean | 否 | 是否只筛选有附件的邮件，默认值：**否**
**示例值**：true
is_unread | boolean | 否 | 是否只筛选未读邮件，默认为**否**
**示例值**：true
create_time | time_range | 否 | 邮件接收时间范围筛选，只返回在所选时间范围内的邮件。
限制：一次搜索请求的时间范围不要超过1年。
start_time | string | 否 | 时间范围的开始时间。（iso8601）精确到秒
**示例值**："2026-03-10T00:00:00+08:00"
**数据校验规则**：
- 正则校验：`^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):([0-5]\d):([0-5]\d)(Z|([+-](?:[01]\d|2[0-3]):?[0-5]\d))$`
end_time | string | 否 | 时间范围的截止时间。（iso8601）精确到秒
**示例值**："2026-03-10T00:00:00+08:00"
**数据校验规则**：
- 正则校验：`^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):([0-5]\d):([0-5]\d)(Z|([+-](?:[01]\d|2[0-3]):?[0-5]\d))$`
### 请求体示例
```json
{
"query": "合同审批通知",
"filter": {
"from": [
"zhangsan"
],
"to": [
"lisi"
],
"cc": [
"wangwu"
],
"bcc": [
"yiming"
],
"subject": "合同签署",
"folder": [
"trash"
],
"label": [
"自定义标签"
],
"has_attachment": true,
"is_unread": true,
"create_time": {
"start_time": "2026-03-10T00:00:00+08:00",
"end_time": "2026-03-10T00:00:00+08:00"
}
}
}
```
## 响应
### 响应体
名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
items | mail_search_item\[\] | 搜索结果列表
id | string | 邮件唯一标识
display_info | string | 包含邮件基本信息的卡片，用户搜索关键词命中的文本片段，使用标签包裹标注
meta_data | mail_search_meta | 邮件元信息
title | string | 邮件主题
thread_id | string | 邮件线程 ID
create_time | string | 邮件接收时间
message_biz_id | string | 邮件唯一标识
from | mail_address | 邮件发件人
mail_address | string | 邮件地址
name | string | 名称
total | int | 搜索命中结果数
has_more | boolean | 是否还有更多项
page_token | string | 分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
notice | string | 搜索补充提示信息，返回本次搜索的额外说明，例如：query被截断；搜索结果不全 等
### 响应体示例
```json
{
"code": 0,
"msg": "success",
"data": {
"items": [
{
"id": "msg_XXX",
"display_info": "{}",
"meta_data": {
"title": "测试邮件",
"thread_id": "thread_id_XXX",
"create_time": "2026-03-15T14:30:00+08:00",
"message_biz_id": "msg_id_xxx",
"from": {
"mail_address": "mike@outlook.com",
"name": "Mike"
}
}
}
],
"total": 99,
"has_more": true,
"page_token": "eVQrYzJBNDNONlk4VFZBZVlSdzlKdFJ4bVVHVExENDNKVHoxaVdiVnViQT0=",
"notice": "The query is too long and has been truncated to the first 50 characters for search."
}
}
```
### 错误码
HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
400 | 1231020 | page_token is invalid or expired, please start a new search | page_token 已失效或不合法，请重新发起搜索获取新的分页 token。
400 | 1231021 | page size is over the limit | 调小 page_size，不要超过接口限制
400 | 1231022 | page_token is over the limit，please refine your query with more specific keywords or filters | 分页已超过限制，请收窄关键词或筛选条件后重新搜索。
500 | 1231030 | user identity not found, please check your access token | 检查 access token 是否有效、类型是否正确，以及是否能识别到用户身份。
500 | 1232501 | no permission to access mailbox | 检查当前 token / 应用是否有访问该邮箱的权限。
400 | 1231040 | search service error, see logs for details. | 搜索服务异常，请带 request_id/log_id 查看日志或找下游排查。