Zoho Mail 技能

直接通过 Clawdbot 读取、搜索和管理 Zoho Mail。

配置

1. 前往 Zoho API 控制台，创建一个 自用客户端（Self Client）
2. 记录下 Client ID 和 Client Secret
3. 使用以下作用域（scopes）生成授权码（grant code）：ZohoMail.messages.READ,ZohoMail.folders.READ,ZohoMail.accounts.READ
4. 使用授权码换取刷新令牌（refresh token）：

   curl -s -X POST "https://accounts.zoho.com/oauth/v2/token" 
     -d "code=YOUR_GRANT_CODE" 
     -d "client_id=YOUR_CLIENT_ID" 
     -d "client_secret=YOUR_CLIENT_SECRET" 
     -d "grant_type=authorization_code" | jq
   

5. 设置环境变量：

   export ZOHO_CLIENT_ID="your-client-id"
   export ZOHO_CLIENT_SECRET="your-client-secret"
   export ZOHO_REFRESH_TOKEN="your-refresh-token"
   

认证

Zoho 使用 OAuth 2.0 认证机制。访问令牌（access token）有效期为 1 小时，因此每次调用 API 前都必须刷新；刷新令牌（refresh token）长期有效，除非被主动撤销。

获取访问令牌

ZOHO_ACCESS_TOKEN=$(curl -s -X POST "https://accounts.zoho.com/oauth/v2/token" 
  -d "refresh_token=$ZOHO_REFRESH_TOKEN" 
  -d "client_id=$ZOHO_CLIENT_ID" 
  -d "client_secret=$ZOHO_CLIENT_SECRET" 
  -d "grant_type=refresh_token" | jq -r '.access_token')

重要提示：请在每次 API 会话开始前执行该命令，或在收到 401 错误时立即执行。下方所有命令均假定 $ZOHO_ACCESS_TOKEN 已正确设置。

使用方法

所有命令均使用 curl 并携带 Zoho-oauthtoken 认证请求头。注意：Zoho 使用的前缀是 Zoho-oauthtoken，不是 Bearer。

获取账户 ID

curl -s "https://mail.zoho.com/api/accounts" 
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" | jq '.data[0] | {accountId, mailboxAddress, firstName, lastName}'

将账户 ID 存储为变量供后续调用使用：

ZOHO_ACCOUNT_ID=$(curl -s "https://mail.zoho.com/api/accounts" 
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" | jq -r '.data[0].accountId')

列出文件夹

curl -s "https://mail.zoho.com/api/accounts/$ZOHO_ACCOUNT_ID/folders" 
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" | jq '.data[] | {folderName, folderId, unreadCount, messageCount}'

获取收件箱（Inbox）文件夹 ID

INBOX_ID=$(curl -s "https://mail.zoho.com/api/accounts/$ZOHO_ACCOUNT_ID/folders" 
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" | jq -r '.data[] | select(.folderName=="Inbox") | .folderId')

列出收件箱邮件

curl -s "https://mail.zoho.com/api/accounts/$ZOHO_ACCOUNT_ID/messages/view?folderId=$INBOX_ID&limit=10&start=0" 
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" | jq '.data[] | {subject, sender, fromAddress, receivedTime, messageId, status2}'

列出指定文件夹中的邮件

curl -s "https://mail.zoho.com/api/accounts/$ZOHO_ACCOUNT_ID/messages/view?folderId={folderId}&limit=10&start=0" 
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" | jq '.data[] | {subject, sender, receivedTime, messageId}'

读取某封特定邮件

curl -s "https://mail.zoho.com/api/accounts/$ZOHO_ACCOUNT_ID/messages/{messageId}" 
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" | jq '.data | {subject, sender, fromAddress, toAddress, ccAddress, receivedTime, content}'

仅获取邮件正文内容

curl -s "https://mail.zoho.com/api/accounts/$ZOHO_ACCOUNT_ID/messages/{messageId}/content" 
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" | jq -r '.data.content'

搜索邮件

curl -s "https://mail.zoho.com/api/accounts/$ZOHO_ACCOUNT_ID/messages/search?searchKey={query}&limit=10" 
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" | jq '.data[] | {subject, sender, receivedTime, messageId, summary}'

搜索语法支持以下形式：

• 纯文本搜索：searchKey=invoice
• 发件人筛选：searchKey=from:john@example.com
• 主题筛选：searchKey=subject:quarterly report
• 日期范围：searchKey=after:2024-01-01 before:2024-06-30
• 组合条件：searchKey=from:boss@company.com subject:meeting

列出邮件会话（threads）

curl -s "https://mail.zoho.com/api/accounts/$ZOHO_ACCOUNT_ID/threads/view?folderId=$INBOX_ID&limit=10&start=0" 
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" | jq '.data[] | {subject, threadId, messageCount}'

获取会话详情（包含该会话中全部邮件）

curl -s "https://mail.zoho.com/api/accounts/$ZOHO_ACCOUNT_ID/threads/{threadId}" 
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" | jq

列出标签（labels/tags）

curl -s "https://mail.zoho.com/api/accounts/$ZOHO_ACCOUNT_ID/tags" 
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" | jq '.data[] | {tagName, tagId, color}'

列出某封邮件的附件

curl -s "https://mail.zoho.com/api/accounts/$ZOHO_ACCOUNT_ID/folders/{folderId}/messages/{messageId}/attachments" 
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" | jq '.data[] | {attachmentName, attachmentId, fileSize}'

获取账户信息

curl -s "https://mail.zoho.com/api/accounts/$ZOHO_ACCOUNT_ID" 
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" | jq '.data | {firstName, lastName, mailboxAddress, usedStorage, planStorage}'

区域化端点（Regional Endpoints）

若您的 Zoho 账户不在美国区域，请将 mail.zoho.com 和 accounts.zoho.com 替换为下表对应域名：

注意事项

• 访问令牌（access token）有效期为 1 小时 —— 每次会话前务必刷新
• 刷新令牌（refresh token）不会过期，除非被手动撤销
• 速率限制：每个账户每分钟最多 30 次 API 请求
• receivedTime 字段单位为毫秒（自 Unix 纪元起），可使用如下命令转换为可读时间：date -d @$((receivedTime/1000))
• status2 字段含义："0" 表示未读，"1" 表示已读
• 认证请求头必须使用 Zoho-oauthtoken 前缀，不可使用 Bearer
• 请务必妥善保管您的 Client Secret 和 Refresh Token！

示例

# 完整会话示例：刷新令牌、获取账户 ID、列出收件箱
ZOHO_ACCESS_TOKEN=$(curl -s -X POST "https://accounts.zoho.com/oauth/v2/token" 
  -d "refresh_token=$ZOHO_REFRESH_TOKEN" 
  -d "client_id=$ZOHO_CLIENT_ID" 
  -d "client_secret=$ZOHO_CLIENT_SECRET" 
  -d "grant_type=refresh_token" | jq -r '.access_token')

ZOHO_ACCOUNT_ID=$(curl -s "https://mail.zoho.com/api/accounts" 
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" | jq -r '.data[0].accountId')

INBOX_ID=$(curl -s "https://mail.zoho.com/api/accounts/$ZOHO_ACCOUNT_ID/folders" 
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" | jq -r '.data[] | select(.folderName=="Inbox") | .folderId')

# 列出最新的 5 封收件箱邮件
curl -s "https://mail.zoho.com/api/accounts/$ZOHO_ACCOUNT_ID/messages/view?folderId=$INBOX_ID&limit=5" 
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" | jq '.data[] | {subject, sender, receivedTime}'

# 搜索来自某位联系人的邮件
curl -s "https://mail.zoho.com/api/accounts/$ZOHO_ACCOUNT_ID/messages/search?searchKey=from:monika@example.com&limit=5" 
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" | jq '.data[] | {subject, sender, summary}'

# 获取各文件夹未读邮件数量（仅显示未读数大于 0 的文件夹）
curl -s "https://mail.zoho.com/api/accounts/$ZOHO_ACCOUNT_ID/folders" 
  -H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" | jq '.data[] | select(.unreadCount > 0) | {folderName, unreadCount}'