🏠 Integrating PuffiMail with Home Assistant¶

PuffiMail is designed to work seamlessly with Home Assistant using MQTT and auto-discovery. Once connected, it will appear in your Home Assistant dashboard with no manual YAML configuration needed.

✅ Requirements¶

A working MQTT Broker (e.g. Mosquitto) configured in Home Assistant
Home Assistant must be connected to the same network as PuffiMail
PuffiMail must have MQTT settings (server, username/password) correctly configured via its web interface

puffimail Home Assistant MQTT

📡 MQTT Auto-Discovery¶

When MQTT connection is established, PuffiMail publishes the following topics:

Entity	MQTT Topic	Type
`sensor.puffimail_distance`	`mailbox-sensor/distance`	JSON sensor with `{ current, baseline }`
`sensor.puffimail_status`	`mailbox-sensor/mail_status`	Enum sensor: `new_mail`, `empty`, `unknown`
`binary_sensor.puffimail_battery`	`mailbox-sensor/battery`	Battery indicator: `normal` / `low_battery`
`sensor.puffimail_availability`	`mailbox-sensor/availability`	Status: `online`

You can find these sensors under Settings > Devices & Services > MQTT in Home Assistant.

🛠 Example Automations¶

📬 Notify when new mail arrives¶

alias: Notify New Mail
trigger:
  - platform: state
    entity_id: sensor.puffimail_status
    to: "new_mail"
action:
  - service: notify.mobile_app_yourphone
    data:
      message: "📬 You have new mail in your PuffiMail mailbox!"
mode: single