Your Gmail. Your OAuth credentials.

Bring Your Own OAuth

MailRoutine Cloud currently uses Bring Your Own OAuth (BYO OAuth) to connect Gmail. Every user must create their own Google OAuth client ID and client secret, then save both in the app for their own MailRoutine account.

Signing in to MailRoutine and authorizing Gmail access are separate steps. Your OAuth client identifies your Google integration; Google's consent flow grants MailRoutine permission to work with your Gmail account. Creating and saving credentials alone does not authorize mailbox access.

Set up OAuth for your user

Complete these steps for your own MailRoutine account. Each user supplies their own credentials.

1. Create a Google Cloud project

   Open Google Cloud Console, create or select a project you control, and enable the Gmail API for that project.

2. Configure the OAuth consent screen

   In Google Auth platform, configure the app name, support email and audience for your personal OAuth app. Do not manually add the gmail.modify scope in the Data Access / consent-screen scope list for this setup. MailRoutine requests the Gmail permissions it needs when you connect your account.

3. Publish your OAuth app

   Open Google Auth platform → Audience, select Publish app, and confirm that the publishing status is In production. Complete this step before connecting Gmail. Leaving an external OAuth app in Testing makes its Gmail refresh token expire after seven days, requiring you to reauthorize Gmail every seven days. Publishing removes this Testing-mode expiry; it does not mean your app is Google-verified.

4. Create a web OAuth client

   In Google Auth platform → Clients, create an OAuth client with the Web application type. Copy the redirect URI displayed by MailRoutine's Gmail connection setup into Google's Authorized redirect URIs exactly, including the scheme, hostname and path. Use the callback shown by the Cloud app when connecting to Cloud.

5. Save your client ID and client secret in MailRoutine

   Sign in to your MailRoutine account and open the Gmail connection / OAuth configuration. Paste the client ID and client secret from your Google project into the corresponding fields and save them in the app. These are your per-user OAuth credentials. Keep the client secret private.

6. Authorize your Gmail account

   Start the Gmail connection flow in MailRoutine, choose the Google account you configured, and review and approve the requested permissions on Google's consent screen. Return to MailRoutine and confirm the Gmail connection is ready before enabling routines.

Google classifies gmail.modify as a restricted scope. Adding it to your declared scopes brings the app into Google's restricted-scope verification workflow unless an exception applies. Personal-use apps may qualify for an exception. MailRoutine still requests Gmail access during authorization; omitting the scope from the console does not remove Google's verification requirements where they apply.

Use In production for ongoing routines. Testing requires Gmail reauthorization every seven days. If you already connected while in Testing, publish your OAuth app and reconnect Gmail to obtain a new authorization. Publishing does not prevent other causes of token expiry or revocation.

How your credentials are protected

OAuth credentials saved in the app are protected by double encryption. The key hierarchy wraps the per-user key with the master key, then wraps the master key with the MasterKeyEncryptor.

Open-source documentation

The OSS OAuth guide covers Google project configuration, Gmail permissions and testing restrictions. Self-hosted deployment uses its own environment configuration and redirect URI; follow the Cloud steps above to store credentials per user in the hosted app.

Manage your connection

You can revoke Gmail access from your Google Account permissions. After changing your OAuth credentials in Google, update the saved credentials in MailRoutine and reconnect Gmail as needed.