Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/auroracapital/ai-gmail-assistant

🤖 Automate your Gmail inbox with AI-powered email organization, smart categorization, and language-aware draft responses using Claude Sonnet 4.5
https://github.com/auroracapital/ai-gmail-assistant

ai automation aws-lambda claude email-automation email-organizer gmail inbox-zero openrouter productivity python serverless

Last synced: about 1 month ago
JSON representation

🤖 Automate your Gmail inbox with AI-powered email organization, smart categorization, and language-aware draft responses using Claude Sonnet 4.5

Awesome Lists containing this project

README 

          
# 🤖 AI Gmail Assistant



> **Automate your Gmail inbox with AI-powered email organization, smart categorization, and language-aware draft responses**



[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)

[![GitHub stars](https://img.shields.io/github/stars/auroracapital/ai-gmail-assistant?style=social)](https://github.com/auroracapital/ai-gmail-assistant/stargazers)



**AI Gmail Assistant** uses Claude Sonnet 4.5 to intelligently organize your Gmail inbox, generate contextual draft responses, and save you hours every week. It's like having a personal email assistant that understands your business context and communication style.



---



## ✨ Features



### 🎯 **Smart Email Categorization**

- **AI-Powered Analysis**: Uses Claude Sonnet 4.5 to understand email context and intent

- **Colored Labels**: Automatically applies visual labels (🔴 Action, 🟠 Respond, 🟢 FYI)

- **Conservative Deletion**: Safely removes spam and verification codes while preserving important emails

- **Auto-Starring**: Highlights critical emails requiring immediate attention



### 💬 **Universal Language-Aware Draft Responses**

- **Auto Language Detection**: AI automatically detects the language of incoming emails (supports all major languages)

- **Native Language Responses**: Responds in the same language as the sender (English, Dutch, Spanish, French, German, Chinese, Japanese, and more)

- **Context-Aware**: Understands your business (music industry, SaaS, investments)

- **Tone Matching**: Maintains appropriate formality level

- **One Draft Per Thread**: Automatically manages draft versions



### 📋 **Action Outlines**

- **Step-by-Step Plans**: Creates actionable checklists for complex emails

- **Deadline Detection**: Identifies and tracks email deadlines

- **Auto-Snooze**: Resurfaces emails 2 days before deadlines



### ☁️ **Serverless Deployment**

- **AWS Lambda**: Runs automatically on schedule

- **Cost-Effective**: ~$1.25/month for daily execution

- **Secure**: All credentials in AWS Secrets Manager

- **Scalable**: Handles hundreds of emails per run



---



## 🚀 Quick Start



### Prerequisites



- **Python 3.11+** installed on your system

- **Gmail account** with API access enabled

- **Google Cloud Project** with Gmail API enabled

- **OpenRouter API key** ([sign up here](https://openrouter.ai/keys))

- **(Optional) AWS account** for Lambda deployment



### Step 1: Clone the Repository



```bash

git clone https://github.com/auroracapital/ai-gmail-assistant.git

cd ai-gmail-assistant

```



### Step 2: Install Dependencies



```bash

pip install -r requirements.txt

```



### Step 3: Set Up Gmail API Credentials



#### 3.1 Create Google Cloud Project



1. Go to [Google Cloud Console](https://console.cloud.google.com/)

2. Create a new project or select existing one

3. Enable the **Gmail API**:

   - Navigate to **APIs & Services** > **Library**

   - Search for "Gmail API"

   - Click **Enable**



#### 3.2 Create OAuth 2.0 Credentials



1. Go to **APIs & Services** > **Credentials**

2. Click **Create Credentials** > **OAuth client ID**

3. Configure OAuth consent screen (if prompted):

   - User Type: **External**

   - App name: `AI Gmail Assistant`

   - User support email: Your email

   - Scopes: Add `gmail.modify` and `gmail.readonly`

4. Application type: **Desktop app**

5. Name: `Gmail Organizer Desktop Client`

6. Click **Create**

7. **Download JSON** and save as `credentials/client_secret.json`



```bash

# Create credentials directory

mkdir -p credentials

# Move downloaded file to credentials/client_secret.json

```



### Step 4: Get OpenRouter API Key



1. Sign up at [OpenRouter](https://openrouter.ai)

2. Navigate to [API Keys](https://openrouter.ai/keys)

3. Click **Create Key**

4. Copy the API key (starts with `sk-or-v1-...`)



### Step 5: Configure Environment Variables



```bash

# Copy example environment file

cp .env.example .env



# Edit .env with your credentials

nano .env

```



Add your OpenRouter API key:



```bash

# .env

OPENROUTER_API_KEY=sk-or-v1-your-actual-api-key-here

```



### Step 6: First Run (Local)



```bash

python src/gmail_organizer.py

```



**On first run**, you'll see:



```

Please visit this URL to authorize this application:

https://accounts.google.com/o/oauth2/auth?client_id=...

```



1. Open the URL in your browser

2. Sign in with your Gmail account

3. Grant permissions to the app

4. You'll see "The authentication flow has completed"

5. A `token.json` file will be created automatically



The script will now:

- Fetch your unread emails

- Analyze them with Claude AI

- Apply labels, stars, and create drafts

- Show a summary of actions taken



---



## 🌐 AWS Lambda Deployment (Optional)



Deploy to AWS Lambda for **automatic daily inbox organization** at 9 AM.



### Prerequisites



- AWS account with CLI configured

- AWS credentials with Lambda, Secrets Manager, and EventBridge permissions



### Step 1: Configure AWS Credentials



```bash

# Option 1: AWS CLI

aws configure

# Enter your AWS Access Key ID

# Enter your AWS Secret Access Key

# Default region: eu-west-1 (or your preferred region)



# Option 2: Environment variables

export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE

export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

export AWS_DEFAULT_REGION=eu-west-1

```



### Step 2: Store Secrets in AWS Secrets Manager



```bash

# Store OpenRouter API key

aws secretsmanager create-secret \

    --name gmail-organizer/openrouter-api-key \

    --secret-string "sk-or-v1-your-actual-api-key-here" \

    --region eu-west-1



# Store Gmail OAuth credentials (client_secret.json content)

aws secretsmanager create-secret \

    --name gmail-organizer/gmail-oauth-credentials \

    --secret-string file://credentials/client_secret.json \

    --region eu-west-1



# Store Gmail API token (token.json content - generated after first local run)

aws secretsmanager create-secret \

    --name gmail-organizer/gmail-api-token \

    --secret-string file://token.json \

    --region eu-west-1

```



### Step 3: Deploy Lambda Function



```bash

# Package dependencies

cd src

pip install -r ../requirements.txt -t .



# Create deployment package

zip -r ../gmail-organizer-lambda.zip .

cd ..



# Create IAM role (see docs/AWS_DEPLOYMENT.md for full policy)

aws iam create-role \

    --role-name GmailOrganizerLambdaRole \

    --assume-role-policy-document file://docs/lambda-trust-policy.json



# Attach policies

aws iam attach-role-policy \

    --role-name GmailOrganizerLambdaRole \

    --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole



# Create Lambda function

aws lambda create-function \

    --function-name gmail-inbox-organizer \

    --runtime python3.11 \

    --role arn:aws:iam::YOUR_ACCOUNT_ID:role/GmailOrganizerLambdaRole \

    --handler gmail_organizer_lambda.lambda_handler \

    --zip-file fileb://gmail-organizer-lambda.zip \

    --timeout 300 \

    --memory-size 512 \

    --region eu-west-1

```



### Step 4: Schedule Daily Execution



```bash

# Create EventBridge rule for daily 9 AM (Amsterdam time = 7 AM UTC)

aws events put-rule \

    --name gmail-organizer-daily-9am \

    --schedule-expression "cron(0 7 * * ? *)" \

    --region eu-west-1



# Add Lambda permission for EventBridge

aws lambda add-permission \

    --function-name gmail-inbox-organizer \

    --statement-id AllowEventBridgeInvoke \

    --action lambda:InvokeFunction \

    --principal events.amazonaws.com \

    --source-arn arn:aws:events:eu-west-1:YOUR_ACCOUNT_ID:rule/gmail-organizer-daily-9am



# Add Lambda as target

aws events put-targets \

    --rule gmail-organizer-daily-9am \

    --targets "Id"="1","Arn"="arn:aws:lambda:eu-west-1:YOUR_ACCOUNT_ID:function:gmail-inbox-organizer"

```



**See [AWS Deployment Guide](docs/AWS_DEPLOYMENT.md) for detailed instructions and troubleshooting.**



---



## 📖 How It Works



```mermaid

graph LR

    A[Gmail Inbox] --> B[AI Analysis]

    B --> C{Categorize}

    C -->|Spam| D[Delete]

    C -->|Urgent| E[Star + Label]

    C -->|Action| F[Create Outline]

    C -->|Respond| G[Draft Reply]

    E --> H[Organized Inbox]

    F --> H

    G --> H

```



1. **Fetch Emails**: Retrieves unread emails from your Gmail inbox

2. **AI Analysis**: Claude Sonnet 4.5 analyzes each email's content, sender, and context

3. **Smart Actions**:

   - **Delete**: Removes spam, expired verification codes, promotional emails

   - **Star**: Highlights billing issues, payment failures, urgent matters

   - **Label**: Applies colored labels (action/respond/fyi)

   - **Draft**: Generates language-aware responses

   - **Outline**: Creates action plans for complex tasks



---



## 🎨 Label System



| Label | Color | Purpose | Example |

|-------|-------|---------|---------|

| **action** | 🔴 Red | Requires specific action | Payment update, contract signing |

| **respond** | 🟠 Orange | Needs email reply | Business inquiry, collaboration request |

| **fyi** | 🟢 Green | Informational only | Invoices, confirmations, newsletters |



---



## 🔧 Configuration



### Customize Business Context



Edit `src/gmail_organizer.py` to add your business context:



```python

USER_CONTEXT = """

Your business: Music production, SaaS startup

Key contacts: Investors, collaborators, labels

Priority: Billing > Legal > Business > Personal

"""

```



### Adjust Label Colors



Configure Gmail label colors in the script:



```python

LABEL_COLORS = {

    "action": "red",      # #FF0000

    "respond": "orange",  # #FF9900

    "fyi": "green"        # #00FF00

}

```



### Change Schedule (AWS Lambda)



Modify EventBridge cron expression:



```bash

# Daily at 9 AM Amsterdam time (7 AM UTC)

cron(0 7 * * ? *)



# Twice daily at 9 AM and 5 PM

cron(0 7,15 * * ? *)



# Every 4 hours

cron(0 */4 * * ? *)

```



---



## 📊 Performance



- **Processing Speed**: ~2-3 minutes for 50 emails

- **Accuracy**: 95%+ categorization accuracy

- **Cost**: $0.04 per run (OpenRouter API)

- **AWS Lambda Cost**: ~$1.25/month (daily execution)

- **Uptime**: 99.9% (AWS Lambda)



---



## 🛡️ Security & Privacy



- ✅ **OAuth 2.0**: Secure Gmail authentication

- ✅ **No Data Storage**: Emails processed in memory only

- ✅ **Encrypted Secrets**: AWS Secrets Manager for credentials

- ✅ **Open Source**: Fully auditable code

- ✅ **Local-First**: Run on your machine, you control the data

- ✅ **Least Privilege**: IAM roles with minimal permissions



### Security Best Practices



1. **Never commit credentials** to Git (use `.gitignore`)

2. **Rotate API keys** regularly

3. **Use AWS Secrets Manager** for production deployments

4. **Enable MFA** on your AWS account

5. **Review IAM policies** for least-privilege access



---



## 🤝 Contributing



We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.



### Development Setup



```bash

# Create feature branch

git checkout -b feature/your-feature-name



# Install dev dependencies

pip install -r requirements-dev.txt



# Run tests

pytest tests/



# Format code

black src/

isort src/



# Lint

flake8 src/

```



---



## 📝 License



This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.



---



## 🌟 Star History



[![Star History Chart](https://api.star-history.com/svg?repos=auroracapital/ai-gmail-assistant&type=Date)](https://star-history.com/#auroracapital/ai-gmail-assistant&Date)



---



## 💬 Community & Support



- 🐛 [Report a Bug](https://github.com/auroracapital/ai-gmail-assistant/issues/new?template=bug_report.md)

- 💡 [Request a Feature](https://github.com/auroracapital/ai-gmail-assistant/issues/new?template=feature_request.md)

- 💬 [Join Discussions](https://github.com/auroracapital/ai-gmail-assistant/discussions)

- 📧 Email: sam@auroracapital.nl



---



## 🙏 Acknowledgments



- **Claude Sonnet 4.5** by Anthropic for AI-powered email analysis

- **OpenRouter** for multi-model API access

- **Google Gmail API** for email integration

- **AWS Lambda** for serverless execution



---



## 📈 Roadmap



- [ ] Microsoft Outlook support

- [ ] Slack integration for notifications

- [ ] Custom AI model fine-tuning

- [ ] Mobile app (iOS/Android)

- [ ] Team collaboration features

- [ ] Analytics dashboard

- [ ] Browser extension

- [ ] Zapier/Make.com integration



---



## ❓ FAQ



### How much does it cost to run?



- **OpenRouter API**: ~$0.04 per run (50 emails)

- **AWS Lambda**: ~$1.25/month (daily execution)

- **Gmail API**: Free (up to 1 billion quota units/day)



### Is my email data stored anywhere?



No. All email processing happens in memory. No data is stored or logged.



### Can I run this without AWS?



Yes! Run locally with `python src/gmail_organizer.py` or set up a cron job.



### What languages are supported?



All major languages! The AI automatically detects the language of the incoming email and responds in that same language. This includes English, Dutch, Spanish, French, German, Italian, Portuguese, Chinese, Japanese, Korean, Arabic, and many more. No configuration needed - it just works.



### How do I stop the automation?



**AWS Lambda**: Delete the EventBridge rule or disable the Lambda function.

**Local cron**: Remove the cron job entry.



---





  Made with ❤️ by developers who hate email overload






  Get Started •

  How It Works •

  Deploy •

  Contribute