Zoho Mail Integration via API

Purpose

This guide explains how to create a Zoho Self Client in the Zoho API Console and use it to generate the OAuth 2.0 refresh token Logsign USO needs to pull Zoho Mail admin audit records and login history via API, for security analytics and forensic purposes.

Zoho Mail is cloud-only and does not offer syslog forwarding for these records, so the API integration described here is the only supported way to bring this data into Logsign.

Prerequisites

The Zoho user who grants consent must be an organization admin who also has a Zoho Mail mailbox in the same organization. An admin account without a Zoho Mail mailbox will authenticate successfully but every request will fail with a USERNAME_NOT_SET error; this is the most common setup mistake with this integration.

You need access to the Zoho API Console (api-console.zoho.<dc>) for your Zoho data center, and your Zoho Mail Organization ID (zoid), found in the Zoho Mail Admin Console under Organization Details / Profile.

Step 1: Identify Your Zoho Data Center

Zoho operates separate, non-interoperable data centers per region. Confirm which one your organization is provisioned on from the domain you use to sign in to Zoho Mail, then map it below. Logsign asks for this as the Region field, and it determines every host used for authentication and API calls.

The ca region uses the zohocloud.ca domain, not zoho.ca. Your accounts host, Mail API host, and refresh token must always belong to the same region.

Step 2: Create a Self Client in the Zoho API Console

1. Sign in to https://api-console.zoho.<dc> (your region's domain from Step 1) with the mailbox-holding admin account.
2. Click Add Client and choose Self Client.
3. Open the client and copy the Client ID and Client Secret from the Client Secret tab. These are entered directly into the Logsign form.

Step 3: Generate a Grant Code and Exchange It for a Refresh Token

1. In the Self Client, open the Generate Code tab.
2. In the Scope field, paste the following (comma-separated, no spaces): 
   ZohoMail.organization.accounts.READ,ZohoMail.organization.audit.READ
3. Set Time Duration to the maximum, 10 minutes, and click Create.

4. Copy the generated grant code immediately and exchange it for a refresh token, using the accounts host for your region:

   curl --location "https://accounts.zoho.<dc>/oauth/v2/token" \
     --header "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "grant_type=authorization_code" \
     --data-urlencode "code={GrantCode}" \
     --data-urlencode "client_id={ClientID}" \
     --data-urlencode "client_secret={ClientSecret}"

5. The response contains a refresh_token field. Copy it; Zoho shows it only once and it does not expire on its own.

If the grant code has already expired (they last only 1-2 minutes) or was already used, the token endpoint still replies with HTTP 200 and a body of {"error":"invalid_code"} rather than an error status. Generate a fresh code and try again immediately.

Step 4: Find Your Organization ID (zoid)

In the Zoho Mail Admin Console, go to Organization Details (or your Profile screen) and copy the numeric Organization ID. This must belong to the same organization as the admin account used for consent in Step 3, or every request will fail with USERNAME_NOT_SET.

Step 5: Configure the Integration in Logsign USO

Add a new Zoho Mail data source in Logsign USO and provide:

Logsign exchanges the refresh token for a short-lived access token automatically (valid ~3600 seconds); no manual renewal is required. If both checkboxes are enabled, Logsign polls the audit activity feed and, separately, all four login history modes (successful login, failed login, successful protocol login, failed protocol login), tracking each as an independent cursor.

Notes and Limits

• Zoho Mail enforces roughly 30 API requests per minute; Logsign paces its own paging requests to stay under this automatically, so no customer-side action is needed.
• Mail admin audit records are retained by Zoho for about 1 year; login history is retained for about 90 days. Data older than that cannot be backfilled.
• A refresh token can be exchanged for at most 10 access tokens per 10 minutes, and a Zoho client/user pair may hold at most 20 live refresh tokens; a 21st consent silently revokes the oldest. If you repeat the consent flow while testing, make sure the last refresh token generated is the one entered into Logsign.
• If polling fails with USERNAME_NOT_SET, the most likely causes are: the zoid entered belongs to a different organization than the consenting account, or the consenting account is an admin without an actual Zoho Mail mailbox. Re-confirm both in the Admin Console.
• This integration does not cover message-level email traffic or spam/filtering decisions; Zoho's SMTP-level mail logs are only available through a partner-only API that is out of scope here. It also does not cover Zoho CRM login history; Zoho tracks that in Zoho Directory, which has no public API (see the separate Zoho CRM integration guide for CRM audit coverage).