How do I install the Zoho Mail skill?

Run npx skillmds@latest add craftos-dev/zoho-mail in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Zoho Mail skill do?

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. It is listed under Integrations & APIs on SkillMD.

Is Zoho Mail safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Zoho Mail?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Zoho Mail free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Zoho Mail?

craftos-dev (@craftos-dev) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Zoho Mail by craftos-dev — Agent Skill

Name: Zoho Mail
Author: craftos-dev

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

Sign in or create an account at maton.ai
Go to maton.ai/settings
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:

{
  "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:

{
  "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: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 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": "sender@yourdomain.com",
  "toAddress": "recipient@example.com",
  "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": "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

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": "sender@yourdomain.com",
  "toAddress": "recipient@example.com",
  "subject": "Re: Original Subject",
  "content": "Reply content"
}

Save Draft

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

{
  "fromAddress": "sender@yourdomain.com",
  "toAddress": "recipient@example.com",
  "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 support@maton.ai 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

Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

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

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

Zoho Mail

File contents

Zoho Mail

Quick Start

Base URL

Authentication

Getting Your API Key

Connection Management

List Connections

Create Connection

Get Connection

Delete Connection

Specifying Connection

API Reference

Account Operations

Get All Accounts

Get Account Details

Folder Operations

List All Folders

Create Folder

Rename Folder

Delete Folder

Label Operations

List Labels

Create Label

Update Label

Delete Label

Email Message Operations

List Emails in Folder

Search Emails

Get Email Content

Get Email Headers

Get Email Metadata

Get Original Message (MIME)

Send Email

Reply to Email

Save Draft

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

Delete Email

Attachment Operations

Upload Attachment

Get Attachment Info

Download Attachment

Pagination

Code Examples

JavaScript

Python

Notes

Error Handling

Troubleshooting: API Key Issues

Troubleshooting: Invalid App Name

Resources

Related skills

Frequently asked questions

How do I install the Zoho Mail skill?

What does the Zoho Mail skill do?

Is Zoho Mail safe to use?

Which AI agents work with Zoho Mail?

Is Zoho Mail free to use?

Who published Zoho Mail?