StarMail Tasks

Purpose

StarMail Tasks is a web application designed to integrate deeply with Gmail APIs. Its primary goal is to convert your passive inbox workflow into an actionable to-do list. By automatically fetching emails marked with the STARRED label across multiple linked Gmail accounts, the application provides a centralized hub to review important emails, add context-specific notes, and mark them as completed entirely outside of a cluttered inbox interface.

Architecture

The application is built on a standard Client-Server architecture:

1. Client Layer (Frontend):
   • A dynamic single-page application feel built with Vanilla JavaScript (static/app.js).
   • Handles seamless OAuth flow initiation, dropdown-based dynamic account switching, and real-time DOM updates for tasks.
   • Styled with modern CSS aesthetics featuring custom properties, dark mode, and glassmorphism UI elements (static/styles.css).
2. Application Layer (Backend):
   • Built on Flask, functioning as both an API provider and the host for the main UI template (routes.py, app.py).
   • Relies on google-auth and google-api-python-client to facilitate the OAuth 2.0 flow and store refresh/access tokens (google_auth.py).
   • Connects to the user's Gmail API independently to extract metadata (Subject, Sender, Snippet) from starred messages (gmail_service.py).
3. Database Layer:
   • An SQLite database managed via SQLAlchemy (models.py).
   • Securely stores user profiles, linked Gmail accounts (and their associated credentials), and customized task metadata including completion statuses and rich user-generated notes.

Tech Stack

• Backend: Python 3, Flask, Flask-SQLAlchemy, Google API Python Client
• Database: SQLite
• Frontend: HTML5, CSS3, Vanilla JavaScript
• Security: Google OAuth 2.0

How to Run Locally

Prerequisites

• Python 3.8+
• Google Cloud Console Project with the Gmail API enabled
• OAuth 2.0 Client credentials downloaded as oauth.json and placed in the project root.

Setup Instructions

1. Clone the repository (if applicable):

   git clone https://github.com/charmi-reddy/StarMail.git
   cd StarMail

2. Set up a Virtual Environment:

   python -m venv venv
   
   # Windows:
   .\venv\Scripts\Activate.ps1
   # macOS/Linux:
   source venv/bin/activate

3. Install Dependencies:

   pip install -r requirements.txt

4. Run the Application:

   python app.py

5. Access the App: Navigate your web browser to http://127.0.0.1:5000 to log in and start fetching your starred emails!