Inboxorcist

Inboxorcist requires Google OAuth credentials to access your Gmail account. This guide walks you through creating these credentials in Google Cloud Console.

This is a one-time setup that takes approximately 15-30 minutes.

Step 1: Create a Google Cloud Project

Go to the Google Cloud Console
Click the project dropdown at the top of the page
Click New Project
Enter a project name (e.g., "Inboxorcist")
Click Create

Step 2: Enable the Gmail API

In your new project, go to APIs & Services > Library
Search for "Gmail API"
Click on Gmail API
Click Enable

Go to APIs & Services > OAuth consent screen
Select External user type (unless you have a Google Workspace organization)
Click Create

Fill in the required fields:

Field	Value
App name	Inboxorcist
User support email	Your email address
Developer contact email	Your email address

Click Save and Continue

Add Scopes

Click Add or Remove Scopes
Add the following scopes:
- https://www.googleapis.com/auth/gmail.readonly - View email messages
- https://www.googleapis.com/auth/gmail.modify - Modify email messages (for deletion)
Click Update
Click Save and Continue

Add Test Users

While your app is in testing mode, only test users can authenticate:

Click Add Users
Enter your Gmail address
Click Add
Click Save and Continue

Your app will remain in "Testing" mode until you submit it for verification. Test users can still use all features - verification is only needed if you want to allow any Google user to connect.

Step 4: Create OAuth Credentials

Go to APIs & Services > Credentials
Click Create Credentials > OAuth client ID
Select Web application as the application type
Enter a name (e.g., "Inboxorcist Web")

Configure Authorized Redirect URIs

Add the redirect URI based on your deployment:

Deployment	Redirect URI
Local development	`http://localhost:6616/auth/google/callback`
Railway	`https://your-app.up.railway.app/auth/google/callback`
Render	`https://your-app.onrender.com/auth/google/callback`
Fly.io	`https://your-app.fly.dev/auth/google/callback`
Custom domain	`https://api.yourdomain.com/auth/google/callback`

Click Create

Step 5: Copy Your Credentials

After creating the OAuth client, you'll see:

Client ID - Looks like 123456789.apps.googleusercontent.com
Client Secret - Looks like GOCSPX-xxxxxxxxxxxxx

Add these to your .env file:

GOOGLE_CLIENT_ID=123456789.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxx

The OAuth redirect URI is automatically derived from APP_URL. For production deployments with a custom domain, set APP_URL=https://your-domain.com in your .env file.

Verification (Optional)

If you want to allow anyone to use your Inboxorcist instance (not just test users), you'll need to submit your app for verification:

Go to OAuth consent screen
Click Publish App
Follow Google's verification process

Verification requires a privacy policy, terms of service, and can take several weeks. For personal or small-team use, staying in testing mode is sufficient.

Common Redirect URI Patterns

When deploying, ensure your redirect URI matches exactly. Here are common patterns:

# Local development
http://localhost:6616/auth/google/callback

# Docker with different port
http://localhost:8080/auth/google/callback

# Cloud deployment
https://inboxorcist.yourdomain.com/auth/google/callback

# Subdomain for API
https://api.inboxorcist.yourdomain.com/auth/google/callback

The redirect URI must match exactly - including the protocol (http vs https), port number, and path. Mismatches will cause "redirect_uri_mismatch" errors.

Security Notes

Never share your Client Secret publicly
Never commit credentials to version control
The Client ID can be safely exposed in frontend code
OAuth tokens are encrypted at rest using your ENCRYPTION_KEY

Google OAuth Setup