b450b512a2
- 添加 mipu-api 作为 git submodule (Claude Code Skill) - 迁移 API 文档源文件到 docs/ 目录统一维护 - 添加 Gitea Actions 工作流：tag推送自动打包docs并发布Release - Skill 运行时自动从 mipu-open Release 下载最新文档 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
401 lines
14 KiB
Markdown
401 lines
14 KiB
Markdown
<!-- mipuyun-api-doc: mailbox-mail-search -->
|
||
# mailbox/mail/search - 搜索邮件
|
||
|
||
## 概述
|
||
|
||
根据关键词、邮件类型等条件搜索邮件，返回分页结果。
|
||
|
||
### 使用场景
|
||
|
||
- 用户需要在邮箱中查找特定邮件
|
||
- 根据关键词、邮件类型等条件筛选邮件
|
||
- 分页浏览邮件列表
|
||
|
||
## 请求说明
|
||
|
||
| 项目 | 值 |
|
||
|------|-----|
|
||
| **请求地址** | `https://${endpoint}/mailbox/mail/search` |
|
||
| **请求方法** | POST |
|
||
|
||
### Header 参数
|
||
|
||
| 参数名称 | 类型 | 是否必选 | 示例值 | 说明 |
|
||
|----------|------|----------|--------|------|
|
||
| Content-Type | String | 是 | application/json | 固定值，指定请求体格式为 JSON |
|
||
| Accept-Encoding | String | 是 | gzip, deflate, br | 必须要填写，否则服务器会拒绝 |
|
||
| client-key | String | 是 | xxxxx | 联系我们获取生产环境 key |
|
||
| client-secret | String | 是 | xxxxx | 联系我们获取生产环境 secret |
|
||
|
||
### 请求体参数
|
||
|
||
| 参数名称 | 类型 | 是否必选 | 示例值 | 说明 |
|
||
|----------|------|----------|--------|------|
|
||
| keyword | String | 否 | 机票 | 搜索关键词，支持邮件主题、发件人等 |
|
||
| mailType | Integer | 否 | 1 | 邮件类型：1-收件，2-发件 |
|
||
| domainName | String | 否 | example.com | 域名过滤 |
|
||
| hasAttachment | Boolean | 否 | true | 是否有附件 |
|
||
| readStatus | Integer | 否 | 0 | 阅读状态：0-未读，1-已读 |
|
||
| startTime | String | 否 | 2025-01-01T00:00:00Z | 起始时间（ISO 8601格式，**必须使用UTC时区**，以`Z`结尾） |
|
||
| endTime | String | 否 | 2025-01-31T23:59:59Z | 结束时间（ISO 8601格式，**必须使用UTC时区**，以`Z`结尾） |
|
||
| airlineCode | String | 否 | CA | 航空代码（如：CA-国航、MU-东航、CZ-南航等） |
|
||
| pageIndex | Integer | 是 | 1 | 页码，从1开始 |
|
||
| pageSize | Integer | 是 | 20 | 每页数量，建议10-50，最大100 |
|
||
| orderBy | String | 否 | sendTime | 排序字段，支持：`sendTime`(发送时间)、`receiveTime`(接收时间)、`subject`(主题) |
|
||
| orderDirection | String | 否 | DESC | 排序方向：`ASC`=升序，`DESC`=降序 |
|
||
|
||
#### 请求体示例
|
||
|
||
```json
|
||
{
|
||
"keyword": "机票",
|
||
"mailType": 1,
|
||
"airlineCode": "CA",
|
||
"pageIndex": 1,
|
||
"pageSize": 20,
|
||
"orderBy": "sendTime",
|
||
"orderDirection": "DESC"
|
||
}
|
||
```
|
||
|
||
## 返回参数
|
||
|
||
返回分页结果 `PageResult<MailInfo>`：
|
||
|
||
| 参数名称 | 类型 | 示例值 | 说明 |
|
||
|----------|------|--------|------|
|
||
| pageIndex | Integer | 1 | 当前页码 |
|
||
| pageSize | Integer | 20 | 每页数量 |
|
||
| total | Long | 150 | 总记录数 |
|
||
| records | Array\<MailInfo\> | - | 邮件列表 |
|
||
|
||
> **注意**：
|
||
> - 请求和响应统一使用 `pageIndex`
|
||
> - 总页数 `totalPages` 字段已移除，前端需自行计算：`totalPages = Math.ceil(total / pageSize)`
|
||
|
||
### MailInfo 对象字段
|
||
|
||
| 参数名称 | 类型 | 示例值 | 说明 |
|
||
|----------|------|--------|------|
|
||
| mailId | String | MSG_001 | 邮件ID |
|
||
| subject | String | 机票预订确认 | 邮件主题 |
|
||
| fromAddress | String | airline@example.com | 发件人地址 |
|
||
| toAddresses | String\[\] | ["user@example.com"] | 收件人列表 |
|
||
| ccAddresses | String\[\] | ["cc@example.com"] | 抄送列表 |
|
||
| mailType | Integer | 1 | 邮件类型：1-收件，2-发件 |
|
||
| mailTypeText | String | 收件 | 类型文本 |
|
||
| hasAttachment | Boolean | true | 是否有附件 |
|
||
| attachmentCount | Integer | 2 | 附件数量 |
|
||
| mailSize | Long | 1024000 | 邮件大小（字节） |
|
||
| mailSizeText | String | 1.0 MB | 人性化大小 |
|
||
| readStatus | Integer | 0 | 阅读状态：0-未读，1-已读 |
|
||
| receiveTime | String | 2025-01-02T10:00:00Z | 接收时间 |
|
||
| sendTime | String | 2025-01-02T10:00:00Z | 发送时间 |
|
||
| emlDownloadUrl | String | https://... | 原始EML文件下载地址（临时链接，1小时有效期） |
|
||
|
||
## 返回示例
|
||
|
||
```json
|
||
{
|
||
"pageIndex": 1,
|
||
"pageSize": 20,
|
||
"total": 150,
|
||
"records": [
|
||
{
|
||
"mailId": "MSG_001",
|
||
"subject": "机票预订确认",
|
||
"fromAddress": "airline@example.com",
|
||
"toAddresses": ["user@example.com"],
|
||
"ccAddresses": ["cc@example.com"],
|
||
"mailType": 1,
|
||
"mailTypeText": "收件",
|
||
"hasAttachment": true,
|
||
"attachmentCount": 2,
|
||
"mailSize": 1024000,
|
||
"mailSizeText": "1.0 MB",
|
||
"readStatus": 0,
|
||
"receiveTime": "2025-01-02T10:00:00Z",
|
||
"sendTime": "2025-01-02T10:00:00Z",
|
||
"emlDownloadUrl": "https://cdn.example.com/download/eml/MSG_001?token=xxx"
|
||
},
|
||
{
|
||
"mailId": "MSG_002",
|
||
"subject": "航班变更通知",
|
||
"fromAddress": "airline@example.com",
|
||
"toAddresses": ["user@example.com"],
|
||
"ccAddresses": [],
|
||
"mailType": 1,
|
||
"mailTypeText": "收件",
|
||
"hasAttachment": false,
|
||
"attachmentCount": 0,
|
||
"mailSize": 51200,
|
||
"mailSizeText": "50.0 KB",
|
||
"readStatus": 1,
|
||
"receiveTime": "2025-01-02T09:00:00Z",
|
||
"sendTime": "2025-01-02T09:00:00Z",
|
||
"emlDownloadUrl": "https://cdn.example.com/download/eml/MSG_002?token=yyy"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 时区说明
|
||
|
||
### UTC 时区要求
|
||
|
||
本接口要求所有时间参数**必须使用 UTC 时区**（协调世界时）。
|
||
|
||
**什么是 UTC？**
|
||
- UTC（Coordinated Universal Time）是世界标准时间，不受夏令时影响
|
||
- UTC 是全球统一的时间基准，与地理位置无关
|
||
- 北京时间 = UTC + 8小时，纽约时间 = UTC - 5小时（东部标准时间）
|
||
|
||
**为什么使用 UTC？**
|
||
1. **避免时区混淆**：不同地区的服务器和客户端使用不同时区会导致时间解释错误
|
||
2. **跨时区一致**：确保全球用户查询结果一致
|
||
3. **简化逻辑**：无需处理复杂的时区转换和夏令时问题
|
||
|
||
**时间格式要求：**
|
||
```
|
||
ISO 8601 格式：2025-01-15T00:00:00Z
|
||
^^^^^^^^^^^ ^^^^^^^ ^ ^
|
||
日期 时间 时区标识（UTC）
|
||
```
|
||
|
||
### 时间转换示例
|
||
|
||
| 本地时间 | UTC 时间（需要发送） | 说明 |
|
||
|----------|---------------------|------|
|
||
| 2025-01-15 00:00:00 (北京) | 2025-01-14T16:00:00Z | 北京时间 UTC+8，减8小时 |
|
||
| 2025-01-15 00:00:00 (纽约) | 2025-01-15T05:00:00Z | 纽约时间 UTC-5，加5小时 |
|
||
| 2025-01-15 00:00:00 (伦敦) | 2025-01-15T00:00:00Z | 伦敦时间 UTC+0（冬季） |
|
||
| 2025-01-15 00:00:00 (东京) | 2025-01-14T15:00:00Z | 东京时间 UTC+9，减9小时 |
|
||
|
||
> **重要**：发送时间前，请务必将本地时间转换为 UTC 时间！
|
||
|
||
### 代码示例
|
||
|
||
#### Java 示例
|
||
|
||
```java
|
||
import java.time.*;
|
||
import java.time.format.DateTimeFormatter;
|
||
import okhttp3.*;
|
||
import com.google.gson.Gson;
|
||
|
||
public class MailSearchExample {
|
||
|
||
private static final String API_ENDPOINT = "https://api.example.com/mailbox/mail/search";
|
||
private static final String CLIENT_KEY = "your-client-key";
|
||
private static final String CLIENT_SECRET = "your-client-secret";
|
||
|
||
public static void main(String[] args) {
|
||
// 方式1: 使用当前时间（自动转换为UTC）
|
||
ZonedDateTime nowUtc = ZonedDateTime.now(ZoneOffset.UTC);
|
||
ZonedDateTime oneDayAgoUtc = nowUtc.minusDays(1);
|
||
|
||
// 方式2: 从本地时间转换到UTC
|
||
ZonedDateTime localTime = ZonedDateTime.now(ZoneId.of("Asia/Shanghai"));
|
||
ZonedDateTime utcTime = localTime.withZoneSameInstant(ZoneOffset.UTC);
|
||
|
||
// 方式3: 指定特定时间（例如：北京时间2025-01-15 00:00:00）
|
||
ZonedDateTime beijingTime = ZonedDateTime.of(
|
||
2025, 1, 15, 0, 0, 0, 0,
|
||
ZoneId.of("Asia/Shanghai")
|
||
);
|
||
ZonedDateTime startTimeUtc = beijingTime.withZoneSameInstant(ZoneOffset.UTC);
|
||
ZonedDateTime endTimeUtc = beijingTime.plusDays(1).minusSeconds(1)
|
||
.withZoneSameInstant(ZoneOffset.UTC);
|
||
|
||
// 格式化为ISO 8601格式（带Z后缀）
|
||
DateTimeFormatter formatter = DateTimeFormatter.ISO_INSTANT;
|
||
String startTime = startTimeUtc.format(formatter); // 2025-01-14T16:00:00Z
|
||
String endTime = endTimeUtc.format(formatter); // 2025-01-15T15:59:59Z
|
||
|
||
// 构建请求体
|
||
MailSearchRequest request = new MailSearchRequest();
|
||
request.setKeyword("机票");
|
||
request.setMailType(1);
|
||
request.setStartTime(startTime);
|
||
request.setEndTime(endTime);
|
||
request.setPageIndex(1);
|
||
request.setPageSize(20);
|
||
|
||
// 设置排序（按发送时间降序）
|
||
request.setOrderBy("sendTime");
|
||
request.setOrderDirection("DESC");
|
||
|
||
// 发送请求
|
||
sendRequest(request);
|
||
}
|
||
|
||
static class MailSearchRequest {
|
||
private String keyword;
|
||
private Integer mailType;
|
||
private String startTime;
|
||
private String endTime;
|
||
private Integer pageIndex;
|
||
private Integer pageSize;
|
||
private String orderBy;
|
||
private String orderDirection;
|
||
|
||
// getters and setters...
|
||
}
|
||
|
||
private static void sendRequest(MailSearchRequest request) throws Exception {
|
||
Gson gson = new Gson();
|
||
String json = gson.toJson(request);
|
||
|
||
OkHttpClient client = new OkHttpClient();
|
||
RequestBody body = RequestBody.create(
|
||
json,
|
||
MediaType.parse("application/json; charset=utf-8")
|
||
);
|
||
|
||
Request httpRequest = new Request.Builder()
|
||
.url(API_ENDPOINT)
|
||
.post(body)
|
||
.addHeader("Content-Type", "application/json")
|
||
.addHeader("Accept-Encoding", "gzip, deflate, br")
|
||
.addHeader("client-key", CLIENT_KEY)
|
||
.addHeader("client-secret", CLIENT_SECRET)
|
||
.build();
|
||
|
||
try (Response response = client.newCall(httpRequest).execute()) {
|
||
System.out.println(response.body().string());
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### Python 示例
|
||
|
||
```python
|
||
import requests
|
||
from datetime import datetime, timezone, timedelta
|
||
from zoneinfo import ZoneInfo # Python 3.9+
|
||
import json
|
||
|
||
API_ENDPOINT = "https://api.example.com/mailbox/mail/search"
|
||
CLIENT_KEY = "your-client-key"
|
||
CLIENT_SECRET = "your-client-secret"
|
||
|
||
def search_mails():
|
||
# 方式1: 使用当前UTC时间
|
||
now_utc = datetime.now(timezone.utc)
|
||
one_day_ago_utc = now_utc - timedelta(days=1)
|
||
|
||
# 方式2: 从本地时间转换到UTC（例如：北京时间）
|
||
beijing_tz = ZoneInfo("Asia/Shanghai")
|
||
local_time = datetime(2025, 1, 15, 0, 0, 0, tzinfo=beijing_tz)
|
||
start_time_utc = local_time.astimezone(timezone.utc)
|
||
end_time_utc = (local_time + timedelta(days=1) - timedelta(seconds=1)).astimezone(timezone.utc)
|
||
|
||
# 方式3: 直接创建UTC时间
|
||
start_time_utc = datetime(2025, 1, 14, 16, 0, 0, tzinfo=timezone.utc)
|
||
end_time_utc = datetime(2025, 1, 15, 15, 59, 59, tzinfo=timezone.utc)
|
||
|
||
# 格式化为ISO 8601格式（带Z后缀）
|
||
start_time = start_time_utc.isoformat()
|
||
end_time = end_time_utc.isoformat()
|
||
# 结果: "2025-01-14T16:00:00+00:00" 或 "2025-01-14T16:00:00Z"
|
||
|
||
# 确保以Z结尾（某些库可能使用+00:00）
|
||
if not start_time.endswith('Z'):
|
||
start_time = start_time.replace('+00:00', 'Z').replace('+00:00:00', 'Z')
|
||
if not end_time.endswith('Z'):
|
||
end_time = end_time.replace('+00:00', 'Z').replace('+00:00:00', 'Z')
|
||
|
||
# 构建请求体
|
||
payload = {
|
||
"keyword": "机票",
|
||
"mailType": 1,
|
||
"startTime": start_time, # "2025-01-14T16:00:00Z"
|
||
"endTime": end_time, # "2025-01-15T15:59:59Z"
|
||
"pageIndex": 1,
|
||
"pageSize": 20,
|
||
"orderBy": "sendTime",
|
||
"orderDirection": "DESC"
|
||
}
|
||
|
||
# 发送请求
|
||
headers = {
|
||
"Content-Type": "application/json",
|
||
"Accept-Encoding": "gzip, deflate, br",
|
||
"client-key": CLIENT_KEY,
|
||
"client-secret": CLIENT_SECRET
|
||
}
|
||
|
||
response = requests.post(
|
||
API_ENDPOINT,
|
||
data=json.dumps(payload),
|
||
headers=headers
|
||
)
|
||
|
||
print(f"Status Code: {response.status_code}")
|
||
print(f"Response: {response.json()}")
|
||
|
||
return response.json()
|
||
|
||
# 常用时区转换工具函数
|
||
def convert_to_utc(local_time_str, local_timezone="Asia/Shanghai"):
|
||
"""
|
||
将本地时间字符串转换为UTC时间字符串
|
||
|
||
Args:
|
||
local_time_str: 本地时间，如 "2025-01-15 00:00:00"
|
||
local_timezone: 本地时区，默认 "Asia/Shanghai"
|
||
|
||
Returns:
|
||
UTC时间字符串，如 "2025-01-14T16:00:00Z"
|
||
"""
|
||
local_tz = ZoneInfo(local_timezone)
|
||
local_dt = datetime.strptime(local_time_str, "%Y-%m-%d %H:%M:%S")
|
||
local_dt = local_dt.replace(tzinfo=local_tz)
|
||
utc_dt = local_dt.astimezone(timezone.utc)
|
||
return utc_dt.isoformat().replace('+00:00', 'Z')
|
||
|
||
# 使用示例
|
||
if __name__ == "__main__":
|
||
# 北京时间 2025-01-15 00:00:00 转换为 UTC
|
||
utc_time = convert_to_utc("2025-01-15 00:00:00", "Asia/Shanghai")
|
||
print(f"UTC Time: {utc_time}") # 输出: 2025-01-14T16:00:00Z
|
||
|
||
search_mails()
|
||
```
|
||
|
||
#### cURL 示例
|
||
|
||
```bash
|
||
curl -X POST "https://api.example.com/mailbox/mail/search" \
|
||
-H "Content-Type: application/json" \
|
||
-H "Accept-Encoding: gzip, deflate, br" \
|
||
-H "client-key: your-client-key" \
|
||
-H "client-secret: your-client-secret" \
|
||
-d '{
|
||
"keyword": "机票",
|
||
"mailType": 1,
|
||
"startTime": "2025-01-14T16:00:00Z",
|
||
"endTime": "2025-01-15T15:59:59Z",
|
||
"pageIndex": 1,
|
||
"pageSize": 20,
|
||
"orderBy": "sendTime",
|
||
"orderDirection": "DESC"
|
||
}'
|
||
```
|
||
|
||
## 搜索技巧
|
||
|
||
- 支持模糊匹配，关键词可以匹配邮件主题和发件人
|
||
- mailType 为可选参数，不传则搜索所有类型邮件
|
||
- 建议 pageSize 设置为 20-50 以获得最佳性能
|
||
- **时间参数必须使用 UTC 时区**，发送前请确保时间已正确转换
|
||
|
||
## 错误码说明
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 400 | 请求参数错误，pageIndex、pageSize、orderBy 或 orderDirection 不合法 |
|
||
| 401 | 认证失败，client-key 或 client-secret 无效 |
|
||
| 500 | 服务器内部错误 |
|