> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/rowboatlabs/rowboat/llms.txt
> Use this file to discover all available pages before exploring further.

# Gmail Integration

> Sync your Gmail threads and attachments to Rowboat

Rowboat automatically syncs your Gmail threads to make your email history searchable and accessible to your AI assistant.

## Overview

The Gmail integration:

* Syncs email threads from the last 30 days
* Saves thread conversations as markdown files
* Downloads and stores email attachments
* Uses incremental sync to only fetch new messages
* Runs automatically every 5 minutes

## Prerequisites

<Info>
  Gmail integration requires Google OAuth setup. You'll need to create a Google Cloud project and enable the Gmail API.
</Info>

## Google OAuth Setup

Follow these steps to connect Gmail to Rowboat.

<Steps>
  <Step title="Open Google Cloud Console">
    Go to [Google Cloud Console](https://console.cloud.google.com/) and make sure you're logged into the Google account you want to use.
  </Step>

  <Step title="Create a New Project">
    Go to [Create Project](https://console.cloud.google.com/projectcreate)

    * Click **Create Project**
    * Give it a name (e.g. `Rowboat Integration`)
    * Click **Create**

    Once created, select the new project in the top project dropdown.
  </Step>

  <Step title="Enable Gmail API">
    Enable the Gmail API at:

    [https://console.cloud.google.com/apis/api/gmail.googleapis.com](https://console.cloud.google.com/apis/api/gmail.googleapis.com)

    Click **Enable**
  </Step>

  <Step title="Configure OAuth Consent Screen">
    Go to [OAuth Consent Screen](https://console.cloud.google.com/auth/branding)

    **App Information:**

    * App name: `Rowboat`
    * User support email: Your email

    **Audience:**

    * Choose **External**

    **Contact Information:**

    * Add your email address

    Click **Save and Continue** through the remaining steps.

    <Note>
      You do NOT need to publish the app — keeping it in **Testing** mode is fine.
    </Note>
  </Step>

  <Step title="Add Test Users">
    If your app is in Testing mode, you must add users manually.

    Go to [Test Users](https://console.cloud.google.com/auth/audience)

    Under **Test Users:**

    * Click **Add Users**
    * Add the email address you plan to connect with Rowboat

    Save changes.
  </Step>

  <Step title="Create OAuth Client ID">
    Go to [Credentials](https://console.cloud.google.com/auth/clients)

    Click **Create Credentials → OAuth Client ID**

    **Application Type:**

    * Select: **Universal Windows Platform (UWP)**
    * Name: `Rowboat Desktop`
    * Store ID: `test`
    * Click **Create**
  </Step>

  <Step title="Copy the Client ID">
    After creation, Google will show:

    * **Client ID**
    * **Client Secret**

    Copy the **Client ID** and paste it into Rowboat where prompted.
  </Step>
</Steps>

## How It Works

### Sync Configuration

The Gmail sync runs automatically with these settings:

```typescript theme={null}
const SYNC_DIR = path.join(WorkDir, 'gmail_sync');
const SYNC_INTERVAL_MS = 5 * 60 * 1000; // Every 5 minutes
const LOOKBACK_DAYS = 30; // Last 30 days
const REQUIRED_SCOPE = 'https://www.googleapis.com/auth/gmail.readonly';
```

### Thread Storage Format

Each Gmail thread is saved as a markdown file:

```markdown theme={null}
# Email Subject

**Thread ID:** abc123xyz
**Message Count:** 3

---

### From: sender@example.com
**Date:** Mon, 1 Jan 2024 10:00:00 GMT

Message body content...

**Attachments:**
- [document.pdf](attachments/abc123_document.pdf)

---
```

### Incremental Sync

Rowboat uses Gmail's History API for efficient syncing:

1. **First Sync**: Fetches all threads from the last 30 days
2. **Subsequent Syncs**: Only fetches new messages using history ID
3. **State Tracking**: Saves history ID to `sync_state.json`

```json theme={null}
{
  "historyId": "123456",
  "last_sync": "2024-01-01T10:00:00.000Z"
}
```

<Warning>
  If the history ID expires (404 error), Rowboat will automatically fall back to a full sync.
</Warning>

## Attachment Handling

Attachments are automatically downloaded and stored:

* **Location**: `~/rowboat/gmail_sync/attachments/`
* **Naming**: `{messageId}_{filename}`
* **Deduplication**: Skips if already downloaded

```typescript theme={null}
const safeName = `${msgId}_${cleanFilename(filename)}`;
const filePath = path.join(attachmentsDir, safeName);

if (!fs.existsSync(filePath)) {
  const data = await gmail.users.messages.attachments.get({
    userId: 'me',
    messageId: msgId,
    id: attachmentId
  });
  fs.writeFileSync(filePath, Buffer.from(data.data, 'base64'));
}
```

## Trigger Manual Sync

You can trigger an immediate sync programmatically:

```typescript theme={null}
import { triggerSync } from './sync_gmail';

triggerSync(); // Wakes up sync immediately
```

## Troubleshooting

### 401 Unauthorized Error

If you see authentication errors, Rowboat will automatically clear the OAuth cache:

```typescript theme={null}
if (response.status === 401) {
  console.log("401 Unauthorized, clearing cache");
  GoogleClientFactory.clearCache();
}
```

You'll need to reconnect your Google account.

### Rate Limiting

Gmail API has rate limits. Rowboat handles this by:

* Syncing every 5 minutes (not more frequently)
* Using incremental sync to minimize API calls
* Caching message data locally

### Missing Emails

<Info>
  Only emails from the last 30 days are synced. To change this, modify `LOOKBACK_DAYS` in the configuration.
</Info>

## Files Synced

| Location | Description |
| - | - |
| `~/rowboat/gmail_sync/{threadId}.md` | Thread conversations |
| `~/rowboat/gmail_sync/attachments/` | Email attachments |
| `~/rowboat/gmail_sync/sync_state.json` | Sync state tracking |

## Privacy & Security

* **Read-Only Access**: Uses `gmail.readonly` scope
* **Local Storage**: All data stored locally on your machine
* **No Cloud Sync**: Emails never sent to external servers
* **OAuth Tokens**: Securely managed by Google's OAuth flow

## Related Integrations

* [Google Calendar](/integrations/google-calendar) - Sync calendar events
* [MCP](/integrations/mcp) - Model Context Protocol servers


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.