# Project export: Mailman Extension
This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small.
## Project metadata
- Hackathon: Cal Hacks 12.0
- Tagline: Reading emails is boring, you don’t need to. Imagine an extension that is your personal assistant and lets you know about emails like an assistant. You can even ask it for specific questions.
- Devpost: https://devpost.com/software/mailman-extension
- GitHub: https://github.com/adityarp3/mailman-ext
- Team: 1 GitHub contributor(s) — unknown (5 commits)
## Devpost submission (written by the team)
### Inspiration
I get a lot of emails a day and want to only read the important ones on some days.
### What it does
It takes all your recent unread emails, and becomes your AI assistant for sorting by importance, telling you what the email is about and answer questions about the emails.
### How we built it
Python/JS/Flask framework/Gmail API/Gemini API
### Challenges we ran into
UI - I am not good with JavaScript.
### Accomplishments we're proud of
It works exactly how I hoped for.
### What's next
Hoping to deploy it for everyone to use soon.
## README (from the GitHub repository)
No README available.
## Detected evidence (automated analysis)
Indexed codebase: 5 recognized source files, 31 KB.
- Flask (technology) — detected in the code
- HTML (language) — detected in the code
- JavaScript (language) — detected in the code
- Python (language) — detected in the code
- Google Gemini (technology) — claimed on Devpost, not found in the code
## Codebase structure (from repository index)
### Files (9 of 9)
```
.gitignore
.vscode/settings.json
backend/app.py
extension/background.js
extension/manifest.json
extension/popup.html
extension/popup.js
README.md
requirements.txt
```
### Dependencies
- requirements.txt: flask@==3.0.0, flask-cors@==4.0.0, google-api-python-client@==2.110.0, google-auth@==2.25.2, google-auth-httplib2@==0.2.0, google-auth-oauthlib@==1.2.0, gunicorn@==23.0.0, python-dotenv@==1.1.1, requests@==2.31.0
### Recent commits (newest first)
- Delete extra files
- Update requirements.txt
- Initial Commit with fixed .gitignore
- Initial Commit with .gitignore
- Initial Commit
## Key source files (fetched from GitHub, selected and truncated for size)
### requirements.txt
```
flask==3.0.0
flask-cors==4.0.0
google-auth==2.25.2
google-auth-oauthlib==1.2.0
google-auth-httplib2==0.2.0
google-api-python-client==2.110.0
requests==2.31.0
python-dotenv==1.1.1
gunicorn==23.0.0
```
### backend/app.py
```python
from flask import Flask, jsonify, request
from flask_cors import CORS
from google.oauth2.credentials import Credentials
from googleapiclient.discovery import build
import os
import base64
import requests
import json
import time
from dotenv import load_dotenv
load_dotenv()
app = Flask(__name__)
CORS(app)
SCOPES = ['https://www.googleapis.com/auth/gmail.readonly']
GEMINI_API_KEY = os.environ.get("GEMINI_API_KEY")
GEMINI_MODEL_ID = "gemini-2.5-flash"
GEMINI_API_URL = f"https://generativelanguage.googleapis.com/v1beta/models/{GEMINI_MODEL_ID}:generateContent"
def get_gmail_service():
"""
Authenticate and return Gmail API service using the Bearer token
provided by the client (browser extension).
"""
auth_header = request.headers.get('Authorization')
if not auth_header:
raise Exception('Authorization header is missing')
try:
token_type, access_token = auth_header.split(' ')
if token_type.lower() != 'bearer':
raise Exception('Authorization header must start with Bearer')
creds = Credentials(access_token, scopes=SCOPES)
return build('gmail', 'v1', credentials=creds)
except Exception as e:
print(f"Error parsing auth header: {e}")
raise Exception(f'Invalid Authorization header: {e}')
def get_email_body(payload):
"""Extract email body from message payload"""
if 'parts' in payload:
for part in payload['parts']:
if part['mimeType'] == 'text/plain':
data = part['body'].get('data', '')
if data:
return base64.urlsafe_b64decode(data).decode('utf-8')
else:
data = payload.get('body', {}).get('data', '')
if data:
return base64.urlsafe_b64decode(data).decode('utf-8')
return ""
def rule_based_analysis(subject, sender, body):
"""Fallback rule-based analysis if Gemini fails or if email is pre-filtered."""
priority = 5
reason = "Default priority (AI analysis failed or quota exceeded)"
sender_lower = sender.lower()
low_priority_keywords = ['noreply', 'marketing', 'promo', 'unsubscribe', 'coupon', 'newsletter',
'advertisement', 'deal', 'offer', 'weekly digest', 'sale', 'save now']
if any(word in sender_lower for word in low_priority_keywords) or any(word in subject.lower() for word in low_priority_keywords):
priority = 2
reason = "Automated/promotional email filter hit"
return {
"summary": f"Email from {sender}: {subject}",
"priority": priority,
"reason": reason
}
if any(word in sender_lower for word in ['gov', 'government', 'irs', 'court', 'legal', '.gov']):
priority = 9
reason = "Government/legal sender"
elif any(word in sender_lower for word in ['boss', 'manager', 'ceo', 'director']):
priority = 8
reason = "Management communication"
elif any(word in sender_lower for word in ['teacher', 'professor', 'instructor', '.edu']):
priority = 7
reason = "Educational authority"
subject_lower = subject.lower()
urgent_keywords = ['urgent', 'immediate', 'action required', 'deadline', 'asap', 'emergency', 'important']
if any(word in subject_lower for word in urgent_keywords):
priority = min(priority + 2, 10)
reason = f"{reason} + urgent keywords"
body_lower = body[:200].lower()
if any(word in body_lower for word in ['due date', 'overdue', 'payment', 'suspended', 'expires']):
priority = min(priority + 1, 10)
summary = f"Email from {sender}: {subject}"
if len(summary) > 100:
summary = summary[:97] + "..."
return {
"summary": summary,
"priority": priority,
"reason": reason
}
def analyze_email_with_gemini(subject, sender, body, date, max_retries=3):
"""Use Google Gemini to analyze and prioritize email with retry logic and pre-check filter."""
low_priority_keywords = ['unsubscribe', 'coupon', 'newsletter', 'advertisement', 'promo', 'marketing',
'noreply', 'deal', 'offer', 'weekly digest', 'sale', 'save now']
sender_lower = sender.lower()
subject_lower = subject.lower()
if any(word in sender_lower for word in low_priority_keywords) or any(word in subject_lower for word in low_priority_keywords):
print(f"Skipping AI analysis for potential promo/spam: {subject}")
return rule_based_analysis(subject, sender, body)
if not GEMINI_API_KEY:
print("Falling back to rule-based analysis: GEMINI_API_KEY not found.")
return rule_based_analysis(subject, sender, body)
system_instruction = (
"You are an email prioritization expert. Your primary goal is to identify emails "
"that require a *personal, timely response* or contain *critical personal or professional information*. "
"Be extremely critical of any email that resembles marketing, automated reports, "
"or social media notifications. Only assign a priority score of 7 or higher if the email "
"demands immediate human action or contains legally/financially important content."
)
prompt = f"""{system_instruction}
--- END OF INSTRUCTIONS ---
Analyze this email and provide a brief summary, priority score, and reason.
Email Details:
From: {sender}
Date: {date}
Subject: {subject}
Body: {body[:1000]}
Respond ONLY with valid JSON in this exact format:
{{
"summary": "brief 1-2 sentence summary",
"priority": 8,
"reason": "explanation for priority score"
}}
"""
for attempt in range(max_retries):
try:
response = requests.post(
f"{GEMINI_API_URL}?key={GEMINI_API_KEY}",
json={
"contents": [
{
"role": "user",
"parts": [{"t
[truncated — 8540 more characters]
```
### extension/popup.html
```html
Mailman
Personal Email AI Assistant.
Error from Backend: ${data.error}
This may mean your token expired or the Gemini API key is missing on the server.