Flags API: Flagging Phishing Emails

#devchallenge #postmarkchallenge #webdev #api

This is a submission for the Postmark Challenge: Inbox Innovators.

What I Built

I built a developer-focused phishing detection microservice that analyzes inbound emails (via Postmark) and scores them for potential phishing indicators. The solution combines classic heuristics (e.g., mismatched links, suspicious reply-to addresses) with machine learning-based email intent classification to provide explainable, interpretable results.

The service is designed to be:

Explainable – Every phishing score is backed by specific, human-readable reasons.
Extensible – Built on FastAPI, with a modular architecture for adding more rules or ML models.
Postmark-ready – Accepts Postmark’s inbound webhook payloads out-of-the-box.

Demo

You can run the service locally using Docker or Python:

uvicorn app.api:app --reload

Then test it using:

curl -X POST http://localhost:8000/postmark/webhook \
  -H "Content-Type: application/json" \
  -d @tests/sample_postmark_email.json

The service will return a phishing verdict like:

{
  "verdict": {
    "score": 0.75,
    "reasons": [
      "Mismatch between link text and URL destination",
      "Suspicious reply-to address",
      "Detected urgent or manipulative language"
    ],
    "intent": "threat",
    "intent_confidence": 0.92
  }
}

No credentials are required for testing. Feel free to use the sample payloads in the repo.

Code Repository

GitHub: https://github.com/dteklavya/mail-sentinel

How I Built It

This project was built using:

Python + FastAPI for the web API
Pytest for test coverage
Hugging Face Transformers to detect manipulative email intent
Postmark Inbound Webhook to ingest real-world email data

The phishing detector combines rule-based checks like:

Mismatched anchor text and URLs
Suspicious Reply-To headers
Common urgent phrases

With ML-based sentiment intent detection for “fear”, “threats”, and similar phishing tones.

The design keeps the logic explainable and modular, making it ideal for dev-focused environments where transparency in email filtering is critical.

TODO / Limitations

The current ML model for email intent focuses on emotional tone (e.g., fear, threat) but doesn't fully capture all varieties of phishing tactics (like fake promotions, lotteries, or impersonated legal notices).
Intent classification can be further refined by fine-tuning on email-specific datasets or integrating custom-trained classifiers for phishing intent.
UI/visualization layer is not included — future plans include adding a simple dashboard or Postmark-friendly email header injection for visibility.
Due to the short development window, this is an MVP — several enhancements (e.g., domain reputation checks, attachment analysis) are on the roadmap.

DEV Community