- name
- zoho-mail
- description
- Read, search, and manage Zoho Mail via the Zoho Mail REST API.
- homepage
- https://www.zoho.com/mail/help/api/
- metadata
- {"clawdbot":{"emoji":"📧","requires":{"bins":["jq","curl"],"env":["ZOHO_CLIENT_ID","ZOHO_CLIENT_SECRET","ZOHO_REFRESH_TOKEN"]}}}
Zoho Mail Skill
Read, search, and manage Zoho Mail directly from Clawdbot.
Setup
- Go to Zoho API Console and create a Self Client
- Note the Client ID and Client Secret
- Generate a grant code with scopes:
ZohoMail.messages.READ,ZohoMail.folders.READ,ZohoMail.accounts.READ - Exchange the grant code for a 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- Set environment variables:
export ZOHO_CLIENT_ID="your-client-id"
export ZOHO_CLIENT_SECRET="your-client-secret"
export ZOHO_REFRESH_TOKEN="your-refresh-token"Authentication
Zoho uses OAuth 2.0. Access tokens expire after 1 hour, so always refresh before making API calls. The refresh token does not expire unless revoked.
Get an access 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')Important: Run this command before every API session or when you get a 401 error. All commands below assume $ZOHO_ACCESS_TOKEN is set.
Usage
All commands use curl with the Zoho-oauthtoken authorization header. Note: Zoho uses Zoho-oauthtoken prefix, not Bearer.
Get account ID
curl -s "https://mail.zoho.com/api/accounts" \
-H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" | jq '.data[0] | {accountId, mailboxAddress, firstName, lastName}'Store the account ID for subsequent calls:
ZOHO_ACCOUNT_ID=$(curl -s "https://mail.zoho.com/api/accounts" \
-H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" | jq -r '.data[0].accountId')List folders
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}'Get Inbox folder 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')List inbox messages
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}'List messages in a specific folder
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}'Read a specific email
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}'Get email body content only
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'Search emails
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}'Search syntax supports:
- Simple text:
searchKey=invoice - From filter:
searchKey=from:john@example.com - Subject filter:
searchKey=subject:quarterly report - Date range:
searchKey=after:2024-01-01 before:2024-06-30 - Combined:
searchKey=from:boss@company.com subject:meeting
List email 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}'Get thread details (all messages in a thread)
curl -s "https://mail.zoho.com/api/accounts/$ZOHO_ACCOUNT_ID/threads/{threadId}" \
-H "Authorization: Zoho-oauthtoken $ZOHO_ACCESS_TOKEN" | jqList 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}'List attachments on an email
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}'Get account info
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
If your Zoho account is not in the US region, replace mail.zoho.com and accounts.zoho.com with:
| Region | Mail API | Auth |
|---|---|---|
| US | mail.zoho.com | accounts.zoho.com |
| EU | mail.zoho.eu | accounts.zoho.eu |
| India | mail.zoho.in | accounts.zoho.in |
| Australia | mail.zoho.com.au | accounts.zoho.com.au |
| Japan | mail.zoho.jp | accounts.zoho.jp |
| Canada | mail.zohocloud.ca | accounts.zohocloud.ca |
Notes
- Access tokens expire after 1 hour — refresh before each session
- The refresh token does not expire unless revoked
- Rate limit: 30 API requests per minute per account
receivedTimeis in milliseconds since epoch — convert with:date -d @$((receivedTime/1000))status2field:"0"= unread,"1"= read- Auth header uses
Zoho-oauthtokenprefix, notBearer - Keep your Client Secret and Refresh Token secure!
Examples
# Full session: refresh token, get account, list inbox
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')
# List latest 5 inbox emails
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}'
# Search for emails from a specific person
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}'
# Get unread count per folder
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}'