How to retrieve mail configuration in Zoho

Retrieving mail configuration in Zoho CRM and Zoho Desk requires calling the appropriate REST endpoint with a valid OAuth access token — the exact path differs depending on which product you're working with.

Why this matters

When building integrations or automations, you often need to inspect how outgoing or incoming mail is set up for an organisation. Whether you're auditing email routing in Zoho CRM or listing support-mailbox configurations in Zoho Desk, knowing the correct endpoint and authentication flow saves significant debugging time. This is especially relevant for teams managing multi-channel support or CRM email sync. *(Note: Beam Help is independent expert support for Zoho — we are not official Zoho support.)*

---

Step-by-step

1. Obtain a valid OAuth access token

Before calling any mail-configuration endpoint, your application must complete the OAuth flow. Start by generating an authorisation URL that includes your clientid, redirecturi, configured scopes, responsetype: code, accesstype: offline, and prompt: consent.^[1]

Step 1a. Direct the user to that authorisation URL. After they approve, Zoho redirects back with a code parameter.

Step 1b. Exchange the authorisation code for tokens by POSTing to the Zoho token URL with granttype: authorizationcode, your clientid, clientsecret, redirecturi, and the received code. A successful response contains an accesstoken, a refreshtoken, an apidomain, and an expires_in value.^[1]

Step 1c. Store the tokenexpiresat timestamp (current Unix time plus expiresin) so your code knows when to refresh. When the token expires, POST to the token URL again using granttype: refreshtoken along with your client credentials to obtain a fresh accesstoken.^[2]

---

2. Retrieve mail configuration in Zoho CRM

Step 2. With a valid access token in hand, issue the following request to the CRM settings endpoint:

GET /settings/mail_config

In Python, using the internal client wrapper, this looks like:

def get_mail_config(self):
    return self.c.request("GET", "/settings/mail_config")

This operation (getmailconfig) falls under the Mail & Social settings category and returns the current mail configuration for the connected CRM organisation.^[6]

---

3. List mail configurations in Zoho Desk

Step 3. For Zoho Desk, the endpoint is different. To retrieve organisation-level mail configurations, send:

GET /api/v1/mailConfigurations

An optional p parameter can be passed for pagination or filtering. In Python:

def list_organizationlevel_mail_configurations(self, p: dict = None):
    return self.c.request("GET", "/api/v1/mailConfigurations", p, None)

This lists all mail configurations set up at the organisation level within Zoho Desk.^[7]

---

4. Handle authentication errors gracefully

Step 4. If either endpoint returns an HTTP 401 status, the access token has expired or been revoked. In that scenario, prompt the user to reconnect their Zoho account and retry the request after obtaining a fresh token.^[4]

---

Common pitfalls

• Wrong data centre (DC). The apidomain returned during token exchange reflects the user's data centre (e.g., zohoapis.eu for EU). Always use the apidomain from the token response rather than hardcoding zohoapis.com, otherwise requests will fail silently or return auth errors.^[1]
• Scope not included. If the OAuth scopes configured at authorisation time do not cover mail/settings access, the API will reject the request. Double-check that your ZOHO_SCOPES configuration includes the relevant mail or settings scope before generating the auth URL.^[1]
• Org ID mismatch. User info returned from https://accounts.zoho.<DC>/oauth/user/info may expose the org ID under different field names (orgid, organizationid, or ZGID) depending on the data centre. Always try multiple field names and fall back gracefully.^[2]
• Token not refreshed before expiry. Comparing the current Unix time against the stored tokenexpiresat value before each API call prevents unnecessary 401 errors mid-workflow.^[2]

---

What to check

• Confirm the correct base URL — verify that requests are being sent to the api_domain returned during token exchange, not a hardcoded domain, to ensure the right data centre is targeted.^[1]
• Validate the access token is current — check that tokenexpiresat is in the future before calling either /settings/mail_config (CRM) or /api/v1/mailConfigurations (Desk), and refresh proactively if needed.^[2]
• Inspect the response payload — confirm the returned JSON contains the expected mail configuration fields; a 401 in the response body signals an auth issue requiring reconnection rather than a data problem.^[4]