zohomail

# 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 | |-----------|------|-------------| | `searchKey` | string | Search query | | `limit` | integer | Number of results to return | | `start` | integer | Offset for pagination | **Example:** ```bash 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 ```bash GET /zoho-mail/api/accounts/{accountId}/folders/{folderId}/messages/{messageId}/content ``` **Example:** ```bash 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')