---
title: "OAuth apps for connected mailboxes"
description: "Members can connect a Gmail, Outlook.com, Microsoft 365 or Zoho Mail mailbox with the provider's own sign-in."
url: https://onesend.email/docs/oauth-apps/
---
# OAuth apps for connected mailboxes

Members can connect a Gmail, Outlook.com, Microsoft 365 or Zoho Mail mailbox with the provider's own sign-in. The mailbox then appears under **Connected accounts**: its mail comes into the inbox, read, starred, archive and trash changes go back to the provider, and replies are sent through the provider's API. Turned on for sending, the mailbox is also a sending provider: **Gmail API** (`gmail_api`), **Microsoft Graph** (`microsoft_graph`) or **Zoho Mail API** (`zoho_mail_api`). These are for personal and low-volume sending only; see [Sending limits](#sending-limits).

The **Connect Google**, **Connect Microsoft** and **Connect Zoho** buttons only appear when the operator of the server has registered an OAuth client with that provider and set its client ID and secret. This page explains how. Without a client, any of these mailboxes can still be connected over IMAP and SMTP with an app password (Connected accounts, **Connect with IMAP**).

| Provider | Environment variables | Redirect URI to register |
|---|---|---|
| Google (Gmail, Google Workspace) | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` | `${ONESEND_PUBLIC_URL}/accounts/oauth/callback/gmail` |
| Microsoft (Outlook.com, Microsoft 365) | `MICROSOFT_CLIENT_ID`, `MICROSOFT_CLIENT_SECRET` (or `MICROSOFT_CLIENT_PUBLIC=true` for a public client), optional `MICROSOFT_TENANT` | `${ONESEND_PUBLIC_URL}/accounts/oauth/callback/microsoft` |
| Zoho Mail | `ZOHO_CLIENT_ID`, `ZOHO_CLIENT_SECRET` (or `ZOHO_CLIENT_PUBLIC=true` for a public client), optional `ZOHO_ACCOUNTS_SERVER` | `${ONESEND_PUBLIC_URL}/accounts/oauth/callback/zoho` |

`ONESEND_PUBLIC_URL` must be the address people open the dashboard at, with `https://` (for example `https://mail.example.com`), because the provider sends the browser back there. `GET /v1/accounts/oauth/providers` shows which providers are configured and the exact redirect URI of your server.

Client secrets are read only from the environment (or from a file named in `<NAME>_FILE`, such as `GOOGLE_CLIENT_SECRET_FILE`), never from `onesend.config.json`, and they are redacted from logs and error messages. Setting a client ID without its secret (or the reverse) stops the server at startup with an explanation. On the Cloudflare edition, store the secrets with `wrangler secret put GOOGLE_CLIENT_SECRET` and so on.

**Public clients (no secret).** Microsoft and Zoho also issue clients for installed apps (Microsoft "Mobile and desktop applications", Zoho "Mobile-based Applications"). They are public clients (RFC 6749 §2.1): they have no secret and rely on PKCE, which every OneSend sign-in uses (`S256`). For such a client set `MICROSOFT_CLIENT_PUBLIC=true` (or `ZOHO_CLIENT_PUBLIC=true`, or `microsoftClientPublic` / `zohoClientPublic` in `onesend.config.json`) instead of the secret. The server then sends only `client_id` and the PKCE `code_verifier` to the token endpoint, for the code exchange and for every refresh, and refuses a code exchange without the verifier. Setting the flag and a secret together stops the server at startup, because Microsoft rejects a secret from a public client (AADSTS700025). Google has no such option: its installed-app (Desktop) clients still use their secret. The Mac app uses public clients for its built-in Microsoft and Zoho sign-in; a server reached over the internet should normally keep a confidential **Web** client.

Facts on this page were checked against each provider's documentation on November 8, 2026 (Zoho's page for mobile and desktop apps on November 9, 2026). Providers change their consoles and policies; their documentation wins.

## How the connection works

1. A signed-in member clicks **Connect Google**. The server creates a random `state` and a PKCE verifier (RFC 7636, `S256`), stores them for 10 minutes (the verifier encrypted, the state only as a SHA-256 hash), and sends the browser to the provider.
2. After consent, the provider redirects to `/accounts/oauth/callback/<provider>`. The server accepts the callback only once, only within 10 minutes, and only in a browser signed in as the member who started it, so a link from someone else cannot connect your mailbox to their workspace. It exchanges the code (with the verifier) for tokens.
3. The access and refresh tokens are stored encrypted with the account (AES-256-GCM under `ONESEND_SECRET`) and are never returned by the API. Access tokens are refreshed shortly before they expire; Microsoft's new refresh token replaces the old one each time.
4. If the provider says the grant is no longer valid (`invalid_grant`, Zoho `invalid_code`: the person revoked access, changed their password, or the token expired), the account shows **Reconnect** and syncing and sending through it stop until someone reconnects it. Reconnecting signs in again and keeps the account, its folders and its mail.

People can choose **Only for sending** before connecting. OneSend then asks for the send permission only (Gmail `gmail.send`, Microsoft `Mail.Send`, Zoho `ZohoMail.messages.CREATE`) and reads no mail.

## Scopes

| Provider | Sync and send (default) | Only for sending |
|---|---|---|
| Google | `https://www.googleapis.com/auth/gmail.modify` | `openid`, `email`, `https://www.googleapis.com/auth/gmail.send` |
| Microsoft | `offline_access`, `User.Read`, `Mail.ReadWrite`, `Mail.Send` (delegated, Microsoft Graph) | `offline_access`, `User.Read`, `Mail.Send` |
| Zoho | `ZohoMail.accounts.READ`, `ZohoMail.folders.READ`, `ZohoMail.tags.READ`, `ZohoMail.messages.READ`, `ZohoMail.messages.UPDATE`, `ZohoMail.messages.CREATE` | `ZohoMail.accounts.READ`, `ZohoMail.messages.CREATE` |

`gmail.modify` reads, labels, archives and trashes mail and sends it. It cannot delete mail permanently, and OneSend never does. Trash in OneSend moves mail to the provider's Trash.

## Google

### Verification and the security assessment

Google classifies Gmail scopes (developers.google.com/workspace/gmail/api/auth/scopes):

- `gmail.modify` and `gmail.readonly` are **restricted** scopes. A public app that uses them must pass Google's OAuth app verification for restricted scopes, and because OneSend stores the mail it reads on a server, also a **security assessment** by an assessor Google approves, repeated every year. This takes weeks and has a cost. It applies to anyone running OneSend as a public service (for example a cloud edition where people from any Google account connect their Gmail).
- `gmail.send` is a **sensitive** scope: a public app needs verification but no security assessment.
- `openid` and `email` are not sensitive.

Self-hosters usually do not need any of this:

- **Google Workspace, only your organization:** create the OAuth client in a Google Cloud project of your Workspace organization and set the audience to **Internal**. Only accounts of your organization can connect, and Google does not require verification for internal apps.
- **Personal Gmail accounts you know:** leave the app in **Testing** and add each Gmail address as a test user. Google limits testing apps to a short list of test users, and refresh tokens of apps in Testing with an External audience **expire after 7 days** (Google, "Using OAuth 2.0 to Access Google APIs", refresh token expiration). The account then shows **Reconnect** every week.
- **No OAuth client at all:** connect Gmail over IMAP with an app password (2-Step Verification must be on; see Connected accounts, preset Gmail).

### Steps

1. Open the Google Cloud console (console.cloud.google.com) and create a project, or pick one. For Workspace-only use, create it inside your organization.
2. **APIs & Services → Library**: enable the **Gmail API**.
3. **Google Auth Platform** (formerly OAuth consent screen):
   - **Branding**: app name (for example "OneSend at Example Inc."), support email, and your domain under authorized domains (the domain of `ONESEND_PUBLIC_URL`).
   - **Audience**: **Internal** for Workspace-only use; otherwise **External**, and add test users while the app is in Testing.
   - **Data access**: add the scopes from [Scopes](#scopes): `.../auth/gmail.modify` (and `.../auth/gmail.send`, `openid`, `email` if members will use Only for sending).
4. **Clients → Create client**: application type **Web application**. Under **Authorized redirect URIs** add `https://<your server>/accounts/oauth/callback/gmail` exactly (scheme, host, no trailing slash). No JavaScript origins are needed.
5. Copy the client ID and secret into the server's environment and restart it:

   ```bash
   GOOGLE_CLIENT_ID=1234567890-abc.apps.googleusercontent.com
   GOOGLE_CLIENT_SECRET=GOCSPX-…
   ```

6. In the dashboard, open Connected accounts and click **Connect Google**. On the consent screen, leave every permission ticked: if the Gmail permission is unticked, OneSend stores nothing, revokes the grant and asks you to connect again.

Each Google account can hold at most 100 refresh tokens per OAuth client; connecting the same account many times invalidates the oldest token silently (Google, refresh token limits).

### Sync and push notifications

OneSend polls by default. The first sync lists messages of the sync window (`messages.list`, `after:`), then follows `history.list` from the history ID captured before the listing; if Gmail no longer has that history ID (HTTP 404, usually after about a week without syncing), the window is synced again. Gmail labels become folders and labels in OneSend; UNREAD and STARRED are the read and starred state; a message without INBOX, SPAM or TRASH is archived ("All Mail"). Gmail allows each user 6,000 quota units a minute and downloading one message costs 60, so large first syncs proceed in steps.

Gmail push notifications (`users.watch` to a Cloud Pub/Sub topic, renewed at least every 7 days, with publish rights for `gmail-api-push@system.gserviceaccount.com`) are not used yet; polling is the default.

## Microsoft

### Steps

1. Open the Microsoft Entra admin center (entra.microsoft.com) → **App registrations → New registration**.
2. **Supported account types**:
   - personal Microsoft accounts and work or school accounts: "Accounts in any organizational directory and personal Microsoft accounts" (then `MICROSOFT_TENANT=common`, the default);
   - only Outlook.com and other personal accounts: `MICROSOFT_TENANT=consumers`;
   - only work or school accounts: `MICROSOFT_TENANT=organizations`, or your tenant ID to allow only your own organization.
3. **Redirect URI**: platform **Web**, `https://<your server>/accounts/oauth/callback/microsoft`. (Not "Single-page application": SPA redirect URIs get refresh tokens that expire after 24 hours.)
4. **Certificates & secrets → New client secret**. Copy the secret's **Value** (not its ID). Secrets expire; note the date and rotate before it.
5. **API permissions → Add a permission → Microsoft Graph → Delegated permissions**: `Mail.ReadWrite`, `Mail.Send`, `User.Read` and `offline_access`. Organizations that do not let users consent to apps themselves need an administrator to **Grant admin consent**.
6. Set the environment and restart:

   ```bash
   MICROSOFT_CLIENT_ID=00001111-aaaa-2222-bbbb-3333cccc4444
   MICROSOFT_CLIENT_SECRET=…
   MICROSOFT_TENANT=common
   ```

### Publisher verification

For a multitenant app (people from other organizations connect), Microsoft recommends publisher verification: a Microsoft AI Cloud Partner Program account linked to the app registration, and a publisher domain that is not `*.onmicrosoft.com`. Microsoft notes that since November 2020, where risk-based step-up consent is on, users cannot consent to most multitenant apps registered after November 8, 2020 that are not publisher verified and ask for more than sign-in and basic profile, so an administrator has to consent instead (learn.microsoft.com, "Publisher verification overview"). Apps registered with a personal Microsoft account cannot be publisher verified. A single-tenant registration for your own organization does not need it.

### Sync and change notifications

Each synced folder uses a Microsoft Graph delta query (`/me/mailFolders/{id}/messages/delta`); the delta link is the folder's cursor, and the first round is limited to the sync window. Messages keep their ID when moved (immutable IDs). Folders map by their well-known names (Inbox, Sent Items, Drafts, Deleted Items, Junk Email, Archive); Outlook categories are labels. Read and flagged state, moves to Archive and Deleted Items, and categories go back to Outlook. Sending uses `/me/sendMail` with the MIME message, so threading headers are kept and Exchange saves the message in Sent Items. Microsoft Graph accepts at most 4 MB per request, so messages larger than about 3 MB cannot be sent through Graph; connect the mailbox over SMTP for those.

Graph change notifications (webhooks) are optional and not turned on by default. The connector implements the subscription validation handshake (the `validationToken` is echoed as `text/plain` within 10 seconds) and checks each notification's `clientState`; polling is the default.

## Zoho

### Steps

1. Open the Zoho API Console (api-console.zoho.com, or the console of your data center) → **Add Client → Server-based Applications**.
2. Client name, homepage URL (your `ONESEND_PUBLIC_URL`) and **Authorized Redirect URIs** `https://<your server>/accounts/oauth/callback/zoho`.
3. Copy the client ID and secret.
4. **Settings** of the client: turn on every data center your members' accounts live in (US, EU, India, Australia, Japan, Canada, Saudi Arabia, United Kingdom, …) and choose **use the same OAuth credentials for all data centers**. OneSend uses one secret for every data center. The client ID is the same in all of them.
5. Set the environment and restart:

   ```bash
   ZOHO_CLIENT_ID=1000.ABC…
   ZOHO_CLIENT_SECRET=…
   # where sign-in starts; Zoho sends people to their own data center (default https://accounts.zoho.com)
   ZOHO_ACCOUNTS_SERVER=https://accounts.zoho.eu
   ```

Zoho returns the person's data center on the redirect (`accounts-server`); OneSend accepts only Zoho's own accounts servers and then uses that data center's token and Mail API hosts (for example `accounts.zoho.in` and `mail.zoho.in`), with or without a client secret. The Zoho Mail account ID is found after sign-in (`GET /api/accounts`). Zoho documents PKCE for its OAuth clients; OneSend sends the `S256` challenge and the verifier. For mobile and desktop apps Zoho's documentation (zoho.com/accounts/protocol/oauth/mobile-applications.html, checked November 9, 2026) calls them public clients, says PKCE must be used with them, and that the SHA-256 method is mandatory when the client supports it; it does not say whether the token request of such a client may omit `client_secret`; the server sends the secret when it has one and omits it for a public client.

### Sync

Zoho Mail has no change feed. Each synced folder is listed newest first with a received-time cursor: new mail is downloaded (`originalmessage`), and the read and flagged state of the newest messages is refreshed. Mail deleted at Zoho is noticed at the next full resync. Zoho allows 30 API requests a minute per user (zoho.com/mail/help/adminconsole/rates-and-limits.html), so pages are small and a large first sync takes a while. Zoho archives mail in place, so OneSend shows a virtual **Archive** folder; archiving uses Zoho's archive action. Sending uses the Zoho Mail send API (replies use its reply action). That API takes no raw message, so OneSend's Message-ID and custom headers are not kept by Zoho. Zoho's IMAP and SMTP (presets Zoho Mail) work without an OAuth client.

## Sending limits

The mailbox providers allow a person's own mail, not bulk or marketing mail, and limit daily sending. OneSend treats these connections as personal mailboxes: never used for broadcasts, with a conservative daily cap that you can lower or raise within the provider's terms.

| Provider | Published limits (checked November 8, 2026) | Default daily cap |
|---|---|---|
| Gmail | 500 emails a day, 500 recipients per email (support.google.com/mail/answer/22839) | 500 |
| Google Workspace | 2,000 messages a day per user (500 for trial accounts), 500 recipients per message through the Gmail API, 10,000 recipients a day ("Gmail sending limits in Google Workspace") | 500 (raise to 2,000 for paid Workspace) |
| Microsoft 365 / Exchange Online | 10,000 recipients a day, 30 messages a minute per mailbox ("Exchange Online limits") | 300 |
| Outlook.com | lower and reputation-based for new accounts; 5,000 recipients a day for Microsoft 365 subscribers ("Sending limits in Outlook.com") | 300 |
| Zoho Mail | 50–500 external emails an hour per user (based on reputation), 150 recipients per message on paid plans, 100 on free; no daily figure published | 300 |

## Troubleshooting

| What you see | Cause and fix |
|---|---|
| No Connect buttons, "Sign-in not set up on this server" | The client ID and secret are not set for that provider. Set both and restart (for a public Microsoft or Zoho client: the ID and `MICROSOFT_CLIENT_PUBLIC=true` / `ZOHO_CLIENT_PUBLIC=true`). |
| Microsoft `AADSTS700025` ("Client is public so neither 'client_assertion' nor 'client_secret' should be presented") | The app registration is a public client, but the server sends a secret. Remove `MICROSOFT_CLIENT_SECRET` and set `MICROSOFT_CLIENT_PUBLIC=true`. |
| Microsoft `AADSTS7000218` ("The request body must contain … 'client_assertion' or 'client_secret'") | `MICROSOFT_CLIENT_PUBLIC=true` is set, but the registration does not allow public client flows. Turn on **Allow public client flows** (Authentication) and use the **Mobile and desktop applications** platform, or use a Web client with its secret. |
| Google `redirect_uri_mismatch`, Microsoft `AADSTS50011`, Zoho "Invalid Redirect Uri" | The registered redirect URI differs from `${ONESEND_PUBLIC_URL}/accounts/oauth/callback/<provider>`. Compare them character by character (http vs https, port, trailing slash). |
| "The provider rejected this server's OAuth client" | Wrong client secret, an expired Microsoft secret, or a Zoho client without the person's data center turned on. |
| "Sign in to OneSend in this browser…" | The sign-in was finished in another browser or profile, or the session ended. Start again from the dashboard in the same browser. |
| Google: "Access blocked: app has not completed the Google verification process" | The app is External and in Testing, and this address is not a test user; add it, use an Internal app, or connect over IMAP. |
| Microsoft: "Need admin approval" | The organization requires administrator consent: an administrator grants consent for the app, or uses a single-tenant registration. |
| Account shows **Reconnect** every 7 days (Gmail) | The Google app is External and in Testing. Publish it (and verify it) or use an Internal app. |
| Account shows **Reconnect** | The person revoked access, changed their password (Google), or the refresh token expired. Click Reconnect and sign in again. |

