Zoho Mail

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

Reference

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://api.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}

List All Folders

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

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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}

List Labels

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

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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}

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://api.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://api.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://api.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://api.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)
setFlag - Set flag (requires flagid)
applyLabel - Apply labels (requires labelId)
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://api.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

Set Flag on Messages

Flag messages with a color/status indicator.

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

{
  "mode": "setFlag",
  "messageId": ["messageId1", "messageId2"],
  "flagid": "important"
}

Flag ID Options:

Flag ID	Description
`info`	Info flag (blue)
`important`	Important flag (red)
`followup`	Follow-up flag (orange)
`flag_not_set`	Remove flag

Optional Parameters:

threadId - Array of thread IDs (alternative to messageId)
isFolderSpecific - Set to true if using folderId
folderId - Folder ID (required if isFolderSpecific is true)
isArchive - Set to true to include archived emails

Example - Flag as Important:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "mode": "setFlag",
    "messageId": ["1234567890123456789"],
    "flagid": "important",
    "isFolderSpecific": True,
    "folderId": "9876543210987654321"
}).encode()
req = urllib.request.Request('https://api.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

Apply Label to Messages

Apply one or more labels to messages or threads.

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

{
  "mode": "applyLabel",
  "messageId": ["messageId1"],
  "labelId": ["labelId1", "labelId2"]
}

Required Parameters:

mode - Must be "applyLabel"
messageId or threadId - Array of message/thread IDs
labelId - Array of label IDs to apply

Optional Parameters:

isFolderSpecific - Set to true if using folderId
folderId - Folder ID (required if isFolderSpecific is true)
isArchive - Set to true to include archived emails

Example - Apply Labels:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "mode": "applyLabel",
    "messageId": ["1234567890123456789"],
    "labelId": ["111222333444555666", "777888999000111222"],
    "isFolderSpecific": True,
    "folderId": "9876543210987654321"
}).encode()
req = urllib.request.Request('https://api.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

Note: Get label IDs by calling GET /zoho-mail/api/accounts/{accountId}/labels first.

Delete Email

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

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}

Zoho Mail

Reference

Get All Accounts

Get Account Details

List All Folders

Create Folder

Rename Folder

Delete Folder

List Labels

Create Label

Update Label

Delete Label

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)

Set Flag on Messages

Apply Label to Messages

Delete Email

Upload Attachment

Get Attachment Info

Download Attachment

Resources

On this page