Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | ## How do I set up custom OAuth credentials for Zoho Mail? |
| 2 | |
| 3 | Use your own Zoho OAuth client when you want the consent screen to show your app name and to manage the client credentials yourself. You need an existing Zoho Mail account. |
| 4 | |
| 5 | ### Create the Zoho OAuth client |
| 6 | |
| 7 | 1. Sign in to the [Zoho API Console](https://api-console.zoho.com/). Click **Add Client** (or **Get Started** for your first client). |
| 8 | |
| 9 |  |
| 10 | |
| 11 | 2. Choose **Server-based Applications** and click **Create Now**. See Zoho's [client registration guide](https://www.zoho.com/developer/oauth/register-app.html). |
| 12 | |
| 13 |  |
| 14 | |
| 15 | 3. Enter a **Client Name** and your application's **Homepage URL**. Use your own product name: Zoho rejects client names that contain `ZOHO` with "Client name should not contain ZOHO". |
| 16 | |
| 17 |  |
| 18 | |
| 19 | 4. In **Authorized Redirect URIs**, enter `https://backend.composio.dev/api/v1/auth-apps/add`. It must exactly match the auth config's `oauth_redirect_uri` field. |
| 20 | |
| 21 |  |
| 22 | |
| 23 | 5. Click **Create**, then open the **Client Secret** tab and copy the **Client ID** and **Client Secret**. |
| 24 | |
| 25 |  |
| 26 | |
| 27 | ### Create the auth config in Composio |
| 28 | |
| 29 | 1. In the [Composio dashboard](https://dashboard.composio.dev/~/project/auth-configs?utm_source=docs&utm_medium=content&utm_campaign=toolkits-zoho_mail), go to **Auth Configs** → **Create** and select **Zoho Mail**. |
| 30 | |
| 31 |  |
| 32 | |
| 33 | 2. Choose **OAuth 2.0** and **Your Own Credentials**, then paste the Client ID and Client Secret. Leave **Redirect URI** as the value you registered in Zoho. |
| 34 | |
| 35 | 3. Enter the scopes your workflow needs (see below) and click **Create Auth Config**. To add a scope that isn't listed, type its exact name and click **Add scope**. |
| 36 | |
| 37 |  |
| 38 | |
| 39 | 4. Click **Connect Account** and enter the account's data center code in **Domain Extension** (see the region question below). |
| 40 | |
| 41 |  |
| 42 | |
| 43 |  |
| 44 | |
| 45 | 5. Sign in to Zoho Mail, review the app name and permissions, tick the consent checkbox, and click **Accept**. Then open the auth config's **Accounts** tab and check that the account shows **Active**. The config showing **Enabled** doesn't mean an account is connected. |
| 46 | |
| 47 |  |
| 48 | |
| 49 |  |
| 50 | |
| 51 | See [custom auth configs](/docs/auth-configuration/custom-auth-configs) for the general flow. |
| 52 | |
| 53 | ### Scopes |
| 54 | |
| 55 | The default auth config requests no scopes, but Zoho requires scope names in the authorization request, so add the ones your tools need. Scope names are case-sensitive. Common ones: |
| 56 | |
| 57 | - `ZohoMail.accounts.READ`: list the user's mail accounts |
| 58 | - `ZohoMail.messages.READ`: read messages |
| 59 | - `ZohoMail.messages.CREATE`: send messages |
| 60 | |
| 61 | See the [Zoho Mail API reference](https://www.zoho.com/mail/help/api/) for the scope each operation needs. |
| 62 | |
| 63 | ### Troubleshooting |
| 64 | |
| 65 | - **Invalid client or region error**: check the client's data center, the account's data center, and **Domain Extension**. |
| 66 | - **Invalid scope**: use the exact, case-sensitive Zoho Mail scope names. |
| 67 | - **Redirect mismatch**: compare the full callback URL in Zoho and in Composio, including the path. |
| 68 | |
| 69 | ## What should I pass for the correct Zoho region when connecting Zoho Mail? |
| 70 | |
| 71 | Enter the code from your Zoho Mail web address in **Domain Extension**. Zoho accounts live in one data center, so an EU or other regional account fails if you connect with the default `com`. |
| 72 | |
| 73 | - `mail.zoho.com`: `com` |
| 74 | - `mail.zoho.eu`: `eu` |
| 75 | - `mail.zoho.in`: `in` |
| 76 | - `mail.zoho.com.au`: `au` |
| 77 | - `mail.zohocloud.ca`: `ca` |
| 78 | - `mail.zoho.com.cn`: `cn` |
| 79 | - `mail.zoho.jp`: `jp` |
| 80 | - `mail.zoho.ae`: `ae` |
| 81 | - `mail.zoho.sa`: `sa` |
| 82 | |
| 83 | Enter the code only, not a full URL. If your app connects users in data centers other than the one where you registered the client, enable [multi-DC support](https://www.zoho.com/developer/oauth/web-server-apps/overview.html) in the API Console. See Zoho's [Mail data center list](https://www.zoho.com/mail/help/api/getting-started-with-api.html). |