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

Gmail integration requires Google OAuth setup. You’ll need to create a Google Cloud project and enable the Gmail API.

Google OAuth Setup

Follow these steps to connect Gmail to Rowboat.

1. Open Google Cloud Console

   Go to Google Cloud Console and make sure you’re logged into the Google account you want to use.

2. Create a New Project

   Go to Create Project

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

   Once created, select the new project in the top project dropdown.

3. Enable Gmail API

   Enable the Gmail API at:

   https://console.cloud.google.com/apis/api/gmail.googleapis.com

   Click Enable

4. Configure OAuth Consent Screen

   Go to OAuth Consent Screen

   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.

   You do NOT need to publish the app — keeping it in Testing mode is fine.

5. Add Test Users

   If your app is in Testing mode, you must add users manually.

   Go to Test Users

   Under Test Users:

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

   Save changes.

6. Create OAuth Client ID

   Go to Credentials

   Click Create Credentials → OAuth Client ID

   Application Type:

   • Select: Universal Windows Platform (UWP)
   • Name: Rowboat Desktop
   • Store ID: test
   • Click Create
7. Copy the Client ID

   After creation, Google will show:

   • Client ID
   • Client Secret

   Copy the Client ID and paste it into Rowboat where prompted.

How It Works

Sync Configuration

The Gmail sync runs automatically with these settings:

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:

# Email Subject

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

---

### From: [e-mail]
**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

{
  "historyId": "123456",
  "last_sync": "2024-01-01T10:00:00.000Z"
}

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

Attachment Handling

Attachments are automatically downloaded and stored:

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

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:

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:

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

Only emails from the last 30 days are synced. To change this, modify LOOKBACK_DAYS in the configuration.

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 - Sync calendar events
• MCP - Model Context Protocol servers