Anutri03/email_spam_api

📧 Email Spam Detection API

A powerful AI-powered email spam detection system that not only classifies emails as spam or legitimate but also provides detailed explanations for its decisions.

🚀 Features

• —High Accuracy: Uses DistilBERT transformer model with 98.86% F1-Score
• —Multiple Models: Supports both transformer and traditional ML models
• —Detailed Explanations: Provides reasons why an email was classified as spam or ham
• —Batch Processing: Can process multiple emails at once
• —RESTful API: Clean, well-documented API endpoints
• —Fast Performance: Optimized for production use

🏗️ Architecture

Models Available:

1. 1.DistilBERT (Best Performance) - 98.86% F1-Score
2. 2.Random Forest - 97.69% F1-Score
3. 3.Logistic Regression - 95.47% F1-Score
4. 4.Naive Bayes - 91.38% F1-Score

Spam Detection Features:

• —Text Pattern Analysis: Detects urgency words, money references, action words
• —Formatting Analysis: Identifies excessive caps, multiple exclamation marks
• —URL Detection: Counts and analyzes suspicious links
• —Feature Importance: Shows which words/patterns influenced the decision

📡 API Endpoints

Base URL

https://anutri03-email-spam-api.hf.space

1. Health Check

GET /health

Response:

{
  "status": "healthy",
  "models_loaded": 4,
  "best_model": "DistilBERT"
}

2. Single Email Prediction

POST /predict
Content-Type: application/json

{
  "text": "URGENT: Your account has been compromised. Click here to update your password!"
}

Response:

{
  "prediction": "spam",
  "confidence": 0.95,
  "explanation": "🚨 **SPAM DETECTED**\n\n**Spam indicators found:**\n• Contains 'urgent'\n• Contains 'click here'\n• Multiple exclamation marks (1)",
  "model_used": "DistilBERT"
}

3. Batch Email Prediction

POST /predict_batch
Content-Type: application/json

{
  "emails": [
    "Hi team, meeting at 2 PM today",
    "FREE MONEY!!! Click here to claim your prize!"
  ]
}

4. Model Information

GET /model_info

🔧 Usage Examples

Python

import requests

# Single prediction
response = requests.post(
    "https://anutri03-email-spam-api.hf.space/predict",
    json={"text": "Your email text here"}
)
result = response.json()
print(f"Prediction: {result['prediction']}")
print(f"Explanation: {result['explanation']}")

# Batch prediction
emails = ["Email 1", "Email 2", "Email 3"]
response = requests.post(
    "https://anutri03-email-spam-api.hf.space/predict_batch", 
    json={"emails": emails}
)
results = response.json()

cURL

# Single prediction
curl -X POST "https://anutri03-email-spam-api.hf.space/predict" \
  -H "Content-Type: application/json" \
  -d '{"text": "URGENT: Click here to claim your prize!"}'

# Health check
curl "https://anutri03-email-spam-api.hf.space/health"

🚨 Spam Indicators Detected

The system analyzes emails for various spam indicators:

Keywords

• —Urgency: "urgent", "immediate", "asap", "emergency", "act now"
• —Money: "free", "win", "prize", "money", "cash", "million", "dollar"
• —Actions: "click here", "buy now", "order now", "call now"

Patterns

• —Suspicious Patterns: $d+, % off, limited time, act now
• —Excessive Formatting: Multiple caps, exclamation marks
• —URLs: Suspicious links and multiple email addresses

📊 Performance Metrics

📝 API Documentation

Once deployed, visit /docs for interactive API documentation:

• —Swagger UI: https://anutri03-email-spam-api.hf.space/docs
• —ReDoc: https://anutri03-email-spam-api.hf.space/redoc

🔒 Rate Limits

• —Single Predictions: No limit
• —Batch Predictions: Maximum 100 emails per request
• —Text Length: Maximum 10,000 characters per email

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgments

• —Hugging Face for the DistilBERT model
• —Scikit-learn for traditional ML algorithms
• —FastAPI for the web framework
• —Transformers library for NLP capabilities

Made with ❤️ for email security