Zoho (Mail & WorkDrive)

Overview

Zoho is built into Pentoggle as a first-class integration. Your app can show a "Connect Zoho" button; once a user approves, the app can — always on that user's behalf — send email from their Zoho Mail address, read their inbox, upload files into their Zoho WorkDrive, and create shareable links. Each user connects their own Zoho account, and each user's data stays their own.

What it supports

• Send email as the user — your app can call zoho.sendMail(...) from a function to send HTML or plain-text email from the user's own Zoho Mail address
• Read the user's inbox — zoho.listMessages(...) and zoho.getMessage(...) let the app show recent messages or pull a specific message's content (e.g., an "inbox dashboard" or "process incoming orders" flow)
• Save files to WorkDrive — zoho.uploadFile(...) copies a file from your app's storage into the user's WorkDrive "My Folders"
• Browse and share WorkDrive files — zoho.listFiles(...) lists files; zoho.createShareLink(...) creates a shareable link (viewer, editor, comment, or upload access)
• Automated / scheduled actions — combined with Scheduled tasks, apps can email a report from the user's mailbox or archive a file to WorkDrive at a chosen time
• Token storage and refresh — Pentoggle stores each user's Zoho tokens encrypted and refreshes them automatically in the background. Zoho refresh tokens don't expire, so once a user connects they stay connected until they revoke access
• All Zoho regions — Zoho hosts accounts in different data centers (India, US, EU, Australia, and more). Pentoggle detects each user's home region during connect and talks to the right servers automatically

Example prompts

"Add a 'Connect Zoho' button. When a customer fills the
contact form, email the details from my Zoho Mail account."

"Show my 20 most recent Zoho Mail messages on the dashboard
with an unread indicator."

"After a user generates an invoice PDF, save it to their
Zoho WorkDrive and show them a shareable link."

Setting up Zoho for your app

Zoho requires each app creator to register their own Zoho developer app (a free, five-minute step) so the consent screen is branded as yours and Zoho's limits apply per app.

1. Create a Zoho API Console client
   • Go to api-console.zoho.com and click Get Started (or Add Client)
   • Choose Server-based Applications
   • Fill in your app's name and homepage URL
2. Add the redirect URL
   • Under Authorized Redirect URIs, add exactly: https://pentoggle.com/api/baas/oauth/zoho/callback
   • The URL must be byte-identical — no trailing slash, no http://, no query parameters
3. (If needed) enable other Zoho regions
   • If your users may have Zoho accounts hosted in other regions (e.g., you're in India but have EU users), open the client's Settings tab, enable those data centers, and check "Use the same OAuth credentials for all data centers"
4. Copy your credentials
   • From the Client Secret tab, copy your Client ID and Client Secret
5. Add them in Pentoggle
   • Open your app and go to the Settings tab
   • Find the OAuth Providers section and click on the Zoho card
   • Paste your Client ID and Client Secret, then click Save
   • The status flips from Setup needed to Ready

How it works

1. A user clicks Connect Zoho in your app
2. The browser is redirected to Zoho's consent screen, branded with your Zoho client, listing only the permissions your app actually uses (e.g., "send mail" but not "read files")
3. The user approves; Zoho tells Pentoggle which regional data center hosts the account, and Pentoggle exchanges the code for tokens server-side at that region
4. Your functions call zoho.sendMail(...), zoho.uploadFile(...), etc.; Pentoggle uses the stored token against the user's home region and handles all the Zoho API plumbing (mailbox discovery, folder lookups, refresh) behind the scenes
5. Access tokens are refreshed automatically forever — Zoho refresh tokens don't expire, so users only reconnect if they revoke access from their Zoho account

Limitations

• Connect-only — there is no "Sign in with Zoho". Users sign in to your app with email/password, Google, or LinkedIn, then connect Zoho separately
• The user needs the Zoho product — sending mail requires the connected account to have a Zoho Mail mailbox; WorkDrive features require a WorkDrive team. Personal accounts without these get a clear "not available" error
• Permissions are fixed at connect time — if your app later needs an extra permission (e.g., adds file upload to a mail-only app), users must reconnect once to approve it
• File downloads need share links — WorkDrive files can't be downloaded by the browser directly; use zoho.createShareLink(...) when a user needs a link to open
• Mail attachments — sending attachments with zoho.sendMail is not supported yet (save the file to WorkDrive and include a share link instead)
• Other Zoho products — Zoho CRM, Calendar, and Cliq are not wrapped yet

Troubleshooting

• "redirect_uri does not match" / "Invalid Redirect Uri" — the URL in the Zoho API Console must be exactly https://pentoggle.com/api/baas/oauth/zoho/callback. No trailing slash, no http://, no query string
• Status stays "Setup needed" after saving credentials — re-open the Zoho card; one of the fields may have been pasted with whitespace. Re-paste and save
• A user in another country can't connect — their Zoho account lives in a different data center. Enable that region in your Zoho client's Settings tab and check "Use the same OAuth credentials for all data centers"
• "Zoho Mail is not enabled for this Zoho account" — the connected account has no Zoho Mail mailbox. The user needs a Zoho account with Mail set up (free personal Zoho accounts qualify once Mail is activated)
• "This Zoho account has no WorkDrive team" — WorkDrive's API requires a team workspace. The user needs to open WorkDrive once with their Zoho account so their workspace is created
• Missing-permission error after adding a new feature — the app now uses a Zoho permission the user hasn't approved yet. Ask affected users to reconnect Zoho once