---
title: Gmail
description: Connect your Gmail to SurfSense
---

# Gmail OAuth Integration Setup Guide

This guide walks you through setting up a Google OAuth 2.0 integration for SurfSense to connect your Gmail account.

## Step 1: Access the Google Cloud Console

1. Navigate to [Google Cloud Console](https://console.cloud.google.com/)
2. Select an existing project or create a new one

## Step 2: Enable Required APIs

1. Go to **APIs & Services** > **Library**
2. Search for and enable the following APIs:
   - **People API** (required for Google OAuth)
   - **Gmail API** (required for Gmail connector)

![Google Developer Console People API](/docs/connectors/google/google_oauth_people_api.png)

## Step 3: Configure OAuth Consent Screen

1. Go to **APIs & Services** > **OAuth consent screen**
2. Select **External** user type (or Internal if using Google Workspace)
3. Fill in the required information:
   - **App name**: `SurfSense`
   - **User support email**: Your email address
   - **Developer contact information**: Your email address
4. Click **Save and Continue**

![Google Developer Console OAuth consent screen](/docs/connectors/google/google_oauth_screen.png)

### Add Scopes

1. Click **Add or Remove Scopes**
2. Add the following scopes:
   - `https://www.googleapis.com/auth/gmail.readonly` - Read Gmail messages
   - `https://www.googleapis.com/auth/userinfo.email` - View user email address
3. Click **Update** and then **Save and Continue**

## Step 4: Create OAuth Client ID

1. Go to **APIs & Services** > **Credentials**
2. Click **Create Credentials** > **OAuth client ID**
3. Select **Web application** as the application type
4. Enter **Name**: `SurfSense`
5. Under **Authorized redirect URIs**, add:
   ```
   http://localhost:8000/api/v1/auth/google/gmail/connector/callback
   ```
6. Click **Create**

![Google Developer Console OAuth client ID](/docs/connectors/google/google_oauth_client.png)

## Step 5: Get OAuth Credentials

1. After creating the OAuth client, you'll see a dialog with your credentials
2. Copy your **Client ID** and **Client Secret**

<Callout type="warn">
  Never share your client secret publicly.
</Callout>

![Google Developer Console Config](/docs/connectors/google/google_oauth_config.png)

---

## Running SurfSense with Gmail Connector

Add the Google OAuth credentials to your `.env` file (created during [Docker installation](/docs/docker-installation)):

```bash
GOOGLE_OAUTH_CLIENT_ID=your_google_client_id
GOOGLE_OAUTH_CLIENT_SECRET=your_google_client_secret
GOOGLE_GMAIL_REDIRECT_URI=http://localhost:8000/api/v1/auth/google/gmail/connector/callback
```

Then restart the services:

```bash
docker compose up -d
```