Can I use Zoho Mail as a CLI?

Yes. KosmoKrator exposes a Zoho Mail CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Zoho Mail through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Zoho Mail tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Zoho Mail credentials stored?

Zoho Mail credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Zoho Mail MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

productivity

Zoho Mail Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Zoho Mail KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.zoho_mail.*. Use lua_read_doc("integrations.zoho-mail") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Zoho Mail workflow without starting an interactive agent session.

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.zoho_mail.list_accounts({}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("zoho-mail"))' --json
kosmo integrations:lua --eval 'print(docs.read("zoho-mail.list_accounts"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua

local zoho_mail = app.integrations.zoho_mail
local result = zoho_mail.list_accounts({})

dump(result)

Run the workflow

kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json

Namespace note. integrations:lua exposes app.integrations.zoho_mail, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.zoho_mail.default.* or app.integrations.zoho_mail.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Zoho Mail, use the narrower mcp:lua command.

MCP Lua command

# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Zoho Mail Lua API Reference

Namespace: app.integrations["zoho-mail"]

Configure a Zoho OAuth access_token and the regional Mail API base URL. The default is https://mail.zoho.com/api; use the matching regional host such as https://mail.zoho.eu/api when required.

Accounts

local accounts = app.integrations["zoho-mail"].get_current_user({})
local account = app.integrations["zoho-mail"].get_account({
  accountId = "12345678"
})

The returned account IDs are required for every mailbox operation.

Messages

List or search messages:

local page = app.integrations["zoho-mail"].list_messages({
  accountId = "12345678",
  folderId = "987654",
  start = 0,
  limit = 50
})

local search = app.integrations["zoho-mail"].search_messages({
  accountId = "12345678",
  params = {
    searchKey = "from:billing@example.test",
    limit = 20
  }
})

Read content, metadata, headers, and original MIME:

local body = app.integrations["zoho-mail"].get_message({
  accountId = "12345678",
  folderId = "987654",
  messageId = "555555",
  includeBlockContent = false
})

local details = app.integrations["zoho-mail"].get_message_details({
  accountId = "12345678",
  folderId = "987654",
  messageId = "555555"
})

local headers = app.integrations["zoho-mail"].get_message_headers({
  accountId = "12345678",
  folderId = "987654",
  messageId = "555555"
})

local original = app.integrations["zoho-mail"].get_original_message({
  accountId = "12345678",
  messageId = "555555"
})

Send, reply, update, or delete:

app.integrations["zoho-mail"].send_message({
  accountId = "12345678",
  toAddress = "recipient@example.test",
  subject = "Status update",
  content = "<p>All set.</p>",
  mailFormat = "html"
})

app.integrations["zoho-mail"].reply_message({
  accountId = "12345678",
  messageId = "555555",
  payload = {
    toAddress = "sender@example.test",
    content = "<p>Thanks.</p>"
  }
})

app.integrations["zoho-mail"].update_messages({
  accountId = "12345678",
  payload = {
    mode = "markAsRead",
    messageId = { "555555" }
  }
})

app.integrations["zoho-mail"].delete_message({
  accountId = "12345678",
  folderId = "987654",
  messageId = "555555"
})

Attachments

local info = app.integrations["zoho-mail"].get_attachment_info({
  accountId = "12345678",
  folderId = "987654",
  messageId = "555555"
})

local attachment = app.integrations["zoho-mail"].get_attachment_content({
  accountId = "12345678",
  folderId = "987654",
  messageId = "555555",
  attachmentId = "att-123"
})

Folders

local folders = app.integrations["zoho-mail"].list_folders({
  accountId = "12345678"
})

local folder = app.integrations["zoho-mail"].get_folder({
  accountId = "12345678",
  folderId = "987654"
})

app.integrations["zoho-mail"].create_folder({
  accountId = "12345678",
  payload = { folderName = "Invoices" }
})

app.integrations["zoho-mail"].update_folder({
  accountId = "12345678",
  folderId = "987654",
  payload = { mode = "renameFolder", folderName = "Receipts" }
})

Labels

local labels = app.integrations["zoho-mail"].list_labels({
  accountId = "12345678"
})

app.integrations["zoho-mail"].create_label({
  accountId = "12345678",
  payload = { labelName = "Follow up", color = "#3366cc" }
})

Tasks

local tasks = app.integrations["zoho-mail"].list_tasks({
  accountId = "12345678",
  limit = 20
})

Raw API Helpers

Use raw helpers for documented Zoho Mail endpoints that do not yet have a named tool. Paths must be relative; full URLs and parent-directory segments are rejected.

local raw = app.integrations["zoho-mail"].api_get({
  path = "/accounts/12345678/folders"
})

local posted = app.integrations["zoho-mail"].api_post({
  path = "/accounts/12345678/labels",
  payload = { labelName = "Review" }
})

Multi-Account Usage

app.integrations["zoho-mail"].list_messages({ accountId = "12345678" })
app.integrations["zoho-mail"].work.list_messages({ accountId = "12345678" })

Raw agent markdown

# Zoho Mail Lua API Reference

Namespace: `app.integrations["zoho-mail"]`

Configure a Zoho OAuth `access_token` and the regional Mail API base URL. The
default is `https://mail.zoho.com/api`; use the matching regional host such as
`https://mail.zoho.eu/api` when required.

## Accounts

```lua
local accounts = app.integrations["zoho-mail"].get_current_user({})
local account = app.integrations["zoho-mail"].get_account({
  accountId = "12345678"
})
```

The returned account IDs are required for every mailbox operation.

## Messages

List or search messages:

```lua
local page = app.integrations["zoho-mail"].list_messages({
  accountId = "12345678",
  folderId = "987654",
  start = 0,
  limit = 50
})

local search = app.integrations["zoho-mail"].search_messages({
  accountId = "12345678",
  params = {
    searchKey = "from:billing@example.test",
    limit = 20
  }
})
```

Read content, metadata, headers, and original MIME:

```lua
local body = app.integrations["zoho-mail"].get_message({
  accountId = "12345678",
  folderId = "987654",
  messageId = "555555",
  includeBlockContent = false
})

local details = app.integrations["zoho-mail"].get_message_details({
  accountId = "12345678",
  folderId = "987654",
  messageId = "555555"
})

local headers = app.integrations["zoho-mail"].get_message_headers({
  accountId = "12345678",
  folderId = "987654",
  messageId = "555555"
})

local original = app.integrations["zoho-mail"].get_original_message({
  accountId = "12345678",
  messageId = "555555"
})
```

Send, reply, update, or delete:

```lua
app.integrations["zoho-mail"].send_message({
  accountId = "12345678",
  toAddress = "recipient@example.test",
  subject = "Status update",
  content = "<p>All set.</p>",
  mailFormat = "html"
})

app.integrations["zoho-mail"].reply_message({
  accountId = "12345678",
  messageId = "555555",
  payload = {
    toAddress = "sender@example.test",
    content = "<p>Thanks.</p>"
  }
})

app.integrations["zoho-mail"].update_messages({
  accountId = "12345678",
  payload = {
    mode = "markAsRead",
    messageId = { "555555" }
  }
})

app.integrations["zoho-mail"].delete_message({
  accountId = "12345678",
  folderId = "987654",
  messageId = "555555"
})
```

## Attachments

```lua
local info = app.integrations["zoho-mail"].get_attachment_info({
  accountId = "12345678",
  folderId = "987654",
  messageId = "555555"
})

local attachment = app.integrations["zoho-mail"].get_attachment_content({
  accountId = "12345678",
  folderId = "987654",
  messageId = "555555",
  attachmentId = "att-123"
})
```

## Folders

```lua
local folders = app.integrations["zoho-mail"].list_folders({
  accountId = "12345678"
})

local folder = app.integrations["zoho-mail"].get_folder({
  accountId = "12345678",
  folderId = "987654"
})

app.integrations["zoho-mail"].create_folder({
  accountId = "12345678",
  payload = { folderName = "Invoices" }
})

app.integrations["zoho-mail"].update_folder({
  accountId = "12345678",
  folderId = "987654",
  payload = { mode = "renameFolder", folderName = "Receipts" }
})
```

## Labels

```lua
local labels = app.integrations["zoho-mail"].list_labels({
  accountId = "12345678"
})

app.integrations["zoho-mail"].create_label({
  accountId = "12345678",
  payload = { labelName = "Follow up", color = "#3366cc" }
})
```

## Tasks

```lua
local tasks = app.integrations["zoho-mail"].list_tasks({
  accountId = "12345678",
  limit = 20
})
```

## Raw API Helpers

Use raw helpers for documented Zoho Mail endpoints that do not yet have a named
tool. Paths must be relative; full URLs and parent-directory segments are
rejected.

```lua
local raw = app.integrations["zoho-mail"].api_get({
  path = "/accounts/12345678/folders"
})

local posted = app.integrations["zoho-mail"].api_post({
  path = "/accounts/12345678/labels",
  payload = { labelName = "Review" }
})
```

## Multi-Account Usage

```lua
app.integrations["zoho-mail"].list_messages({ accountId = "12345678" })
app.integrations["zoho-mail"].work.list_messages({ accountId = "12345678" })
```

Metadata-derived Lua example

local result = app.integrations.zoho_mail.list_accounts({})
print(result)

Functions

list_accounts Read

Get the current user's Zoho Mail account information. Returns account IDs needed for other Zoho Mail operations.

Lua path: app.integrations.zoho_mail.list_accounts
Full name: zoho-mail.zohomail_get_current_user

Parameter	Type	Required	Description
No parameters.

get_account Read

Get details for a specific Zoho Mail account.

Lua path: app.integrations.zoho_mail.get_account
Full name: zoho-mail.zohomail_get_account

Parameter	Type	Required	Description
`accountId`	string	yes	Zoho Mail account ID.

list_messages Read

List email messages in a Zoho Mail folder. Returns message summaries including sender, subject, and date.

Lua path: app.integrations.zoho_mail.list_messages
Full name: zoho-mail.zohomail_list_messages

Parameter	Type	Required	Description
`accountId`	string	yes	The Zoho Mail account ID.
`folderId`	string	no	Folder ID to list messages from (default: Inbox).
`start`	integer	no	Offset for pagination (default: 0).
`limit`	integer	no	Maximum number of messages to return (default: 20, max: 100).
`searchKey`	string	no	Search query to filter messages.

search_messages Read

Search messages in a Zoho Mail account using official search parameters.

Lua path: app.integrations.zoho_mail.search_messages
Full name: zoho-mail.zohomail_search_messages

Parameter	Type	Required	Description
`accountId`	string	yes	Zoho Mail account ID.
`params`	object	no	Zoho Mail message search query parameters.

get_message_content Read

Get a single email message from Zoho Mail by ID. Returns full message content, headers, and attachment info.

Lua path: app.integrations.zoho_mail.get_message_content
Full name: zoho-mail.zohomail_get_message

Parameter	Type	Required	Description
`accountId`	string	yes	The Zoho Mail account ID.
`folderId`	string	yes	The folder ID containing the message.
`messageId`	string	yes	The message ID to retrieve.
`includeBlockContent`	boolean	no	Whether to include quoted block content.

get_message_details Read

Get metadata details for a Zoho Mail message.

Lua path: app.integrations.zoho_mail.get_message_details
Full name: zoho-mail.zohomail_get_message_details

Parameter	Type	Required	Description
No parameters.

get_message_headers Read

Get email headers for a Zoho Mail message.

Lua path: app.integrations.zoho_mail.get_message_headers
Full name: zoho-mail.zohomail_get_message_headers

Parameter	Type	Required	Description
`accountId`	string	yes	Zoho Mail account ID.
`folderId`	string	yes	Folder ID.
`messageId`	string	yes	Message ID.

get_original_message Read

Get the original MIME representation of a Zoho Mail message.

Lua path: app.integrations.zoho_mail.get_original_message
Full name: zoho-mail.zohomail_get_original_message

Parameter	Type	Required	Description
`accountId`	string	yes	Zoho Mail account ID.
`messageId`	string	yes	Message ID.

get_attachment_info Read

Get attachment metadata for a Zoho Mail message.

Lua path: app.integrations.zoho_mail.get_attachment_info
Full name: zoho-mail.zohomail_get_attachment_info

Parameter	Type	Required	Description
`accountId`	string	yes	Zoho Mail account ID.
`folderId`	string	yes	Folder ID.
`messageId`	string	yes	Message ID.

get_attachment_content Read

Get attachment content for a Zoho Mail message.

Lua path: app.integrations.zoho_mail.get_attachment_content
Full name: zoho-mail.zohomail_get_attachment_content

Parameter	Type	Required	Description
`accountId`	string	yes	Zoho Mail account ID.
`folderId`	string	yes	Folder ID.
`messageId`	string	yes	Message ID.
`attachmentId`	string	yes	Attachment ID.

send_message Write

Send a new email message via Zoho Mail. Supports to, cc, bcc, subject, and HTML or plain text content.

Lua path: app.integrations.zoho_mail.send_message
Full name: zoho-mail.zohomail_send_message

Parameter	Type	Required	Description
`accountId`	string	yes	The Zoho Mail account ID to send from.
`toAddress`	string	yes	Recipient email address(es), comma-separated.
`subject`	string	yes	Email subject line.
`content`	string	yes	Email body content (HTML or plain text).
`ccAddress`	string	no	CC recipients, comma-separated.
`bccAddress`	string	no	BCC recipients, comma-separated.
`inReplyTo`	string	no	Message ID to reply to (for threading).
`mailFormat`	string	no	Format of the content: "html" or "plaintext" (default: "html").

reply_message Write

Reply to an existing Zoho Mail message.

Lua path: app.integrations.zoho_mail.reply_message
Full name: zoho-mail.zohomail_reply_message

Parameter	Type	Required	Description
`accountId`	string	yes	Zoho Mail account ID.
`messageId`	string	yes	Message ID to reply to.
`payload`	object	yes	Reply payload accepted by Zoho Mail.

update_messages Write

Update messages with an official Zoho Mail updatemessage payload, including read/unread, move, flag, labels, archive, or spam modes.

Lua path: app.integrations.zoho_mail.update_messages
Full name: zoho-mail.zohomail_update_messages

Parameter	Type	Required	Description
`accountId`	string	yes	Zoho Mail account ID.
`payload`	object	yes	Update payload including mode and messageId or threadId arrays.

delete_message Write

Delete a Zoho Mail message by account, folder, and message ID.

Lua path: app.integrations.zoho_mail.delete_message
Full name: zoho-mail.zohomail_delete_message

Parameter	Type	Required	Description
`accountId`	string	yes	Zoho Mail account ID.
`folderId`	string	yes	Folder ID.
`messageId`	string	yes	Message ID.

list_folders Read

List all email folders in a Zoho Mail account, including Inbox, Sent, Drafts, Trash, and custom folders.

Lua path: app.integrations.zoho_mail.list_folders
Full name: zoho-mail.zohomail_list_folders

Parameter	Type	Required	Description
`accountId`	string	yes	The Zoho Mail account ID.

get_folder Read

Get one Zoho Mail folder by ID.

Lua path: app.integrations.zoho_mail.get_folder
Full name: zoho-mail.zohomail_get_folder

Parameter	Type	Required	Description
`accountId`	string	yes	Account ID.
`folderId`	string	yes	Folder ID.

create_folder Write

Create a Zoho Mail folder.

Lua path: app.integrations.zoho_mail.create_folder
Full name: zoho-mail.zohomail_create_folder

Parameter	Type	Required	Description
`accountId`	string	yes	Account ID.
`payload`	object	yes	Folder creation payload.

update_folder Write

Update, rename, move, empty, or toggle IMAP for a Zoho Mail folder.

Lua path: app.integrations.zoho_mail.update_folder
Full name: zoho-mail.zohomail_update_folder

Parameter	Type	Required	Description
`accountId`	string	yes	Account ID.
`folderId`	string	yes	Folder ID.
`payload`	object	yes	Folder update payload.

delete_folder Write

Delete a Zoho Mail folder by ID.

Lua path: app.integrations.zoho_mail.delete_folder
Full name: zoho-mail.zohomail_delete_folder

Parameter	Type	Required	Description
`accountId`	string	yes	Account ID.
`folderId`	string	yes	Folder ID.

list_labels Read

List labels for a Zoho Mail account.

Lua path: app.integrations.zoho_mail.list_labels
Full name: zoho-mail.zohomail_list_labels

Parameter	Type	Required	Description
`accountId`	string	yes	Zoho Mail account ID.

get_label Read

Get a Zoho Mail label by ID.

Lua path: app.integrations.zoho_mail.get_label
Full name: zoho-mail.zohomail_get_label

Parameter	Type	Required	Description
`accountId`	string	yes	Account ID.
`labelId`	string	yes	Label ID.

create_label Write

Create a Zoho Mail label.

Lua path: app.integrations.zoho_mail.create_label
Full name: zoho-mail.zohomail_create_label

Parameter	Type	Required	Description
`accountId`	string	yes	Account ID.
`payload`	object	yes	Label creation payload.

update_label Write

Update a Zoho Mail label.

Lua path: app.integrations.zoho_mail.update_label
Full name: zoho-mail.zohomail_update_label

Parameter	Type	Required	Description
`accountId`	string	yes	Account ID.
`labelId`	string	yes	Label ID.
`payload`	object	yes	Label update payload.

delete_label Write

Delete a Zoho Mail label.

Lua path: app.integrations.zoho_mail.delete_label
Full name: zoho-mail.zohomail_delete_label

Parameter	Type	Required	Description
`accountId`	string	yes	Account ID.
`labelId`	string	yes	Label ID.

list_tasks Read

List tasks from Zoho Mail. Returns task details including title, status, due date, and priority.

Lua path: app.integrations.zoho_mail.list_tasks
Full name: zoho-mail.zohomail_list_tasks

Parameter	Type	Required	Description
`accountId`	string	yes	The Zoho Mail account ID.
`start`	integer	no	Offset for pagination (default: 0).
`limit`	integer	no	Maximum number of tasks to return (default: 20).

api_get Read

Call a safe relative Zoho Mail API path with GET.

Lua path: app.integrations.zoho_mail.api_get
Full name: zoho-mail.zohomail_api_get

Parameter	Type	Required	Description
`path`	string	yes	Relative API path.
`params`	object	no	Query parameters.

api_post Write

Call a safe relative Zoho Mail API path with POST.

Lua path: app.integrations.zoho_mail.api_post
Full name: zoho-mail.zohomail_api_post

Parameter	Type	Required	Description
`path`	string	yes	Relative API path.
`payload`	object	no	JSON request body.
`params`	object	no	Query parameters.

api_put Write

Call a safe relative Zoho Mail API path with PUT.

Lua path: app.integrations.zoho_mail.api_put
Full name: zoho-mail.zohomail_api_put

Parameter	Type	Required	Description
`path`	string	yes	Relative API path.
`payload`	object	no	JSON request body.
`params`	object	no	Query parameters.

api_delete Write

Call a safe relative Zoho Mail API path with DELETE.

Lua path: app.integrations.zoho_mail.api_delete
Full name: zoho-mail.zohomail_api_delete

Parameter	Type	Required	Description
`path`	string	yes	Relative API path.
`params`	object	no	Query parameters.