Zoho Mail

通过托管的OAuth认证访问Zoho Mail API。发送、接收、搜索和管理电子邮件，并提供完整的文件夹和标签管理功能。

快速开始

# 列出所有账户
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-mail/api/accounts')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础URL

https://gateway.maton.ai/zoho-mail/{原生API路径}

替换{原生API路径}为实际的Zoho Mail API端点路径。网关将请求代理到mail.zoho.com并自动注入您的OAuth令牌。

认证

所有请求都需要在Authorization头部中包含Maton API密钥：

Authorization: Bearer $MATON_API_KEY

环境变量：将您的API密钥设置为MATON_API_KEY：

export MATON_API_KEY="您的API密钥"

获取您的API密钥

1. 登录或前往maton.ai
2. 前往maton.ai/settings
3. 复制您的API密钥

连接管理

在以下地址管理您的Zoho Mail OAuth连接：https://ctrl.maton.ai。

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=zoho-mail&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'zoho-mail'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：

{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "zoho-mail",
    "metadata": {}
  }
}

在浏览器中打开返回的网址以完成OAuth授权。

删除连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

如果您有多个Zoho Mail连接，请使用Maton-Connectionheader:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-mail/api/accounts')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果省略，网关将使用默认的（最早创建的）活跃连接。

API 参考

账户操作

获取所有账户

检索认证用户的所有邮件账户。

GET /zoho-mail/api/accounts

示例：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-mail/api/accounts')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取账户详情

GET /zoho-mail/api/accounts/{accountId}

文件夹操作

列出所有文件夹

GET /zoho-mail/api/accounts/{accountId}/folders

示例：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-mail/api/accounts/{accountId}/folders')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：

{
  "status": {
    "code": 200,
    "description": "success"
  },
  "data": [
    {
      "folderId": "1367000000000008014",
      "folderName": "收件箱",
      "folderType": "Inbox",
      "path": "/Inbox",
      "imapAccess": true,
      "isArchived": 0,
      "URI": "https://mail.zoho.com/api/accounts/1367000000000008002/folders/1367000000000008014"
    },
    {
      "folderId": "1367000000000008016",
      "folderName": "草稿",
      "folderType": "Drafts",
      "path": "/Drafts",
      "imapAccess": true,
      "isArchived": 0
    }
  ]
}

创建文件夹

POST /zoho-mail/api/accounts/{accountId}/folders
Content-Type: application/json

{
  "folderName": "我的自定义文件夹"
}

重命名文件夹

PUT /zoho-mail/api/accounts/{accountId}/folders/{folderId}
Content-Type: application/json

{
  "folderName": "Renamed Folder"
}

删除文件夹

DELETE /zoho-mail/api/accounts/{accountId}/folders/{folderId}

标签操作

列出标签

GET /zoho-mail/api/accounts/{accountId}/labels

示例：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-mail/api/accounts/{accountId}/labels')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建标签

POST /zoho-mail/api/accounts/{accountId}/labels
Content-Type: application/json

{
  "labelName": "Important"
}

更新标签

PUT /zoho-mail/api/accounts/{accountId}/labels/{labelId}
Content-Type: application/json

{
  "labelName": "Updated Label"
}

删除标签

DELETE /zoho-mail/api/accounts/{accountId}/labels/{labelId}

邮件消息操作

列出文件夹中的邮件

GET /zoho-mail/api/accounts/{accountId}/messages/view?folderId={folderId}

查询参数：

示例：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-mail/api/accounts/{accountId}/messages/view?folderId={folderId}&limit=10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

搜索邮件

GET /zoho-mail/api/accounts/{accountId}/messages/search?searchKey={query}

查询参数：

示例：

python <<'EOF'
import urllib.request, os, json
import urllib.parse
query = urllib.parse.quote('from:sender@example.com')
req = urllib.request.Request(f'https://gateway.maton.ai/zoho-mail/api/accounts/{{accountId}}/messages/search?searchKey={query}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取邮件内容

GET /zoho-mail/api/accounts/{accountId}/folders/{folderId}/messages/{messageId}/content

示例：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-mail/api/accounts/{accountId}/folders/{folderId}/messages/{messageId}/content')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取邮件标头

GET /zoho-mail/api/accounts/{accountId}/folders/{folderId}/messages/{messageId}/header

获取邮件元数据

GET /zoho-mail/api/accounts/{accountId}/folders/{folderId}/messages/{messageId}/details

获取原始邮件（MIME格式）

GET /zoho-mail/api/accounts/{accountId}/messages/{messageId}/originalmessage

发送邮件

POST /zoho-mail/api/accounts/{accountId}/messages
Content-Type: application/json

{
  "fromAddress": "sender@yourdomain.com",
  "toAddress": "recipient@example.com",
  "subject": "邮件主题",
  "content": "邮件正文内容",
  "mailFormat": "html"
}

请求体字段：

python <<'EOF' import urllib.request, os, json data = json.dumps({ "fromAddress": "sender@yourdomain.com", "toAddress": "recipient@example.com", "subject": "Hello from Zoho Mail API", "content": "<h1>Hello!</h1><p>This is a test email.</p>", "mailFormat": "html" }).encode() req = urllib.request.Request('https://gateway.maton.ai/zoho-mail/api/accounts/{accountId}/messages', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF

调度参数（可选）：

字段

POST /zoho-mail/api/accounts/{accountId}/messages/{messageId} Content-Type: application/json { "fromAddress": "sender@yourdomain.com", "toAddress": "recipient@example.com", "subject": "回复：原始主题", "content": "回复内容" }

POST /zoho-mail/api/accounts/{accountId}/messages/{messageId}
Content-Type: application/json

{
  "fromAddress": "sender@yourdomain.com",
  "toAddress": "recipient@example.com",
  "subject": "Re: Original Subject",
  "content": "Reply content"
}

保存草稿

POST /zoho-mail/api/accounts/{accountId}/messages
Content-Type: application/json

{
  "fromAddress": "sender@yourdomain.com",
  "toAddress": "recipient@example.com",
  "subject": "草稿主题",
  "content": "草稿内容",
  "mode": "draft"
}

更新邮件（标记为已读/未读、移动、标记）

PUT /zoho-mail/api/accounts/{accountId}/updatemessage
Content-Type: application/json

{
  "messageId": ["messageId1", "messageId2"],
  "folderId": "folderId",
  "mode": "markAsRead"
}

模式选项：

• markAsRead- 将邮件标记为已读
• markAsUnread- 将邮件标记为未读
• moveMessage- 移动邮件（需要destfolderId）
• flag- 设置标记（需要flagid: 1-4）
• archive- 归档邮件
• 取消归档- 取消归档消息
• 垃圾邮件- 标记为垃圾邮件
• 非垃圾邮件- 标记为非垃圾邮件

示例 - 标记为已读：

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "messageId": ["1234567890123456789"],
    "folderId": "9876543210987654321",
    "mode": "markAsRead"
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/zoho-mail/api/accounts/{accountId}/updatemessage', data=data, method='PUT')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

删除邮件

DELETE /zoho-mail/api/accounts/{accountId}/folders/{folderId}/messages/{messageId}

附件操作

上传附件

POST /zoho-mail/api/accounts/{accountId}/messages/attachments
Content-Type: multipart/form-data

获取附件信息

GET /zoho-mail/api/accounts/{accountId}/folders/{folderId}/messages/{messageId}/attachmentinfo

下载附件

GET /zoho-mail/api/accounts/{accountId}/folders/{folderId}/messages/{messageId}/attachments/{attachmentId}

分页

Zoho Mail 使用基于偏移量的分页：

GET /zoho-mail/api/accounts/{accountId}/messages/view?folderId={folderId}&start=0&limit=50

• start：起始索引（默认值：0）
• limit：要返回的记录数（默认值：50）

对于后续页面，将start增加limit的值：

• 第 1 页：start=0&limit=50
• 第 2 页：start=50&limit=50
• 第 3 页：start=100&limit=50

代码示例

JavaScript

const response = await fetch(
  'https://gateway.maton.ai/zoho-mail/api/accounts',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const data = await response.json();

Python

import os
import requests

response = requests.get(
    'https://gateway.maton.ai/zoho-mail/api/accounts',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
data = response.json()

注意事项

• 大多数操作都需要账户ID - 首先调用/api/accounts以获取您的账户ID
• 消息ID和文件夹ID是数字字符串
• 发件地址必须与已认证的账户相关联默认文件夹包括：收件箱、草稿、模板、稍后处理、已发送、垃圾邮件、已删除、发件箱
• 支持的编码：Big5、EUC-JP、EUC-KR、GB2312、ISO-2022-JP、ISO-8859-1、KOI8-R、Shift_JIS、US-ASCII、UTF-8、WINDOWS-1251
• 某些操作（标签、文件夹管理、发送）需要额外的OAuth范围。如果您收到
• INVALID_OAUTHSCOPE错误，请联系Maton支持，邮箱为support@maton.ai并提供您需要的具体操作/API及您的使用场景重要提示：使用curl命令时，请使用
• curl -gcurl -g当URL包含方括号以禁用通配符解析时
• 重要提示：当将curl输出通过管道传递给jq或其他命令时，环境变量如$MATON_API_KEY在某些shell环境中可能无法正确展开

错误处理

故障排除：API密钥问题

1. 检查MATON_API_KEY环境变量是否已设置：

echo $MATON_API_KEY

2. 通过列出连接来验证API密钥是否有效：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

故障排除：无效的应用名称

1. 请确保您的URL路径以zoho-mail开头。例如：

• 正确：https://gateway.maton.ai/zoho-mail/api/accounts
• 错误：https://gateway.maton.ai/api/accounts

资源

• Zoho Mail API概述
• Zoho Mail API索引
• 电子邮件消息API
• Zoho Mail API入门指南
• Maton社区
• Maton技术支持