How to connect Zoho Mail to Composio

Composio connects AI agents to Zoho Mail so they can work with mail accounts, messages and folders using the permissions you approve.

We recommend using your own Zoho OAuth app so you can manage its identity and OAuth credentials directly in the Zoho API Console. You need an existing Zoho Mail account.

Part 1: Register your Zoho OAuth app

Step 1: Create a Server-based Application

1. Open Zoho API Console and sign in. Select Get Started, or Add Client if you already have an app.

2. Choose Server-based Application and select Create Now. This is the authorization-code flow used by this guide. Zoho client registration.

Step 2: Enter your app details

1. Enter a Client Name and your application’s Homepage URL.

Use your own product name. Zoho rejects client names containing ZOHO.

2. Under Authorized Redirect URIs, enter the exact Composio callback:

https://backend.composio.dev/api/v1/auth-apps/add

3. Select Create. Open the app’s Client Secret tab and save its Client ID and Client Secret privately for Composio.

Step 3: Choose permissions for your workflow

Choose the Zoho Mail scopes needed by the tools you plan to use. The account-listing example needs ZohoMail.accounts.READ. Reading messages requires ZohoMail.messages.READ, while sending messages requires ZohoMail.messages.CREATE. Add permissions according to your workflow rather than requesting full access by default. Account-listing scope; Mail API scope reference.

Part 2: Connect Zoho Mail in Composio

Step 1: Create an auth config

1. In the Composio dashboard, open Auth Configs → Create. Search for Zoho Mail, select the toolkit, enter a config name and continue.

2. Choose OAuth 2.0 and Your Own Credentials. Enter your Zoho app’s Client id and Client secret.

3. Keep Redirect URI identical to the URL registered in Zoho. Enter the scopes your workflow needs and select Create Auth Config. Zoho requires scope names in the authorization request; an empty default does not mean no permission is needed.

If a scope is not listed, type its exact name into the scope picker and select Add scope.

Step 2: Select the account’s data center

Open the auth config and select Connect Account. When Composio asks for Domain Extension, use the code for the account’s Zoho Mail data center:

Check the domain in your Zoho Mail browser address. If your app serves users in data centers other than the one where it was registered, configure Zoho’s multi-DC support. Zoho Mail data centers; Multi-DC OAuth setup.

Step 3: Review and authorize access

Sign in to the Zoho Mail account you want to connect. Review the app name and requested permissions. Select Accept only when those permissions match your intended workflow. Composio handles the authorization-code and token exchange.

Select the consent checkbox to enable Accept.

Step 4: Confirm that the connection is Active

Wait for Composio’s successful-connection confirmation. Return to the auth config, open Accounts, and confirm that the account shows Active. The config’s Enabled label alone does not confirm a connected account.

Connection troubleshooting

• Invalid client or region error: check the app’s registration data center, the account’s data center and the Domain Extension used in Composio.

• Invalid scope: use the exact case-sensitive Zoho Mail scope names required for the workflow.

• Redirect mismatch: compare the complete callback in Zoho and Composio, including its path.

If Zoho shows “Client name should not contain ZOHO”, replace the client name with your own product name.