Skip to main content
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.comClick Enable
4

Configure OAuth Consent Screen

Go to OAuth Consent ScreenApp 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 UsersUnder Test Users:
  • Click Add Users
  • Add the email address you plan to connect with Rowboat
Save changes.
6

Create OAuth Client ID

Go to CredentialsClick Create Credentials → OAuth Client IDApplication 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: [email protected]
**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

LocationDescription
~/rowboat/gmail_sync/{threadId}.mdThread conversations
~/rowboat/gmail_sync/attachments/Email attachments
~/rowboat/gmail_sync/sync_state.jsonSync 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

Build docs developers (and LLMs) love

Get started for freeTalk to us