MorningMail AI – Intelligent Daily Email Digest

MorningMail AI is a production-ready daily email parser that checks your Gmail every morning, applies AI (Gemini or OpenAI) to identify only the emails that actually matter, summarizes them, and delivers a formatted digest straight to your WhatsApp.

It includes a premium, glassmorphic dark-mode web dashboard to monitor your incoming feeds, toggle AI classifications, trigger manual digest runs, check scheduler cron times, and train the AI over time based on feedback.

---

Features

• Gmail API OAuth 2.0: Reads messages securely using modern token flows (token auto-refreshes in the background).
• AI Classification Layer: Filters out newsletters, promotions, LinkedIn notifications, and spam. Supports Gemini (default) or OpenAI.
• WhatsApp Cloud API: Integrates with the official Meta WhatsApp Graph API to deliver daily digests.
• WhatsApp & Gmail Simulators: Run the app completely offline without configuring Google Cloud or Meta developer accounts for easy local testing.
• Feedback & Rule Customization: The AI automatically learns from your inputs (thumbs up/down, muting) to dynamically modify classification rules.
• Weather Integrations: Appends daily weather forecasts to the morning digest.
• Background Scheduler: Dynamic cron executions using APScheduler that updates in real-time when the timezone or run time changes.

---

Folder Structure

morningmail-ai/
│
├── app/
│   ├── api/
│   │   ├── auth.py          # Gmail OAuth flow endpoints
│   │   ├── emails.py        # Log logs list and user feedback loops
│   │   ├── preferences.py   # Scheduling configuration, rules and mutes
│   │   └── digests.py       # History logs, manual trigger and simulator API
│   │
│   ├── database/
│   │   ├── connection.py    # Database engines and context sessions
│   │   └── repository.py    # Database CRUD helper queries
│   │
│   ├── models/
│   │   └── db_models.py     # SQLAlchemy User, Email, History, and Cache schemas
│   │
│   ├── schemas/
│   │   └── api_schemas.py   # Pydantic request/response data models
│   │
│   ├── services/
│   │   ├── ai_service.py    # AI provider bindings and heuristic simulators
│   │   ├── gmail_service.py # Gmail API client and inbox simulators
│   │   ├── wa_service.py    # Meta WhatsApp API client and file logs simulator
│   │   ├── weather_service.py # wttr.in or OpenWeatherMap provider
│   │   └── digest_orchestrator.py # Core workflow coordinator
│   │
│   ├── prompts/
│   │   └── templates.py     # System instructions and classification formats
│   │
│   ├── scheduler/
│   │   └── scheduler.py     # APScheduler setup and cron triggers
│   │
│   ├── utils/
│   │   ├── config.py        # Pydantic settings loading .env parameters
│   │   └── logger.py        # Rotating log files configuration
│   │
│   ├── main.py              # Application entrypoint and static file mount
│   │
│   └── static/              # Web Dashboard SPA front-end (HTML / CSS / JS)
│
├── tests/
│   └── test_morningmail.py  # pytest test suites
│
├── .env.example             # Environment template
├── Dockerfile               # Production build recipe
├── docker-compose.yml       # Docker deployment composer
└── requirements.txt         # Package requirements list

---

Getting Started (Local Development)

1. Prerequisite Setup

• Python: Ensure Python 3.9+ is installed.
• Virtual Environment: Initialize a virtual environment:

  python -m venv venv
  source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install Dependencies

pip install -r requirements.txt

3. Environment Configuration

Copy the template .env.example file to .env:

cp .env.example .env

Fill out the keys as desired. By default, if you leave GMAIL_CLIENT_ID and GEMINI_API_KEY/OPENAI_API_KEY blank, the app will run in Simulator Mode using pre-configured heuristic classifications and mock inbox emails, so you can explore the dashboard features immediately!

---

Integrations Configuration

A. Gmail OAuth Setup (Google Cloud)

1. Go to the Google Cloud Console.
2. Create a new project.
3. Enable the Gmail API under APIs & Services.
4. Set up the OAuth Consent Screen (Choose External, add test users, set scopes to include .../auth/gmail.readonly).
5. Under Credentials, create OAuth 2.0 Client IDs (Application type: Web Application).
6. Set the Authorized redirect URIs to http://localhost:8000/api/auth/gmail/callback (or your production domain).
7. Copy your Client ID and Client Secret into your .env file under GMAIL_CLIENT_ID and GMAIL_CLIENT_SECRET.

B. WhatsApp Cloud API Setup (Meta Developer Console)

1. Go to the Meta for Developers Portal.
2. Create an App (Type: Business).
3. Add the WhatsApp product.
4. Copy the Temporary Access Token (or configure a Permanent token) and the Phone Number ID under WhatsApp Getting Started.
5. In your .env, set WHATSAPP_PROVIDER=cloud and paste your WHATSAPP_TOKEN, WHATSAPP_PHONE_NUMBER_ID, and WHATSAPP_RECIPIENT_NUMBER (your personal phone number including country code).
6. Important Note: To send free-text messages to your personal phone number, you must send a text message from your phone to the developer phone number first to open the 24-hour customer service session window!

---

Running the Application

Start the local server using Uvicorn:

uvicorn app.main:app --reload

Open http://localhost:8000 in your browser.

1. Simulator Check: Click Trigger Daily Digest Now on the right side. The app will fetch 10 mock emails, filter out newsletters/promotional material, categorize important items, compile the digest, and print it to the console. The simulated text will display in the WhatsApp mobile mockup screen instantly!
2. Link Gmail: Click Link Gmail to perform Google OAuth. Once approved, the dashboard badge changes to "Connected". Manual triggers and daily crons will sync your actual inbox!
3. Mute/Thumbs Up & Down: Click the thumbs-up/down icons on email logs to alter the priorities. Check the Override Rules tab to inspect the generated filters!

---

Running Automated Tests

Run unit tests via pytest:

pytest

---

Container Deployment

The application is Docker-ready.

Build and run using docker-compose:

docker-compose up --build -d

The database will be persisted under the docker volume sqlite_data so that your OAuth tokens, preference rules, and email history logs are saved securely across container instances!