[RELEASE] Advanced Mail Monitor - State-Aware Tracking, Dashboard, & Secondary Delivery Logic

🚧 Developers Vibe-Code
1

I’m releasing a new app I put together to solve the headaches of standard mailbox monitoring.

Most of us start by tying a simple Rule Machine rule to a contact sensor on the mailbox: If open, announce "Mail is here!" But that simple logic usually falls apart in the real world. The mail carrier opens the box three times to fit a package in, or the UPS guy drops off a secondary delivery hours later, and suddenly your house thinks you retrieved the mail when you actually didn't.

Advanced Mail Monitor is designed to be a true state machine. It doesn't just look for "open/close" events; it uses heuristic logic to figure out what that open event actually means.

:sparkles: Key Features

  • Built-in Live Dashboard: No need to build a separate Tile. The app features a live HTML dashboard right inside the configuration page. It shows today’s delivery/retrieval times, historical averages, contact sensor battery health, and current state.
  • Secondary Delivery Protection (The Interlock): This is the killer feature. You can select exterior doors (Front, Garage) or Mobile Presence sensors. If the mailbox opens, but no one has arrived home or opened a door recently, the app knows it's a second delivery (like UPS/FedEx) and won't falsely log it as a retrieval.
  • Carrier Lockout Timer: Prevents a barrage of notifications if your mail carrier opens and closes the box multiple times while organizing packages.
  • Temperature Tracking: If you have a sensor that reports temperature, the app will monitor the internal heat of the box. It sends a daily warning if the temp exceeds your threshold while mail is waiting (great for protecting medications or electronics in the summer heat).
  • End-of-Day Nag Reminders: Forgot to grab the mail? Set a time, and the app will check if the mail is still waiting and hit you with a push notification or TTS announcement.
  • Security Alerts: Define a nighttime security window. If the box opens at 2:00 AM, it bypasses the normal logic and immediately sends a security alert.
  • Deep Notification Integration: * TTS Smart Speaker announcements (different messages for delivery vs. retrieval).
    • Color RGB bulb support (turns a specific color when mail is waiting, turns off when retrieved).
    • Native Inovelli LED notification support.
  • In-App History Log: Keeps a rolling log of the last 20 events (Deliveries, Retrievals, Lockouts, Battery warnings) directly in the app UI for easy troubleshooting.

:gear: Installation

  1. Open your Hubitat Elevation hub.
  2. Go to Apps Code -> New App.
  3. Paste the code from the link below.
  4. Click Save, then click the OAuth button (if you use external dashboards, otherwise optional).
  5. Go to Apps -> Add User App and select Advanced Mail Monitor.

(https://raw.githubusercontent.com/ShaneAllen334/Hubitat_Apps/refs/heads/main/Advanced_Mail_Monitor/Advanced_Mail_Monitor.groovy)

:memo: Open Source / Do What You Want

I built this to fit how my house operates, but I know everyone's setup is different. Anyone can use this code, steal from it, or edit it. Feel free to rip out the dashboard HTML for your own apps, modify the state machine, or fork it entirely. If you add something cool, drop a comment below so the rest of us can see it!

2

New Features:

  • State Capture & Restore Engine: The app now takes a "snapshot" of the exact state of your indicator lights (including hue, saturation, level, and color temperature, or even if they were simply OFF) the moment the mail is delivered. When you retrieve the mail, it perfectly restores the lights to their previous state rather than just blindly turning them off.
  • Dedicated External Overrides UI: Added a brand new "Integration & External Overrides" settings section. This cleanly exposes a "State Override Switch" that you can map to external apps (like Motion Lighting) to completely freeze them while the mail notification is active.
  • Priority Yielding: The app is now fully aware of higher-priority automation sequences (like the School Bus tracker). If mail is delivered while the School app is actively blinking the lights, the Mail Monitor will log the delivery and send phone push alerts, but it will patiently wait in the background. The second the School app finishes, the Mail app automatically steps in, takes over the lights, and displays the mail notification.
3

I've been tweaking things behind the scenes and today I've released the latest code with the following bug fixes and features:

:bar_chart: Live System & Telemetry Dashboard

  • Historical Average Tracking: Calculates and displays your running historical average time for both Mail Delivery and Mail Retrieval.
  • Today's Timestamps: Logs the exact time of today's delivery and retrieval events directly on the UI.
  • Trip Time Calculator: Displays your "Last Retrieval Walk Time" in minutes and seconds, measuring the exact duration between your front door opening and the mailbox opening.
  • Hardware Health Matrix: Live table showing the open/close state of all mailbox sensors, dynamically color-coding battery percentages (turns Orange at <50%, Red at <15%).
  • Thermal Telemetry: Displays the internal temperature of the mailbox. If no internal sensor is available, it automatically calculates an estimated internal temperature using your outside weather sensor plus a user-defined heat offset.
  • System State Indicator: Clear visual readout showing if the system is "WAITING FOR DELIVERY" or "MAIL WAITING."
  • Event Log: Stores and displays the last 20 system actions, overrides, and sensor triggers with exact timestamps.
  • Manual Data Management: Dedicated buttons to force-clear current mail status, or wipe all historical averages and logs to start fresh.

:brain: Advanced Core Logic & False Alarm Protection

  • Bouncing Door Debounce: Employs a hard hardware-lockout timer (in minutes) to prevent a bouncing mailbox door, or a carrier shoving multiple packages in, from triggering 10 consecutive delivery alerts.
  • Outgoing Mail Filter (Time Windows): Restrict delivery detection to a specific daily time window (e.g., 10:00 AM to 5:00 PM). Opening the box to drop off outgoing mail in the early morning is completely ignored.
  • Secondary Check (False Retrieval Protection): Links to your home's exterior doors and mobile arrival sensors. If the mailbox opens while mail is waiting, but no one has opened a house door or arrived home in the last X minutes, the app classifies it as the mail carrier dropping off additional items, logging a "More Mail Delivered" event instead of a false retrieval.

:bulb: Visual Indicators & Ecosystem Interlocks

  • State Capture & Restore: When mail arrives, designated RGB bulbs change to a specific alert color and brightness. Upon retrieval, the app seamlessly restores the bulbs to their exact previous hue, saturation, level, and color temperature.
  • Native Inovelli Support: Deep integration for Inovelli Red Series switches. Allows you to target specific individual LEDs (1 through 7) or the entire LED bar for visual alerts.
  • External App Freeze Switch: Triggers a specific virtual switch during delivery that you can use to "freeze" external motion-lighting apps, preventing them from turning off your mail indicator lights when a room goes vacant.
  • Priority Yielding: If a higher-priority application (like a School Bus countdown) is currently utilizing your indicator lights, the Mail Monitor will track the delivery but wait to fire its visual alerts until the priority sequence finishes.

:loud_sound: 1-to-1 Spatial Audio & Room Mapping

  • Motion-Tracked Audio: Map up to 7 specific smart speakers or Zooz Chimes directly to 7 specific room motion sensors.
  • Dynamic Interception: When mail arrives, the app evaluates real-time house telemetry. It only sends the TTS announcement or Chime to rooms where human movement was recently detected, preventing audio from blasting into empty rooms.
  • Adjustable Audio Timeout: Set how many minutes a room must be vacant before it is muted (prevents muting if someone is just sitting perfectly still reading).
  • "Always On" Override: Designate one master room (e.g., Living Room) that will always play announcements regardless of motion.

:bell: Announcements, Notifications & Nags

  • Multi-Event Audio Routing: Separate custom TTS text and Zooz sound file assignments for "Delivery," "More Mail Arrived," and "Retrieval."
  • Targeted Push Notifications: Independent toggles to send push alerts to your mobile devices for deliveries and/or retrievals.
  • Single Daily Nag: Schedule a one-time daily TTS/Push reminder at a specific time if the mail is still sitting in the box.
  • Hourly Mode-Restricted Nag: A persistent hourly reminder that only executes if the hub is currently in user-approved modes (e.g., "Evening" or "Home"), preventing hourly nags while you are at work or asleep. Features its own dedicated TTS text and Zooz chime sound.
  • Thermal Melt-Warning: If the internal mailbox temperature exceeds a critical threshold (e.g., 90°F) while mail is waiting, the system fires a high-priority push notification advising you to retrieve sensitive packages (medications, electronics) before they are damaged by heat.

:shield: Security & State Management

  • Midnight Auto-Reset: Optional toggle to automatically wipe the "Mail Waiting" status at midnight. If you leave mail in the box overnight, this ensures tomorrow's delivery isn't falsely logged as a retrieval.
  • Atomic Database Locks: Prevents parallel execution and race conditions if two mailbox contact sensors trigger within milliseconds of each other.

The latest version with all recent bug fixes and features is available on GitHub.

App:
raw.githubusercontent.com/ShaneAllen334/Hubitat_Apps/refs/heads/main/Advanced_Mail_Monitor/Advanced_Mail_Monitor.groovy