邮箱 API

概述

邮箱 API 允许您使用 API 密钥认证以编程方式管理临时邮箱地址、检索收件箱邮件和查看邮件详情。

体验平台

您可以在邮箱 API 体验平台中尝试所有 API 接口。

认证方式

使用 API 密钥有两种方式：

授权请求头（推荐）:
```
Authorization: Bearer YOUR_API_KEY
```
查询参数:
```
?key=YOUR_API_KEY
```

频率限制

频率限制会根据您的订阅等级自动配置：

免费计划: 每小时 200 次请求
专业计划: 每小时 2000 次请求
终身计划: 每小时 5000 次请求

配额限制

邮箱地址创建受基于订阅等级的月度配额限制：

免费计划: 每月 50 个邮箱地址
专业计划: 每月 1,000 个邮箱地址
终身计划: 无限制邮箱地址

接口端点

1. 创建邮箱地址

POST /api/v1/emails/create

为认证用户创建新的邮箱地址。

请求体

{
  "email": "myemail@ig.do",
  "tag": "个人"
}

参数说明

参数	类型	必填	描述
`email`	string	是	完整的邮箱地址（前缀 4-64 字符，格式有效）
`tag`	string	否	用于分类的标签（最多 50 字符）

成功响应 (201)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "myemail@ig.do",
    "tag": "个人",
    "like": false,
    "pin": false,
    "createdAt": "2026-01-02T12:00:00.000Z"
  }
}

错误响应

403 Forbidden - 已达到月度配额限制
409 Conflict - 邮箱地址已存在
400 Bad Request - 邮箱格式无效或前缀被保留

2. 获取邮箱地址列表

GET /api/v1/emails

获取认证用户的邮箱地址分页列表。

查询参数

参数	类型	必填	默认值	描述
`page`	number	否	1	分页页码
`pageSize`	number	否	20	每页项目数（最多 100）
`email`	string	否	-	按邮箱地址筛选（模糊搜索）

请求示例

GET /api/v1/emails?page=1&pageSize=20&email=test

成功响应 (200)

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "test123@ig.do",
      "tag": "个人",
      "like": false,
      "pin": false,
      "createdAt": "2026-01-02T12:00:00.000Z",
      "updatedAt": "2026-01-02T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 45,
    "totalPages": 3
  }
}

3. 通过 ID 获取邮箱地址

GET /api/v1/emails/:id

获取特定邮箱地址的详细信息，包括收件箱统计数据。

路径参数

参数	类型	必填	描述
`id`	string	是	邮箱地址 ID

成功响应 (200)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "test123@ig.do",
    "tag": "个人",
    "like": false,
    "pin": false,
    "createdAt": "2026-01-02T12:00:00.000Z",
    "updatedAt": "2026-01-02T12:00:00.000Z",
    "stats": {
      "total": 15,
      "unread": 3
    }
  }
}

错误响应

404 Not Found - 邮箱地址未找到或不属于您

4. 获取收件箱邮件

GET /api/v1/emails/:id/inbox

获取特定邮箱地址的收件箱邮件，支持文件夹筛选。

路径参数

参数	类型	必填	描述
`id`	string	是	邮箱地址 ID

查询参数

参数	类型	必填	默认值	描述
`folder`	string	否	inbox	文件夹类型：`inbox`、`starred`、`archive`、`trash`
`page`	number	否	1	分页页码
`pageSize`	number	否	50	每页项目数（最多 100）

请求示例

GET /api/v1/emails/550e8400-e29b-41d4-a716-446655440000/inbox?folder=inbox&page=1&pageSize=20

成功响应 (200)

{
  "success": true,
  "data": [
    {
      "id": "msg-123",
      "from": "sender@example.com",
      "to": "test123@ig.do",
      "subject": "欢迎！",
      "text": "欢迎使用我们的服务",
      "html": "<p>欢迎使用我们的服务</p>",
      "readAt": null,
      "like": false,
      "tag": null,
      "createdAt": "2026-01-02T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 15,
    "totalPages": 1
  }
}

5. 获取邮件详情

GET /api/v1/emails/:id/inbox/:messageId

获取特定邮件的完整详细信息。

路径参数

参数	类型	必填	描述
`id`	string	是	邮箱地址 ID
`messageId`	string	是	邮件 ID

成功响应 (200)

{
  "success": true,
  "data": {
    "id": "msg-123",
    "from": "sender@example.com",
    "to": "test123@ig.do",
    "subject": "欢迎！",
    "text": "欢迎使用我们的服务",
    "html": "<p>欢迎使用我们的服务</p>",
    "headers": {},
    "readAt": "2026-01-02T13:00:00.000Z",
    "like": false,
    "tag": null,
    "createdAt": "2026-01-02T12:00:00.000Z",
    "updatedAt": "2026-01-02T13:00:00.000Z"
  }
}

错误响应

404 Not Found - 邮箱地址或邮件未找到

域名访问权限

对域名的访问权限基于您的订阅等级：

免费域名（ig.do）：所有用户可用
专业域名（kfc.sh、uv.do）：需要专业订阅或终身计划

如果您尝试在没有适当订阅的情况下使用专业域名，将收到 403 错误。

代码示例

cURL - 创建邮箱

curl -X POST https://like.do/api/v1/emails/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "myemail@ig.do",
    "tag": "个人"
  }'

cURL - 获取邮箱列表

curl -X GET "https://like.do/api/v1/emails?page=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript - 获取收件箱

const response = await fetch(
  'https://like.do/api/v1/emails/550e8400-e29b-41d4-a716-446655440000/inbox?folder=inbox',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
    },
  }
);

const data = await response.json();
console.log(data);

Python - 获取邮件详情

import requests

url = 'https://like.do/api/v1/emails/550e8400-e29b-41d4-a716-446655440000/inbox/msg-123'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
}

response = requests.get(url, headers=headers)
print(response.json())

创建 API 密钥

在仪表板中导航到 设置 > API 密钥
点击 创建 API 密钥
根据您的计划配置频率限制
安全保存您的 API 密钥（仅显示一次）

最佳实践

安全存储 API 密钥：永远不要将 API 密钥提交到版本控制
使用环境变量：将密钥存储在 .env 文件或安全保险库中
监控频率限制：跟踪您的使用情况以避免达到限制
验证邮箱格式：在创建之前确保邮箱地址格式正确
优雅地处理错误：在代码中实现适当的错误处理
使用 HTTPS：始终使用安全连接进行 API 请求
检查配额限制：监控您的月度邮箱创建配额
实现分页：对于大量邮箱列表使用分页

注意事项

邮箱前缀必须在 4 到 64 字符之间
邮箱地址在每个用户和域名中是唯一的
保留字（例如 admin、noreply、postmaster）不能用作邮箱前缀
软删除的邮箱地址不包含在唯一性检查中
所有时间戳均为 ISO 8601 格式（UTC）
文件夹类型：inbox（默认）、starred（星标邮件）、archive（归档）、trash（已删除）

概述

邮箱 API 允许您使用 API 密钥认证以编程方式管理临时邮箱地址、检索收件箱邮件和查看邮件详情。

体验平台

您可以在邮箱 API 体验平台中尝试所有 API 接口。

认证方式

使用 API 密钥有两种方式：

授权请求头（推荐）:
```
Authorization: Bearer YOUR_API_KEY
```
查询参数:
```
?key=YOUR_API_KEY
```

频率限制

频率限制会根据您的订阅等级自动配置：

免费计划: 每小时 200 次请求
专业计划: 每小时 2000 次请求
终身计划: 每小时 5000 次请求

配额限制

邮箱地址创建受基于订阅等级的月度配额限制：

免费计划: 每月 50 个邮箱地址
专业计划: 每月 1,000 个邮箱地址
终身计划: 无限制邮箱地址

接口端点

1. 创建邮箱地址

POST /api/v1/emails/create

为认证用户创建新的邮箱地址。

请求体

{
  "email": "myemail@ig.do",
  "tag": "个人"
}

参数说明

参数	类型	必填	描述
`email`	string	是	完整的邮箱地址（前缀 4-64 字符，格式有效）
`tag`	string	否	用于分类的标签（最多 50 字符）

成功响应 (201)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "myemail@ig.do",
    "tag": "个人",
    "like": false,
    "pin": false,
    "createdAt": "2026-01-02T12:00:00.000Z"
  }
}

错误响应

403 Forbidden - 已达到月度配额限制
409 Conflict - 邮箱地址已存在
400 Bad Request - 邮箱格式无效或前缀被保留

2. 获取邮箱地址列表

GET /api/v1/emails

获取认证用户的邮箱地址分页列表。

查询参数

参数	类型	必填	默认值	描述
`page`	number	否	1	分页页码
`pageSize`	number	否	20	每页项目数（最多 100）
`email`	string	否	-	按邮箱地址筛选（模糊搜索）

请求示例

GET /api/v1/emails?page=1&pageSize=20&email=test

成功响应 (200)

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "test123@ig.do",
      "tag": "个人",
      "like": false,
      "pin": false,
      "createdAt": "2026-01-02T12:00:00.000Z",
      "updatedAt": "2026-01-02T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 45,
    "totalPages": 3
  }
}

3. 通过 ID 获取邮箱地址

GET /api/v1/emails/:id

获取特定邮箱地址的详细信息，包括收件箱统计数据。

路径参数

参数	类型	必填	描述
`id`	string	是	邮箱地址 ID

成功响应 (200)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "test123@ig.do",
    "tag": "个人",
    "like": false,
    "pin": false,
    "createdAt": "2026-01-02T12:00:00.000Z",
    "updatedAt": "2026-01-02T12:00:00.000Z",
    "stats": {
      "total": 15,
      "unread": 3
    }
  }
}

错误响应

404 Not Found - 邮箱地址未找到或不属于您

4. 获取收件箱邮件

GET /api/v1/emails/:id/inbox

获取特定邮箱地址的收件箱邮件，支持文件夹筛选。

路径参数

参数	类型	必填	描述
`id`	string	是	邮箱地址 ID

查询参数

参数	类型	必填	默认值	描述
`folder`	string	否	inbox	文件夹类型：`inbox`、`starred`、`archive`、`trash`
`page`	number	否	1	分页页码
`pageSize`	number	否	50	每页项目数（最多 100）

请求示例

GET /api/v1/emails/550e8400-e29b-41d4-a716-446655440000/inbox?folder=inbox&page=1&pageSize=20

成功响应 (200)

{
  "success": true,
  "data": [
    {
      "id": "msg-123",
      "from": "sender@example.com",
      "to": "test123@ig.do",
      "subject": "欢迎！",
      "text": "欢迎使用我们的服务",
      "html": "<p>欢迎使用我们的服务</p>",
      "readAt": null,
      "like": false,
      "tag": null,
      "createdAt": "2026-01-02T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 15,
    "totalPages": 1
  }
}

5. 获取邮件详情

GET /api/v1/emails/:id/inbox/:messageId

获取特定邮件的完整详细信息。

路径参数

参数	类型	必填	描述
`id`	string	是	邮箱地址 ID
`messageId`	string	是	邮件 ID

成功响应 (200)

{
  "success": true,
  "data": {
    "id": "msg-123",
    "from": "sender@example.com",
    "to": "test123@ig.do",
    "subject": "欢迎！",
    "text": "欢迎使用我们的服务",
    "html": "<p>欢迎使用我们的服务</p>",
    "headers": {},
    "readAt": "2026-01-02T13:00:00.000Z",
    "like": false,
    "tag": null,
    "createdAt": "2026-01-02T12:00:00.000Z",
    "updatedAt": "2026-01-02T13:00:00.000Z"
  }
}

错误响应

404 Not Found - 邮箱地址或邮件未找到

域名访问权限

对域名的访问权限基于您的订阅等级：

免费域名（ig.do）：所有用户可用
专业域名（kfc.sh、uv.do）：需要专业订阅或终身计划

如果您尝试在没有适当订阅的情况下使用专业域名，将收到 403 错误。

代码示例

cURL - 创建邮箱

curl -X POST https://like.do/api/v1/emails/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "myemail@ig.do",
    "tag": "个人"
  }'

cURL - 获取邮箱列表

curl -X GET "https://like.do/api/v1/emails?page=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript - 获取收件箱

const response = await fetch(
  'https://like.do/api/v1/emails/550e8400-e29b-41d4-a716-446655440000/inbox?folder=inbox',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
    },
  }
);

const data = await response.json();
console.log(data);

Python - 获取邮件详情

import requests

url = 'https://like.do/api/v1/emails/550e8400-e29b-41d4-a716-446655440000/inbox/msg-123'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
}

response = requests.get(url, headers=headers)
print(response.json())

创建 API 密钥

在仪表板中导航到 设置 > API 密钥
点击 创建 API 密钥
根据您的计划配置频率限制
安全保存您的 API 密钥（仅显示一次）

最佳实践

安全存储 API 密钥：永远不要将 API 密钥提交到版本控制
使用环境变量：将密钥存储在 .env 文件或安全保险库中
监控频率限制：跟踪您的使用情况以避免达到限制
验证邮箱格式：在创建之前确保邮箱地址格式正确
优雅地处理错误：在代码中实现适当的错误处理
使用 HTTPS：始终使用安全连接进行 API 请求
检查配额限制：监控您的月度邮箱创建配额
实现分页：对于大量邮箱列表使用分页

注意事项

邮箱前缀必须在 4 到 64 字符之间
邮箱地址在每个用户和域名中是唯一的
保留字（例如 admin、noreply、postmaster）不能用作邮箱前缀
软删除的邮箱地址不包含在唯一性检查中
所有时间戳均为 ISO 8601 格式（UTC）
文件夹类型：inbox（默认）、starred（星标邮件）、archive（归档）、trash（已删除）

目录

邮箱 API

目录