Zoho Mail

---
name: zoho-mail
description: |
  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.
metadata:
  author: maton
  version: "1.0"
  clawdbot:
    emoji: 🧠
    homepage: "https://maton.ai"
    requires:
      env:
        - MATON_API_KEY
---

# 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

```bash
# 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`:

```bash
export MATON_API_KEY="YOUR_API_KEY"
```

### Getting Your API Key

1. Sign in or create an account at [maton.ai](https://maton.ai)
2. Go to [maton.ai/settings](https://maton.ai/settings)
3. Copy your API key

## Connection Management

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

### List Connections

```bash
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

```bash
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

```bash
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

```bash
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:

```bash
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.

```bash
GET /zoho-mail/api/accounts
```

**Example:**

```bash
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

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

### Folder Operations

#### List All Folders

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

**Example:**

```bash
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

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

{
  "folderName": "My Custom Folder"
}
```

#### Rename Folder

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

{
  "folderName": "Renamed Folder"
}
```

#### Delete Folder

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

### Label Operations

#### List Labels

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

**Example:**

```bash
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

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

{
  "labelName": "Important"
}
```

#### Update Label

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

{
  "labelName": "Updated Label"
}
```

#### Delete Label

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

### Email Message Operations

#### List Emails in Folder

```bash
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:**

```bash
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

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

**Query Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `se