Zoho (Mail & WorkDrive)

Overview

Zoho is built into Pentoggle as a first-class integration, two ways:

• As a login method — users sign into your app with "Sign in with Zoho"
• As a connected account — users (or your business) click "Connect Zoho" so the app can work with their mail and files

Either way, 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's own Zoho account is used, and each user's data stays their own.

When Zoho is the login method, one consent screen covers sign-in and all the app's Zoho permissions together.

What it supports

• Sign in with Zoho — apps can offer Zoho as a login method; the first sign-in shows one consent screen (including any Mail/WorkDrive permissions the app uses), and returning users sign in with a single click
• Business account connection — you (the app owner) can connect a shared business mailbox once in Settings; your app can then send from the company's address, use its configured aliases (e.g. support@ and billing@ on one account), and save files to the company WorkDrive — even from public pages or scheduled jobs where nobody is signed in
• 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

Apps you can build

• Client portal for an accounting or consulting firm — clients log in and download their monthly statements (filed automatically to the firm's WorkDrive with share links); the firm's replies and reminders go out from billing@. Staff sign in with their Zoho accounts
• Order desk for a small D2C brand — a public order-inquiry form emails the customer an instant confirmation from orders@, saves each order, and auto-sends a follow-up from the same address if it isn't handled within a chosen time
• Recruitment tracker for an agency — applicants upload CVs which are filed into the company WorkDrive; interview invites go out from careers@; recruiters sign in with Zoho and manage the pipeline
• Shared-inbox triage board — team members sign in with Zoho and work through the company's support mailbox as a kanban: assign, reply, mark resolved, with an AI summary of each thread
• Quote & proposal generator for a services business — staff fill in job details, the app generates the proposal document, files it to the company WorkDrive, and emails the client a share link from the business address — with a scheduled follow-up if the client hasn't responded
• Personal email assistant — each user connects their own Zoho and gets an AI-summarized view of their inbox, one-click follow-up reminders, and drafted replies sent from their own address

Example prompts

"Users sign in with their Zoho account — that's the only
login method. Show their inbox on the dashboard."

"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
   • You don't need to memorize it — your app's Settings → OAuth Providers → Zoho card shows this URL with a copy button
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

Connecting a business account (optional)

If your app acts as the business itself — sending confirmations from a company address, filing documents in the company WorkDrive — connect a business account once: in the same Settings → OAuth Providers → Zoho card, use the Business account → Connect button and sign in with the shared business mailbox (e.g. [email protected]), not a personal account.

The card shows the connection's health and lets you reconnect or disconnect at any time — Reconnect is also how newly added permissions get granted after your app gains a Zoho feature. Staging and production each hold their own business connection, so testing never touches your production mailbox.

How it works

1. A user clicks Sign in with Zoho or 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"). For sign-in, this same screen also signs the user in — one consent covers everything
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. Returning sign-ins skip the consent screen entirely

Limitations

• 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, and the business account needs one click of Reconnect in Settings
• 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)
• Zoho Mail sending limits apply — email sends count against the user's own Zoho plan (roughly 50/day on free accounts, a few hundred on paid, adjusted by Zoho's reputation algorithm). Zoho Mail is meant for person-to-person email — use it for "send on my behalf" actions, not for your app's notification or bulk email (the platform's built-in email service handles those)
• 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
• Users report signing in twice the first time — expected, one-time. Zoho identifies the user at zoho.com first to discover their home region, then completes login + consent at the regional server (e.g., zoho.in). After the first round trip both sessions exist and future sign-ins are a single click
• 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