Gmail Email Sorter Setup Guide

This guide will walk you through setting up the Gmail Email Sorter application from installation to execution.

Table of Contents

1. Prerequisites
2. Installation
3. Google Cloud Setup
4. Configuration
5. Running the Application
6. Troubleshooting

Prerequisites

• Python 3.8 or higher
• A Gmail account
• Internet connection

Installation

Step 1: Clone or download the project

Download the code to your local machine.

Step 2: Install required packages

# Install LangChain and LangGraph
pip install langchain langchain-core langgraph

# Install HuggingFace Transformers
pip install transformers torch

# Install Google API libraries
pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib

Google Cloud Setup

Step 1: Create a Google Cloud Project

1. Go to the Google Cloud Console
2. Click on the project dropdown at the top of the page
3. Click "New Project"
4. Enter a project name (e.g., "Email Sorter") and click "Create"
5. Wait for the project to be created, then select it from the dropdown

Step 2: Enable the Gmail API

1. In the Google Cloud Console, navigate to "APIs & Services" > "Library" in the left sidebar
2. Search for "Gmail API" and click on it
3. Click the "Enable" button

Step 3: Configure OAuth Consent Screen

1. In the Google Cloud Console, navigate to "APIs & Services" > "OAuth consent screen"
2. Select "External" user type (unless you have a Google Workspace account)
3. Fill in the required information:
   • App name: "Email Sorter" (or your preferred name)
   • User support email: Your email address
   • Developer contact information: Your email address
4. Click "Save and Continue"
5. On the "Scopes" page, click "Add or Remove Scopes"
6. In the filter box, enter: https://www.googleapis.com/auth/gmail.modify
7. Check the box next to this scope when it appears
8. Click "Update" and then "Save and Continue"
9. On the "Test users" page, click "Add Users"
10. Add your Gmail address (the one you'll use with the sorter)
11. Click "Save and Continue"
12. Review your app information and click "Back to Dashboard"
13. Note: Your app will be in "Testing" mode, which is fine for personal use

Step 4: Create OAuth 2.0 Client ID and Download Credentials

1. In the Google Cloud Console, navigate to "APIs & Services" > "Credentials"
2. Click "Create Credentials" > "OAuth client ID"
3. Select "Desktop app" as the application type
4. Name: "Email Sorter Client" (or your preferred name)
5. Click "Create"
6. You'll see a popup with your client ID and client secret
7. Click "Download JSON" to download your credentials
8. Rename the downloaded file to credentials.json
9. Move this file to the same directory as your script

If you need to download your credentials again later:

1. Go to Google Cloud Console > "APIs & Services" > "Credentials"
2. Under "OAuth 2.0 Client IDs", find your client
3. Click the download icon (↓) on the right side of your client's row
4. Rename the downloaded file to credentials.json
5. Replace your existing file with this new download

Configuration

Step 1: Create necessary directories

The script needs certain directories to store temporary files and sorted emails. Create these directories or ensure your code has the correct paths defined:

# Example directory structure
TEMP_PATH = "temp"
BASE_SAVE_PATH = "sorted_emails"

Step 2: Define your sorting rules

Ensure your KEYWORD_RULES dictionary is properly defined in your code to match your email sorting needs:

# Example keyword rules
KEYWORD_RULES = {
    "GitHub": ["STAR", "PR", "ISSUE"],
    "Document": ["REPORT", "INVOICE", "CONTRACT"],
    # Add more rules as needed
}

Running the Application

Step 1: First-time authentication

1. Run the script: python email_sorter.py
2. A browser window will open asking you to log in to your Google account
3. Select your account and click "Continue"
4. Review the permissions and click "Continue"
5. The browser will show "The authentication flow has completed."
6. Return to your terminal. The script should now be running and monitoring for new emails.

Step 2: Regular operation

After the first authentication, the script will:

1. Skip all existing emails in your inbox
2. Wait for new emails to arrive
3. Process each new email through your sorting pipeline
4. Sort emails into the appropriate folders based on your rules

To stop the script, press Ctrl+C in your terminal.

Troubleshooting

Authentication Issues

• Error: "Client secrets not found"
  Make sure your credentials.json file is in the same directory as your script.

• Error: "Access denied"
  Make sure you've added your email as a test user in the OAuth consent screen.

• Error: "This app isn't verified"
  When authenticating, you might see a warning that the app isn't verified. Click "Advanced" and then "Go to [Your App Name] (unsafe)" to proceed. This is normal for apps in testing mode.

• Error: "redirect_uri_mismatch"
  Ensure you're using the correct credentials.json file. Delete any token.pickle file and try again.

API Errors

• Error: "Gmail API not enabled"
  Make sure you've enabled the Gmail API in your Google Cloud project.

• Error: "Invalid grant"
  If your token expires, delete the token.pickle file and run the script again to re-authenticate.

• Error: "Daily Limit Exceeded" or "User Rate Limit Exceeded"
  You may be making too many requests to the Gmail API. Try increasing the polling interval.

Email Processing Errors

• If emails aren't being sorted correctly, check your KEYWORD_RULES and the logic in your processing functions.
• Check the console output for specific error messages related to the LLM or sorting process.

Common Solutions

• Reset authentication: Delete the token.pickle file to force re-authentication
• Check API quotas: If you're processing many emails, you might hit API quotas. Check the Google Cloud Console for quota usage.
• Debug logs: Add more print statements to your code to track where errors occur