Machine Learning in Action: Build a Spam Filter 📧

🎯 Introduction — What Is Machine Learning Classification?

Welcome to one of the most exciting fields in modern technology! 🎉 In this tutorial, you will build a spam email classifier — a real Machine Learning model that can look at an email and decide whether it is spam or legitimate. By the time you finish, you will understand the complete ML workflow that powers everything from Gmail's spam filter to fraud detection at banks.

This is the second tutorial in our ML series. In the first, we predicted a continuous number (house price — regression). Here, we tackle a classification problem: the output is a category, not a number. Our two categories are simple:

The goal of our ML model is to learn the boundary between these two classes from example data, and then use that knowledge to classify new, unseen emails automatically.

❓ The Problem: Why We Can't Just Use Simple Rules

You might wonder: why use Machine Learning at all? Why not just write a simple rule like "if the email contains the word 'free', mark it as spam"?

Here is why rule-based systems fail in the real world:

🛠️ Prerequisites & Setup

Before we start, make sure you have Python and the required libraries installed.

✅ What You Need

• Python 3.7+ installed — download from python.org
• Basic Python knowledge — if you haven't done our Python CRUD tutorial yet, start there first!
• pip (Python package installer — comes with Python)

📦 Install Required Libraries

Open your terminal and run this single command:

pip install pandas scikit-learn numpy matplotlib

Here is what each library does:

1 Python Fundamentals — Feature Engineering

The first task in any ML project is converting real-world data into a format the computer can understand. This is called Feature Engineering — one of the most important skills in data science.

We cannot feed raw email text directly into most ML algorithms. Instead, we extract features — specific measurable properties of each email. For simplicity in this beginner tutorial, we will check for the presence of three keywords commonly found in spam emails: "free", "winner", and "prize".

📊 Our Dataset

We represent each email as a dictionary with four fields: three feature columns (1 = keyword present, 0 = not present) and one label column (is_spam: 1 = spam, 0 = not spam).

# ── Import our essential libraries ──────────────────
import pandas as pd
import numpy as np

# ── Our dataset: 12 emails (expanded for better training) ──
email_data = [
    {'contains_free': 1, 'contains_winner': 1, 'contains_prize': 1, 'is_spam': 1},  # Spam
    {'contains_free': 0, 'contains_winner': 0, 'contains_prize': 0, 'is_spam': 0},  # Ham
    {'contains_free': 1, 'contains_winner': 0, 'contains_prize': 0, 'is_spam': 0},  # Ham ("free shipping")
    {'contains_free': 0, 'contains_winner': 1, 'contains_prize': 1, 'is_spam': 1},  # Spam
    {'contains_free': 0, 'contains_winner': 0, 'contains_prize': 1, 'is_spam': 1},  # Spam
    {'contains_free': 0, 'contains_winner': 0, 'contains_prize': 0, 'is_spam': 0},  # Ham
    {'contains_free': 1, 'contains_winner': 1, 'contains_prize': 0, 'is_spam': 1},  # Spam
    {'contains_free': 1, 'contains_winner': 0, 'contains_prize': 1, 'is_spam': 1},  # Spam
    {'contains_free': 0, 'contains_winner': 1, 'contains_prize': 0, 'is_spam': 0},  # Ham ("winner of the quiz")
    {'contains_free': 0, 'contains_winner': 0, 'contains_prize': 0, 'is_spam': 0},  # Ham
    {'contains_free': 1, 'contains_winner': 1, 'contains_prize': 1, 'is_spam': 1},  # Spam
    {'contains_free': 0, 'contains_winner': 0, 'contains_prize': 1, 'is_spam': 1},  # Spam
]

# ── Create a Pandas DataFrame ──────────────────────
df = pd.DataFrame(email_data)

print("Our email dataset:")
print(df)
print(f"\nSpam emails: {df['is_spam'].sum()}")
print(f"Ham emails:  {len(df) - df['is_spam'].sum()}")

📤 Expected Output

Our email dataset:
    contains_free  contains_winner  contains_prize  is_spam
0               1                1               1        1
1               0                0               0        0
2               1                0               0        0
3               0                1               1        1
4               0                0               1        1
5               0                0               0        0
6               1                1               0        1
7               1                0               1        1
8               0                1               0        0
9               0                0               0        0
10              1                1               1        1
11              0                0               1        1

Spam emails: 7
Ham emails:  5

2 Data Structures & Algorithms — The Right Tools

Our DataFrame is a two-dimensional array structure — like a table. Internally, pandas stores this as a NumPy array, which enables fast mathematical operations on entire columns at once. This is essential for ML, where we might process millions of rows.

For a real-world spam filter checking against thousands of keywords, a Python set (based on a hash map) provides near-instant lookups — far faster than checking a list one by one.

# ── Using a Set for Fast Keyword Lookup ─────────────
# A set provides O(1) membership checking vs O(n) for a list

spam_keywords = {'free', 'winner', 'prize', 'congratulations',
                 'click here', 'act now', 'limited offer'}

# Test some words from an incoming email
test_words = ['hello', 'prize', 'meeting', 'free', 'report']

print("Keyword scan results:")
for word in test_words:
    result = "🔴 SPAM WORD" if word in spam_keywords else "🟢 Clean"
    print(ff"  '{word}': {result}")

# Count how many spam keywords are in the email
spam_count = sum(1 for w in test_words if w in spam_keywords)
print(ff"\nSpam keywords found: {spam_count}/{len(test_words)}")

Keyword scan results:
  'hello':   🟢 Clean
  'prize':   🔴 SPAM WORD
  'meeting': 🟢 Clean
  'free':    🔴 SPAM WORD
  'report':  🟢 Clean

Spam keywords found: 2/5

3 Algorithmic Problem Solving — The ML Blueprint

Every successful ML project follows a clear, repeatable workflow. Before writing any model code, you must understand the complete plan. Here is the blueprint we will follow:

4 Discrete Structures — The World of Categories

Unlike regression (which predicts a continuous number on an infinite scale), classification deals with discrete categories — a finite set of possible outputs. This is where discrete mathematics becomes essential.

Our classification model is formally a function:

The model maps an input vector of features to one value in the finite set {0, 1}.

The model learns weights for each feature. A high positive weight on contains_winner means that feature strongly pushes the prediction toward spam. A low weight means it barely matters. These weights define the decision boundary.

5 Calculus Essentials — The Sigmoid Function & Gradient Descent

How does Logistic Regression actually learn? It uses calculus to optimise its weights. Here is the intuition without going too deep into the maths:

The Sigmoid Function 📈

The model first computes a raw score z based on the input features and learned weights. It then passes this score through the Sigmoid function, which "squishes" any number into a value between 0 and 1 — a probability:

• If σ(z) > 0.5 → classify as Spam (1)
• If σ(z) ≤ 0.5 → classify as Not Spam (0)

For example, if the model computes a score of z = 3.0 for a suspicious email, the Sigmoid gives σ(3.0) ≈ 0.95 — a 95% probability of being spam! If z = -2.0, then σ(-2.0) ≈ 0.12 — only 12% chance of spam.

Gradient Descent — How the Model Learns ⛷️

The model starts with random weights (random guesses). It then:

1. Makes predictions on the training data
2. Calculates how wrong it is using a loss function (Log Loss for classification)
3. Uses calculus (the derivative/gradient) to figure out which direction to adjust each weight
4. Takes a small step in that direction (learning rate controls the step size)
5. Repeats thousands of times until the loss stops decreasing

The good news? scikit-learn handles all of this automatically! When you call model.fit(X, y), it runs thousands of gradient descent iterations internally and finds the best weights. You just call one line of code. ✨

6 Statistics — The Confusion Matrix & Evaluation Metrics

After training a model, how do we know if it is actually good? This is where statistics comes in. Simple accuracy (percentage of correct predictions) is misleading for imbalanced datasets.

The Confusion Matrix 🔲

A Confusion Matrix breaks down our model's predictions into four categories, giving us a much clearer picture of what is really happening:

Precision vs Recall 🎯

7 Machine Learning — Building the Final Classifier

Now we put it all together! We will use scikit-learn's LogisticRegression to train our spam classifier, split data properly with train_test_split, make predictions, and evaluate with the full metrics suite.

import pandas as pd
from sklearn.linear_model import LogisticRegression
from sklearn.model_selection import train_test_split
from sklearn.metrics import (accuracy_score, confusion_matrix,
                               precision_score, recall_score,
                               classification_report)

# ── 1. Prepare the dataset ──────────────────────────
email_data = [
    {'contains_free': 1, 'contains_winner': 1, 'contains_prize': 1, 'is_spam': 1},
    {'contains_free': 0, 'contains_winner': 0, 'contains_prize': 0, 'is_spam': 0},
    {'contains_free': 1, 'contains_winner': 0, 'contains_prize': 0, 'is_spam': 0},
    {'contains_free': 0, 'contains_winner': 1, 'contains_prize': 1, 'is_spam': 1},
    {'contains_free': 0, 'contains_winner': 0, 'contains_prize': 1, 'is_spam': 1},
    {'contains_free': 0, 'contains_winner': 0, 'contains_prize': 0, 'is_spam': 0},
    {'contains_free': 1, 'contains_winner': 1, 'contains_prize': 0, 'is_spam': 1},
    {'contains_free': 1, 'contains_winner': 0, 'contains_prize': 1, 'is_spam': 1},
    {'contains_free': 0, 'contains_winner': 1, 'contains_prize': 0, 'is_spam': 0},
    {'contains_free': 0, 'contains_winner': 0, 'contains_prize': 0, 'is_spam': 0},
    {'contains_free': 1, 'contains_winner': 1, 'contains_prize': 1, 'is_spam': 1},
    {'contains_free': 0, 'contains_winner': 0, 'contains_prize': 1, 'is_spam': 1},
]
df = pd.DataFrame(email_data)

# ── 2. Separate features (X) from label (y) ────────
X = df[['contains_free', 'contains_winner', 'contains_prize']]
y = df['is_spam']

# ── 3. Split data: 80% training, 20% testing ───────
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, random_state=42
)
print(f"Training samples: {len(X_train)} | Test samples: {len(X_test)}")

# ── 4. Create and train the model ──────────────────
model = LogisticRegression(random_state=42)
model.fit(X_train, y_train)  # The magic line — model learns here!
print("✅ Model training complete!")

# ── 5. Make predictions on test data ───────────────
y_pred = model.predict(X_test)

# ── 6. Evaluate performance ────────────────────────
accuracy  = accuracy_score(y_test, y_pred)
precision = precision_score(y_test, y_pred, zero_division=0)
recall    = recall_score(y_test, y_pred, zero_division=0)
conf_mat  = confusion_matrix(y_test, y_pred)

print(f"\n📊 Model Performance:")
print(f"   Accuracy:  {accuracy * 100:.1f}%")
print(f"   Precision: {precision * 100:.1f}%")
print(f"   Recall:    {recall * 100:.1f}%")
print(f"\nConfusion Matrix:")
print(conf_mat)
print("\nFull Report:")
print(classification_report(y_test, y_pred,
      target_names=['Not Spam', 'Spam']))

# ── 7. Predict a new email ──────────────────────────
print("\n=== Classify New Emails ===")
test_emails = [
    {"email": "FREE WINNER! Claim your PRIZE now!",  "features": [[1, 1, 1]]},
    {"email": "Team meeting tomorrow at 9am",          "features": [[0, 0, 0]]},
    {"email": "FREE shipping on your order #4521",     "features": [[1, 0, 0]]},
    {"email": "You are a WINNER! Claim your gift!",   "features": [[0, 1, 0]]},
]

for item in test_emails:
    prediction = model.predict(item["features"])[0]
    probability = model.predict_proba(item["features"])[0][1]
    verdict = "🔴 SPAM" if prediction == 1 else "🟢 NOT SPAM"
    print(ff"  {verdict} ({probability*100:.0f}% spam probability)")
    print(ff"  └─ \"{item['email']}\"\n")

📤 Understanding the Output

Training samples: 9 | Test samples: 3
✅ Model training complete!

📊 Model Performance:
   Accuracy:  100.0%
   Precision: 100.0%
   Recall:    100.0%

Confusion Matrix:
[[1 0]
 [0 2]]

Full Report:
              precision    recall  f1-score   support

    Not Spam       1.00      1.00      1.00         1
        Spam       1.00      1.00      1.00         2

    accuracy                           1.00         3

=== Classify New Emails ===
  🔴 SPAM (97% spam probability)
  └─ "FREE WINNER! Claim your PRIZE now!"

  🟢 NOT SPAM (4% spam probability)
  └─ "Team meeting tomorrow at 9am"

  🟢 NOT SPAM (31% spam probability)
  └─ "FREE shipping on your order #4521"

  🔴 SPAM (71% spam probability)
  └─ "You are a WINNER! Claim your gift!"

📖 Reading the Confusion Matrix

Our matrix [[1, 0], [0, 2]] means:

• 1 True Negative — 1 ham email correctly identified as ham ✅
• 0 False Positives — 0 ham emails wrongly called spam ✅
• 0 False Negatives — 0 spam emails were missed ✅
• 2 True Positives — 2 spam emails correctly caught ✅

🎬 Watch: Machine Learning Beginner Tutorial

Prefer learning by watching? This video gives a clear, visual explanation of Machine Learning fundamentals including classification, model training, and scikit-learn — perfect alongside this tutorial!

🎓 Machine Learning for Everybody — covers all core concepts including classification, model training, and evaluation. Watch alongside this tutorial for best results!

🛠️ How to Improve This Model

Our current model uses only 12 samples and 3 features. Here is how to make it production-grade:

🌍 Real-World ML Classification Applications

The exact same technique you just learned — training a binary classifier on labelled data — powers some of the most valuable technology in the world today:

🚀 Your Full-Stack AI Developer Path

This tutorial puts you firmly on the AI & full-stack development path. Here is where you are and where you are going:

❓ Frequently Asked Questions