Zoho Mail

Zoho Mail API integration with managed OAuth. Send, receive, and manage emails, folders, and labels. Use this skill when users want to send emails, read messages, manage folders, or work with email labels in Zoho Mail. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). Requires network access and valid Maton API key.

Install
$clawhub install zoho-mail

Zoho Mail

Access the Zoho Mail API with managed OAuth authentication. Send, receive, search, and manage emails with full folder and label management.

Quick Start

# List all 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

Base URL

https://gateway.maton.ai/zoho-mail/{native-api-path}

Replace {native-api-path} with the actual Zoho Mail API endpoint path. The gateway proxies requests to mail.zoho.com and automatically injects your OAuth token.

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

  1. Sign in or create an account at maton.ai
  2. Go to maton.ai/settings
  3. Copy your API key

Connection Management

Manage your Zoho Mail OAuth connections at https://ctrl.maton.ai.

List Connections

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

Create Connection

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

Get Connection

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

Response: json { "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": {} } }

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

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

Specifying Connection

If you have multiple Zoho Mail connections, specify which one to use with the Maton-Connection header:

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

If omitted, the gateway uses the default (oldest) active connection.

API Reference

Account Operations

Get All Accounts

Retrieve all mail accounts for the authenticated user.

GET /zoho-mail/api/accounts

Example:

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 Account Details

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

Folder Operations

List All Folders

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

Example:

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

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

Create Folder

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

{
  "folderName": "My Custom Folder"
}

Rename Folder

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

{
  "folderName": "Renamed Folder"
}

Delete Folder

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

Label Operations

List Labels

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

Example:

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

Create Label

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

{
  "labelName": "Important"
}

Update Label

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

{
  "labelName": "Updated Label"
}

Delete Label

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

Email Message Operations

List Emails in Folder

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

Query Parameters:

Parameter Type Description
folderId long Folder ID to list messages from
limit integer Number of messages to return (default: 50)
start integer Offset for pagination
sortBy string Sort field (e.g., date)
sortOrder boolean true for ascending, false for descending

Example:

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

Search Emails

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

Query Parameters:

Parameter Type Description
searchKey string Search query
limit integer Number of results to return
start integer Offset for pagination

Example:

python <<'EOF'
import urllib.request, os, json
import urllib.parse
query = urllib.parse.quote('from:[email protected]')
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 Email Content

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

Example:

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 Email Headers

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

Get Email Metadata

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

Get Original Message (MIME)

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

Send Email

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

{
  "fromAddress": "[email protected]",
  "toAddress": "[email protected]",
  "subject": "Email Subject",
  "content": "Email body content",
  "mailFormat": "html"
}

Request Body Fields:

Field Type Required Description
fromAddress string Yes Sender's email address
toAddress string Yes Recipient's email address
subject string Yes Email subject
content string Yes Email body content
ccAddress string No CC recipient
bccAddress string No BCC recipient
mailFormat string No html or plaintext (default: html)
askReceipt string No yes or no for read receipt
encoding string No Character encoding (default: UTF-8)

Example - Send Email:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "fromAddress": "[email protected]",
    "toAddress": "[email protected]",
    "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

Scheduling Parameters (Optional):

Field Type Description
isSchedule boolean Enable scheduling
scheduleType integer 1-5 for preset times; 6 for custom
timeZone string Required if scheduleType=6 (e.g., GMT 5:30)
scheduleTime string Required if scheduleType=6 (format: MM/DD/YYYY HH:MM:SS)

Reply to Email

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

{
  "fromAddress": "[email protected]",
  "toAddress": "[email protected]",
  "subject": "Re: Original Subject",
  "content": "Reply content"
}

Save Draft

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

{
  "fromAddress": "[email protected]",
  "toAddress": "[email protected]",
  "subject": "Draft Subject",
  "content": "Draft content",
  "mode": "draft"
}

Update Message (Mark as Read/Unread, Move, Flag)

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

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

Mode Options: - markAsRead - Mark messages as read - markAsUnread - Mark messages as unread - moveMessage - Move messages (requires destfolderId) - flag - Set flag (requires flagid: 1-4) - archive - Archive messages - unArchive - Unarchive messages - spam - Mark as spam - notSpam - Mark as not spam

Example - Mark as Read:

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 Email

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

Attachment Operations

Upload Attachment

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

Get Attachment Info

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

Download Attachment

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

Pagination

Zoho Mail uses offset-based pagination:

GET /zoho-mail/api/accounts/{accountId}/messages/view?folderId={folderId}&start=0&limit=50
  • start: Offset index (default: 0)
  • limit: Number of records to return (default: 50)

For subsequent pages, increment start by limit: - Page 1: start=0&limit=50 - Page 2: start=50&limit=50 - Page 3: start=100&limit=50

Code Examples

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()

Notes

  • Account IDs are required for most operations - first call /api/accounts to get your account ID
  • Message IDs and Folder IDs are numeric strings
  • The fromAddress must be associated with the authenticated account
  • Default folders include: Inbox, Drafts, Templates, Snoozed, Sent, Spam, Trash, Outbox
  • Supported encodings: Big5, EUC-JP, EUC-KR, GB2312, ISO-2022-JP, ISO-8859-1, KOI8-R, Shift_JIS, US-ASCII, UTF-8, WINDOWS-1251
  • Some operations (labels, folder management, sending) require additional OAuth scopes. If you receive an INVALID_OAUTHSCOPE error, contact Maton support at [email protected] with the specific operations/APIs you need and your use-case
  • IMPORTANT: When using curl commands, use curl -g when URLs contain brackets to disable glob parsing
  • IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments

Error Handling

Status Meaning
400 Missing Zoho Mail connection or invalid request
401 Invalid or missing Maton API key
429 Rate limited
4xx/5xx Passthrough error from Zoho Mail API

Troubleshooting: API Key Issues

  1. Check that the MATON_API_KEY environment variable is set:
echo $MATON_API_KEY
  1. Verify the API key is valid by listing connections:
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

Troubleshooting: Invalid App Name

  1. Ensure your URL path starts with zoho-mail. For example:
  • Correct: https://gateway.maton.ai/zoho-mail/api/accounts
  • Incorrect: https://gateway.maton.ai/api/accounts

Resources

Details

Version
v1.0.4
Downloads
10,694
Stars
2
ClawHub
View on ClawHub

Popular Skills

AgentMail
API-first email platform designed for AI agents. Create and manage dedicated email inboxes, send and receive emails programmatically, and handle email-based workflows with webhooks and real-time events. Use when you need to set up agent email identity, send emails from agents, handle incoming email workflows, or replace traditional email providers like Gmail with agent-friendly infrastructure.
Free Ride - Unlimited free AI
Manages free AI models from OpenRouter for OpenClaw. Automatically ranks models by quality, configures fallbacks for rate-limit handling, and updates openclaw.json. Use when the user mentions free AI, OpenRouter, model switching, rate limits, or wants to reduce AI costs.
Salesforce
Salesforce CRM API integration with managed OAuth. Query records with SOQL, manage sObjects (Contacts, Accounts, Leads, Opportunities), and perform batch operations. Use this skill when users want to interact with Salesforce data. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).