AI Email

AI-powered email personalization tool with Gmail and Google Sheets integration for Google Workspace organizations.

Features

• Google Cloud Apps Script: Centralized LLM API key management for team-wide use
• Google Workspace Integration: OAuth-based authentication for Gmail and Sheets APIs
• Internal Use Only: Configured for your organization's workspace members
• Smart Navigation: Auto-opens the right tab based on setup completion
• Auto-Save Configuration: All settings save automatically on blur
• Config Tab: Connect Google account, configure sheets, and select LLM model
• Context Tab: Create and edit email templates with variable placeholders
• Email Tab: Generate personalized emails, send to contacts, and track status
• Privacy Protected: Contact data never sent to AI - only your template
• Persistent Storage: Configuration and model selections saved across restarts

Quick Start

For Admins/Developers (One-Time Setup)

Prerequisites:

1. Google Workspace organization
2. Administrative access to deploy a Google Apps Script

Setup Steps:

1. Apps Script Configuration - See APPS_SCRIPT_SETUP.md

   • Deploy the included Google Apps Script
   • Grant it access to your Workspace credentials
   • Distribute the Web App URL to your team members

2. Build and Distribute

   npm install
   npm run electron:build

   • Distribute the packaged app to team members
   • Users will authenticate using the Web App URL on first run

For End Users

Once the app is set up by your admin:

1. Launch the app - It will open on the Configuration tab
2. Connect Google Account:
   • Enter your name and Gmail address (auto-saves on blur)
   • Click "Connect Google Account"
   • Paste the Apps Script Web App URL provided by your admin into the configuration field
   • Authorize in your browser
   • Grant permissions to the application
3. Configure Integration:
   • Paste your Google Sheet URL
   • Test the sheet connection
4. Select LLM Model:
   • Click "Fetch Models" to load available Gemini models
   • Select your preferred model (e.g., gemini-1.5-flash)
   • Settings save automatically
5. Create Template - Navigate to Context tab
   • Write your email template
   • Use {{firstName}} and {{lastName}} placeholders
6. Send Emails - Navigate to Email tab
   • Generate personalized emails with AI
   • Review, edit, and send

The app will remember your settings and automatically open the Email tab on next launch.

See USER_SETUP_GUIDE.md for detailed instructions and troubleshooting.

For Developers

# Install dependencies
npm install

# Run in development mode
npm run electron:dev

# Build for production
npm run electron:build

Architecture

Security Model

• OAuth 2.0: All Google API access via user's OAuth tokens
• Apps Script Config: Secret credentials retrieved through secure script URL
• Encrypted Storage: Configuration stored using electron-store encryption
• Content Security Policy: Strict CSP in production, relaxed for HMR in dev
• Context Isolation: Electron security best practices enabled

See SECURITY.md for detailed security architecture.

Key Components

• Main Process (src/main/):

  • index.ts - Electron app lifecycle and window management
  • configFetcher.ts - Local server to catch Apps Script redirects
  • gmail.ts - Gmail API OAuth and email sending
  • sheets.ts - Google Sheets API integration
  • secrets.ts - Credential storage/retrieval via electron-store
  • preload.ts - Secure IPC bridge

• Renderer Process (src/renderer/):

  • App.tsx - Main app with smart tab navigation
  • components/ConfigTab.tsx - Auto-save configuration UI
  • components/ContextTab.tsx - Template editor
  • components/EmailTab.tsx - Email generation and sending
  • services/llm.ts - LLM API integration (Gemini/OpenAI)

Installation & Setup

For End Users (Download & Run)

1. Download the app:

   • Go to the Releases page: https://github.com/democracy-lab/ai-mail/releases
   • Look for the latest release (e.g., v1.0.0).
   • Download the ai-mail-setup-X.X.X.exe (NSIS Installer) or ai-mail-portable-X.X.X.exe (Run without installing).

2. First-time setup:

   • Launch the app. The "Smart Navigation" will guide you through the initial configuration:
     • User Info: Enter your name and work email.
     • Google Account: Paste the admin-provided Apps Script Web App URL and click connect to securely authenticate your workspace account and pull down required configurations.
     • Google Sheet: Paste the link to your contact spreadsheet.
     • LLM: Select your preferred AI model (Gemini/OpenAI).

3. Secure API Access: The app securely fetches your LLM API Key and internal configuration through a Google Apps Script endpoint authorized by your organization's Workspace account.

For Developers (Local Build)

1. Clone the repository:

   git clone https://github.com/democracy-lab/ai-email.git
   cd ai-email

2. Install dependencies:

   npm install

3. Environment Setup:

   • Follow APPS_SCRIPT_SETUP.md for configuring the environment using Google Apps Script.

4. Run in Development:

   npm run dev

5. Build for Production:

   • On Windows, enable Developer Mode in settings to allow symbolic links.
   • Run: npm run electron:build.

Creating a Release

Releases are built and published automatically via GitHub Actions — no personal access token required.

1. Bump the version in package.json (e.g. 1.0.9 → 1.0.10).

2. Commit and push the version change:

   git add package.json
   git commit -m "chore: bump version to 1.0.10"
   git push

3. Push a version tag — this triggers the release workflow:

   git tag v1.0.10
   git push origin v1.0.10

4. Wait for the Action to complete: Go to the Actions tab and wait for the "Build and Release" workflow to finish. It builds installers for both Windows and macOS.

5. Mark the release as Latest: Go to the Releases page, find the newly created release, click Edit, check Set as the latest release, and save.

Usage Guide (Email Workflow)

1. Configure Settings (Config Tab)

The app validates and auto-saves all settings:

• User Information: Name and Gmail address (validates email format)
• Google Account: OAuth connection with test button
• Google Sheets:
  • Paste full spreadsheet URL (auto-extracts ID)
  • Specify sheet tab name
  • Validates required columns
• LLM Configuration:
  • Fetch available models from API
  • Select model (saves with cached model list)
  • API key managed centrally via Apps Script

Status messages appear inline with each section showing success/error feedback.

2. Create Template (Context Tab)

• Write your email template in the rich text editor
• Use placeholders: {{firstName}}, {{lastName}}
• Template auto-saves as you type
• Placeholders replaced locally after AI generation

Important: Only the template is sent to the LLM. Contact names are filled in afterwards, preserving privacy.

3. Send Emails (Email Tab)

1. Load Contacts: Fetches from Google Sheets via API
2. Generate Email:
   • Sends template to LLM
   • LLM creates personalized email structure
   • Placeholders replaced with contact info
3. Review & Edit: Full rich-text editing before sending
4. Send:
   • Test button sends to yourself
   • Send button uses Gmail API
   • Updates sheet with status and Gmail Message ID
5. Navigate: Previous/Next buttons to process multiple contacts

Google Sheet Structure

Required columns:

• Email Address - Contact's email
• First Name - For {{firstName}} placeholder
• Last Name - For {{lastName}} placeholder

Optional columns (auto-created if missing):

• Team Member - Who sent the email (your name)
• Status - sent/skipped/error
• Date Sent - Timestamp
• Gmail Message ID - For tracking

The app validates column presence and shows clear error messages if sheet structure is incorrect.

Multi-User Support

Multiple team members can use the app simultaneously:

• Each person authenticates with their own Google account
• Shared LLM API key accessed via Apps Script (requires IAM permission)
• App updates "Team Member" column after sending
• Contacts with filled "Team Member" column are skipped
• No conflicts or overwrites between users

Tech Stack

Core

• Electron - Desktop application framework
• React 18 - UI framework
• TypeScript - Type safety throughout
• Vite - Fast build tool with HMR

UI & Styling

• Tailwind CSS - Utility-first styling
• react-quill - Rich text email editor

Google Integration

• googleapis - Gmail and Sheets API clients
• google-auth-library - OAuth 2.0 authentication

Storage & Security

• electron-store - Encrypted local configuration
• Content Security Policy - XSS protection

Development

Web App URL

Require user-provided URL during runtime inside configuration panel to fetch environments and complete setup flows via Google Apps Script.

OAuth Scopes

The app requests these scopes:

• https://www.googleapis.com/auth/gmail.send - Send emails
• https://www.googleapis.com/auth/gmail.readonly - Test connection
• https://www.googleapis.com/auth/spreadsheets - Read/write sheets

CSP Configuration

• Development: Relaxed CSP allows unsafe-eval for Vite HMR
• Production: Strict CSP with no eval, whitelisted API domains
• See SECURITY.md for details

Troubleshooting

Configuration Issues

Google Account won't connect

• Ensure you have correctly pasted your IT Admin's provided Google Apps Script URL.
• Verify OAuth consent screen is set to "Internal"
• Ensure you're signed in with a workspace account (not free Gmail)
• Ensure user is part of your Google Workspace

Can't access Apps Script

• Verify user has "Apps Script Secret Accessor" IAM role
• Check secret name is exactly llm-api-key
• Confirm GCP_PROJECT_ID matches your GCP project

Sheet validation fails

• Required columns must be exact: Email Address, First Name, Last Name
• Column headers must be in the first row
• Verify user's Google account has edit access to sheet

Model fetch fails

• Ensure Apps Script connection works
• Check API key in Apps Script is valid
• Try disconnecting and reconnecting Google account

Email Generation Issues

LLM errors

• Verify model is selected in Configuration
• Check API key in Apps Script is valid
• For Gemini: ensure model name format is correct (e.g., gemini-1.5-flash)

List formatting problems

• LLM uses single newlines for list items
• Double newlines create paragraph breaks
• Check generated email preview before sending

See USER_SETUP_GUIDE.md for more troubleshooting steps.

Documentation Files

• README.md - This file, overview and quick start
• OAUTH_SETUP.md - Complete OAuth configuration guide
• SECRET_MANAGER_SETUP.md - Apps Script setup instructions
• SECURITY.md - Security architecture and CSP details
• USER_SETUP_GUIDE.md - End-user setup and troubleshooting
• spec.md - Technical specification and architecture

License

MIT