Urgent Email Assistant

This CrewAI Flow checks an inbox for a requested date, classifies which messages are truly urgent, drafts a digest, and emails that digest back to the user with the original urgent messages attached as .eml files.

What It Does

1. Asks for email login details in the CLI.
2. Uses a small CrewAI date interpreter agent with calendar tools to resolve the requested inbox date.
3. Uses a CrewAI agent to classify urgent emails conservatively.
4. Sends a new email digest to the user.
5. Saves a local markdown copy at output/urgent_email_digest.md.

Urgent means the user likely needs to act today: deadlines, customer escalations, payment/legal/security issues, outages, soon meetings, or direct important requests. Newsletters, promotions, FYI messages, and routine notifications are skipped.

Setup

Install dependencies:

python -m venv .venv
.\.venv\Scripts\python -m pip install -e .

Add your LLM key to .env: Note: user GOOGLE_API_KEY if your model is Gemini

OPENAI_API_KEY=your_key_here
EMAIL_TRIAGE_MODEL=openai/gpt-4o-mini

For Gmail, Outlook, Yahoo, and many work accounts, use an app password rather than your normal password. IMAP and SMTP must be enabled for the mailbox.

Model Selection

The triage model can be changed without editing code. The app checks model settings in this order:

1. --model
2. EMAIL_TRIAGE_MODEL
3. MODEL
4. OPENAI_MODEL_NAME
5. openai/gpt-4o-mini

CrewAI uses provider/model strings. Examples:

# OpenAI
EMAIL_TRIAGE_MODEL=openai/gpt-4o-mini
OPENAI_API_KEY=your_openai_key

# Google Gemini
EMAIL_TRIAGE_MODEL=google/gemini-2.0-flash
GOOGLE_API_KEY=your_google_key

You can also choose the model for one run:

.\.venv\Scripts\python run_email_triage.py "what are the important mails for today" --model google/gemini-2.0-flash --email you@gmail.com

For this use case, prefer a fast, low-cost model that handles structured output reliably. Upgrade to a stronger model if the digest misses nuanced escalation or compliance emails.

Security Guardrails

• The email password/app password is only stored in memory as a private runtime value.
• The password is used only for IMAP login and SMTP login.
• The password is never included in the CrewAI agent prompt. The code checks for this before calling the model.
• Date interpretation sends only the user's request text to the selected model.
• Email content, sender, subject, date, and body excerpts are sent to the selected AI model for classification.
• IMAP is opened in read-only mode, so the app does not change mailbox flags or delete messages while reading.
• The app has no code path for deleting, archiving, moving, marking spam, or expunging inbox mail.
• The digest is sent only to the logged-in mailbox by default. Sending to a different address is blocked unless --allow-external-recipient is explicitly passed.
• Agent output is validated so recommended actions cannot tell the app/user to delete, archive, trash, purge, mark spam, or forward messages.

Run

From this project directory:

.\.venv\Scripts\python run_email_triage.py

Or pass the request and known settings:

.\.venv\Scripts\python run_email_triage.py "what are the important mails for today" --email you@gmail.com --recipient you@gmail.com

Scan a specific date with a deterministic CLI override:

.\.venv\Scripts\python run_email_triage.py "important emails" --date 2026-06-19 --email you@gmail.com

Free-form date language in the prompt is resolved by a CrewAI date interpreter agent with calendar tools:

.\.venv\Scripts\python run_email_triage.py "what are the important mails for 22 May 2026" --email you@gmail.com

Other examples the date agent can handle:

.\.venv\Scripts\python run_email_triage.py "show urgent mail from last Friday" --email you@gmail.com
.\.venv\Scripts\python run_email_triage.py "what important emails came in yesterday morning" --email you@gmail.com
.\.venv\Scripts\python run_email_triage.py "important inbox items from May 22" --email you@gmail.com

If your provider is not auto-detected, pass hosts explicitly:

.\.venv\Scripts\python run_email_triage.py "what are the important mails for today" --email you@example.com --imap-host imap.example.com --smtp-host smtp.example.com

If inbox fetching feels slow, reduce the message cap or timeout:

.\.venv\Scripts\python run_email_triage.py "what are the important mails for 22 May 2026" --email you@gmail.com --max-messages 50 --imap-timeout 20

You can also run the module directly:

.\.venv\Scripts\python -m urgent_email_assistant.main "what are the important mails for today"

Notes

• The app only sends the digest after it successfully logs in, fetches messages, and classifies them.
• Original urgent emails are attached to the digest as .eml files.
• The password prompt is hidden. Avoid using --password except for local testing.
• Use --date YYYY-MM-DD when you want to bypass LLM date interpretation.
• Inbox fetch prints progress and defaults to a 30-second IMAP timeout plus a 100-message cap for the selected date.
• If you use --allow-external-recipient, review the recipient carefully because urgent emails may contain sensitive information.
• The active implementation is in src/urgent_email_assistant/main.py.