Open-source smart mailbox alert system

Build MailFob with Raspberry Pi or Arduino

MailFob detects mailbox vibration, door opening, and optional mail photos using sensors, Home Assistant, and Raspberry Pi.

Start Pi Build Arduino Option
MailFob blue smart mailbox with raised red flag and wireless signal

Vibration Detection

Uses the SW-420 vibration sensor to detect mail drops, bumps, or mailbox movement.

Door Detection

Uses a reed switch magnetic sensor to detect when the mailbox door opens or closes.

Optional Camera AI

Add a separate Pi, Arduino, ESP32, or camera device to prevent overloading the sensor board power line.

1 Parts List

Main Raspberry Pi Build

Part Purpose
Raspberry Pi Zero 2 W Main MailFob controller
SW-420 Vibration Sensor Module Detects mailbox movement
Reed Sensor Module / Magnetic Switch Detects door open and close
MicroSD Card Stores Raspberry Pi OS
5V Power Supply or Battery Bank Powers the Pi
Weather-resistant Project Box Protects electronics

Optional Camera / AI Build

Part Purpose
Second Raspberry Pi, Arduino, ESP32, or Camera Device Keeps camera power separate from the sensor board
Raspberry Pi 5 Recommended for AI recognition
Raspberry Pi Camera Module Takes mail photos
Raspberry Pi AI HAT+ / AI HAT 2 Runs AI recognition
Separate Power Supply Prevents overloading the 3.3V rail
Weatherproof Camera Case Protects the camera outdoors
For camera or AI recognition, use a separate device. Do not force the Pi Zero 2 W sensor board, sensors, camera, and AI hardware to share the same 3.3V power line.

2 Raspberry Pi Zero 2 W Wiring

This is the recommended MailFob build. Use BCM GPIO numbering in the Python code.

SW-420 Vibration Sensor

SW-420 Pin Pi Pin
VCC 3.3V, physical pin 1
GND GND, physical pin 6
DO / OUT GPIO17, physical pin 11

Reed Switch Magnetic Sensor

Reed Sensor Pin Pi Pin
VCC 3.3V, physical pin 17
GND GND, physical pin 9
DO / OUT GPIO27, physical pin 13
Mount the SW-420 firmly to the mailbox body. Mount the reed switch near the mailbox door and the magnet on the moving door.

3 Raspberry Pi Setup

Install Raspberry Pi OS Lite, enable SSH, connect to Wi-Fi, then run these commands.

Bash
sudo apt update
sudo apt upgrade -y
sudo apt install python3-gpiozero python3-pip -y

mkdir ~/mailfob
cd ~/mailfob
After this, the Pi is ready for the MailFob Python script.

4 MailFob Python Code

Create a file called mailfob.py and paste this code.

Python
from gpiozero import DigitalInputDevice, LED
from signal import pause
from datetime import datetime
import time
import json

VIBRATION_PIN = 17
REED_PIN = 27
LED_PIN = 22

vibration = DigitalInputDevice(VIBRATION_PIN, pull_up=False)
reed = DigitalInputDevice(REED_PIN, pull_up=False)
status_led = LED(LED_PIN)

COOLDOWN_SECONDS = 20
last_alert_time = 0

LOG_FILE = "mailfob-events.jsonl"

def log_event(event_type, message):
    event = {
        "time": datetime.now().isoformat(),
        "event": event_type,
        "message": message
    }

    print(f"[{event['time']}] {event_type}: {message}")

    with open(LOG_FILE, "a") as f:
        f.write(json.dumps(event) + "\n")

def send_alert(reason):
    global last_alert_time

    now = time.time()

    if now - last_alert_time < COOLDOWN_SECONDS:
        return

    last_alert_time = now

    status_led.on()
    log_event("mail_detected", reason)

    # Add Home Assistant webhook, MQTT, email, or SMS here.

    time.sleep(2)
    status_led.off()

def vibration_detected():
    send_alert("Mailbox vibration detected. Mail may have arrived.")

def door_opened():
    send_alert("Mailbox door opened.")

def door_closed():
    log_event("door_closed", "Mailbox door closed.")

vibration.when_activated = vibration_detected
reed.when_activated = door_opened
reed.when_deactivated = door_closed

log_event("system_start", "MailFob is running.")
pause()

Run it:

Bash
python3 mailfob.py

5 Start MailFob on Boot

Create a system service so MailFob starts automatically when the Pi turns on.

Bash
sudo nano /etc/systemd/system/mailfob.service
systemd
[Unit]
Description=MailFob Smart Mailbox Alert
After=network-online.target

[Service]
ExecStart=/usr/bin/python3 /home/pi/mailfob/mailfob.py
WorkingDirectory=/home/pi/mailfob
Restart=always
User=pi

[Install]
WantedBy=multi-user.target
Bash
sudo systemctl enable mailfob.service
sudo systemctl start mailfob.service
sudo systemctl status mailfob.service

6 Home Assistant Webhook

MailFob can send an alert to Home Assistant when mail is detected.

Bash
pip3 install requests

Add this to the top of your Python file:

Python
import requests

HOME_ASSISTANT_WEBHOOK = "http://homeassistant.local:8123/api/webhook/mailfob"

Then add this inside send_alert():

Python
try:
    requests.post(HOME_ASSISTANT_WEBHOOK, json={
        "source": "MailFob",
        "reason": reason,
        "time": datetime.now().isoformat()
    }, timeout=5)
except Exception as e:
    log_event("webhook_error", str(e))

7 Arduino Option

You can also build MailFob with Arduino. For Wi-Fi alerts, use an ESP32 instead of a basic Arduino Uno.

Arduino Wiring

Sensor Arduino Pin
SW-420 OUT D2
Reed Switch OUT D3
SW-420 VCC 5V
Reed VCC 5V
GND GND

Arduino Code

Arduino / C++
const int vibrationPin = 2;
const int reedPin = 3;
const int ledPin = 13;

unsigned long lastAlert = 0;
const unsigned long cooldown = 20000;

void setup() {
  pinMode(vibrationPin, INPUT);
  pinMode(reedPin, INPUT);
  pinMode(ledPin, OUTPUT);

  Serial.begin(9600);
  Serial.println("MailFob Arduino started");
}

void loop() {
  int vibrationState = digitalRead(vibrationPin);
  int reedState = digitalRead(reedPin);

  if (millis() - lastAlert > cooldown) {
    if (vibrationState == HIGH) {
      alert("Mailbox vibration detected");
    }

    if (reedState == HIGH) {
      alert("Mailbox door opened");
    }
  }

  delay(100);
}

void alert(String message) {
  lastAlert = millis();

  digitalWrite(ledPin, HIGH);
  Serial.println(message);
  delay(1000);
  digitalWrite(ledPin, LOW);
}

8 Optional Camera and AI System

If you want pictures of the mail or mail carrier detection, use another Raspberry Pi, Arduino, ESP32, or camera-capable device. This keeps the MailFob sensor unit separate and avoids forcing the SW-420, reed switch, camera, and AI hardware to share the same 3.3V power line.

Important Camera Power Warning

If you want to add a camera system, use a separate Raspberry Pi, Arduino, ESP32, or camera-capable device instead of powering everything from the same small sensor board.

This helps prevent overloading or sharing the same 3.3V line. Drawing too much current from the 3.3V rail can cause unstable sensor readings, random shutdowns, damaged GPIO pins, or damage to boards and sensor modules.

Mailbox Sensor Unit

  • Raspberry Pi Zero 2 W
  • SW-420 vibration sensor
  • Reed switch magnetic sensor
  • Uses its own simple sensor power setup
  • Sends alert to Home Assistant

Camera / AI Unit

  • Use a separate Raspberry Pi, Arduino, ESP32, or camera device
  • Use its own power supply
  • Add a Raspberry Pi Camera Module or supported camera
  • Use Raspberry Pi 5 with AI HAT+ / AI HAT 2 for AI recognition
  • Do not overload the Pi Zero 2 W 3.3V rail
For recognition, it is better to say possible mail carrier detected instead of confirmed USPS worker because AI can be wrong.

9 How MailFob Works

Mailbox Opens
Sensor Triggers
Pi Sends Alert
Home Assistant
Phone Notification
Best setup: Pi Zero 2 W handles the mailbox sensors. A separate camera device handles pictures, video, or AI recognition. This keeps power safer and makes the system easier to upgrade.