97 lines
3.0 KiB
Markdown
97 lines
3.0 KiB
Markdown
---
|
|
id: gmail-oauth-setup
|
|
title: Gmail OAuth Setup
|
|
description: Step-by-step Google Cloud setup for JobOps Gmail tracking, with exact scopes and callback configuration.
|
|
sidebar_position: 2
|
|
---
|
|
|
|
## What it is
|
|
|
|
This guide configures Google OAuth so JobOps can read recruitment emails from Gmail for the Tracking Inbox.
|
|
|
|
## Why it exists
|
|
|
|
Gmail OAuth setup is easy to misconfigure (wrong redirect URI, missing refresh token, or unnecessary scopes). This page documents the exact defaults JobOps expects.
|
|
|
|
## How to use it
|
|
|
|
### 1) Create Google Cloud credentials
|
|
|
|
In [Google Cloud Console](https://console.cloud.google.com/):
|
|
|
|
1. Create (or select) a project.
|
|
2. Open **APIs & Services → Library** and enable **Gmail API**.
|
|
3. Open **APIs & Services → OAuth consent screen** and configure your app.
|
|
4. Open **APIs & Services → Credentials** and create **OAuth client ID**.
|
|
5. Choose **Web application**.
|
|
6. Add at least one authorized redirect URI:
|
|
- Local: `http://localhost:3005/oauth/gmail/callback`
|
|
- Production: `https://your-domain.com/oauth/gmail/callback`
|
|
|
|
Notes:
|
|
|
|
- If you set `GMAIL_OAUTH_REDIRECT_URI`, it must exactly match a redirect URI in Google Cloud.
|
|
- JobOps does not require JavaScript origins for this flow.
|
|
|
|
### 2) Set environment variables
|
|
|
|
Configure:
|
|
|
|
```bash
|
|
GMAIL_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
|
|
GMAIL_OAUTH_CLIENT_SECRET=your-client-secret
|
|
# Optional (recommended in production)
|
|
GMAIL_OAUTH_REDIRECT_URI=https://your-domain.com/oauth/gmail/callback
|
|
```
|
|
|
|
Then restart the container/app.
|
|
|
|
### 3) Connect Gmail in JobOps
|
|
|
|
1. Open **Tracking Inbox**.
|
|
2. Click **Connect Gmail**.
|
|
3. Complete Google consent.
|
|
|
|
JobOps starts OAuth with:
|
|
|
|
- Scope: `https://www.googleapis.com/auth/gmail.readonly`
|
|
- `access_type=offline` (requests refresh token)
|
|
- `prompt=consent` (forces consent screen so refresh token is returned reliably)
|
|
|
|
### 4) Scope reference (required vs not required)
|
|
|
|
Required by JobOps:
|
|
|
|
- `https://www.googleapis.com/auth/gmail.readonly`
|
|
|
|
Not required for JobOps Gmail ingestion:
|
|
|
|
- `https://www.googleapis.com/auth/gmail.modify`
|
|
- `openid`
|
|
- `https://www.googleapis.com/auth/userinfo.email`
|
|
- `https://www.googleapis.com/auth/userinfo.profile`
|
|
|
|
## Common problems
|
|
|
|
### Redirect URI mismatch
|
|
|
|
- Symptom: Google returns `redirect_uri_mismatch`.
|
|
- Fix: ensure the exact callback URL in `GMAIL_OAUTH_REDIRECT_URI` is also present in the OAuth client redirect URIs.
|
|
|
|
### No refresh token returned
|
|
|
|
- Symptom: connect fails after OAuth exchange.
|
|
- Fix: remove app access in your Google account, then reconnect so consent is re-granted.
|
|
|
|
### Gmail connects but no inbox results
|
|
|
|
- Check that your account actually has recruitment/application emails.
|
|
- Trigger a sync and increase `searchDays` if needed.
|
|
|
|
## Related pages
|
|
|
|
- [Self-Hosting (Docker Compose)](/docs/next/getting-started/self-hosting)
|
|
- [Post-Application Tracking](/docs/next/features/post-application-tracking)
|
|
- [Post-Application Workflow](/docs/next/workflows/post-application-workflow)
|
|
- [Common Problems](/docs/next/troubleshooting/common-problems)
|