Home

Home Assistant Mail and Packages

The Mail and Packages integration connects to your email server via IMAP (supporting standard password and OAuth2 authentication) to parse delivery notifications and expose mail and package tracking sensors and camera entities in Home Assistant. All processing occurs locally on your Home Assistant instance.

---

Features

• Package Tracking: Per-shipper sensors for packages in transit, delivered, and exceptions.
• USPS Informed Delivery: Mail piece counts, rotating GIF, and grid images of today's mail scans.
• Dedicated Camera Entities: Built-in camera entities for USPS and carrier delivery images.
• OAuth2 Authentication: Supports standard IMAP credentials as well as OAuth2 authentication for Gmail and Outlook/Microsoft 365.
• Email Forwarding: Support for email forwarding services (e.g. SimpleLogin, AnonAddy) via forwarding headers or address lists.
• AI Vision Grid: Static grid image generation (sensor.mail_grid_image_path) for use with AI vision models (e.g., Gemini, LLM Vision).
• 100% Local Processing: All processing occurs locally on your Home Assistant instance. No data leaves your network.

---

How It Works

1. Email Parsing: The integration connects to your email account over IMAP (using password or OAuth2 authentication) and searches for subject lines and body text matching supported carriers.
2. In-Transit Sensors (_delivering): Searches a configurable window of past days (default: 3) so packages shipped prior to today remain tracked until delivered.
3. Delivered Sensors (_delivered): Counts delivery notification emails received today and resets at midnight local time.
4. Summary & Total Sensors: Aggregate sensors (sensor.mail_packages_in_transit and sensor.mail_packages_delivered) combine counts across all enabled carriers (USPS, FedEx, UPS, Amazon, DHL, Walmart, etc.).

Note

The integration does not delete or modify your emails. Do not delete delivery emails on the day they arrive, as the integration needs to find them during its scans. To keep your primary inbox clean, you can use email rules to filter shipping emails into a dedicated folder and point the integration at that folder.

---

Amazon & Carrier Shipping

Amazon uses several third-party carriers (USPS, UPS, FedEx) as well as its own logistics network.

• When Amazon ships via a third-party carrier, the shipment is tracked under that carrier's sensors.
• When Amazon delivers via its own network, notifications with expected arrival dates are tracked under Amazon sensors (sensor.mail_amazon_packages).
• Amazon package counts are automatically included in total package counts (sensor.mail_packages_in_transit and sensor.mail_packages_delivered).

---

Wiki Documentation Index

Guide	Description
Configuration & Email Settings	Complete setup guide for IMAP, OAuth2, folders, and scan options.
Supported Shipper Requirements	Setup steps and notification requirements for all supported carriers.
Mail Summary Message	Jinja2 summary templates for Voice/TTS, sensors, and Lovelace cards.
Notification Examples	Automation examples for iOS, Android, TTS, and Home Assistant notifications.
USPS Informed Delivery Image	Details on rotating GIF, static grid, and camera entities.
Email Forwarding	How to configure email forwarding (forwarding headers & address lists).
AI Mail Summary	Integrating the grid image sensor with AI vision models (e.g. Gemini).
Troubleshooting	Common issues, debug logging, and resolution steps.