# Home Assistant Mail and Packages: shipping counts from your own inbox > This Home Assistant custom integration reads the shipment notification emails in a mailbox you point it at, counts what is in transit and what has been delivered for the current day, and turns USPS Informed Delivery images into a rotating GIF on a dashboard. Everything runs locally, and the price is that the source of truth is a set of subject line patterns rather than a carrier API. **moralmunky/Home-Assistant-Mail-And-Packages** — Home Assistant integration providing day of package counts and USPS informed delivery images. - Repository: https://github.com/moralmunky/Home-Assistant-Mail-And-Packages - Stars: 895 · Forks: 140 - Language: Python - License: MIT - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/moralmunky-home-assistant-mail-and-packages ## The problem: knowing what is arriving without opening a mail app A parcel notification arrives, you glance at it, and the useful question is not where the parcel is but how much is coming today and how much has already arrived. Home Assistant is very good at putting a number on a dashboard, and very bad at knowing about your post. The Mail and Packages integration fills that gap. It creates sensors for supported shippers that show a snapshot of the mail and packages scheduled to be delivered on the current day, and for those packages it provides a count of in transit and delivered packages. It also generates the number of USPS mail pieces and provides a rotating GIF of the images USPS supplies of the mail, if available, for the current day. The audience is specific: a Home Assistant user in the United States, or in a country where the supported carriers send notification emails, who wants their delivery count on a Lovelace card next to the thermostat. The repository topics are the honest summary, home assistant, home assistant config, home automation, lovelace card and lovelace custom card, because most of the value of this integration is what it puts on a dashboard. The licence is MIT, the integration is published as a HACS default integration, and the last push was on 2026-10-20, with releases 0.6.9-b9 on the same day, 0.6.9-b8 and 0.6.9-b7 the day before. The beta suffixes are worth noting: this is a project that ships pre-release builds into the default HACS channel, so a user can get a beta without asking for one. ## The mechanism: subject lines, not carrier APIs The way it works is the interesting part, and it is also the constraint. From your instance of Home Assistant, the integration connects to the email account you point it at, which is the account where your shipment notifications are sent. It reviews the subject lines of the current day's emails from the supported shippers and counts the subject lines that match known language from those shippers about their transit status. For USPS Informed Delivery emails it also downloads the mail images and combines them into a rotating GIF. There is no carrier API, no tracking number poll and no scraping of a carrier's web page. The integration's knowledge of the world is a list of subject line patterns, and the wiki page on Supported Shipper Requirements is where that list lives. That has two consequences. A shipper that changes its subject line format breaks the counts until the patterns are updated, and a carrier that is not in the list produces nothing at all. The upside is that there is no third party in the loop. The documentation is explicit about it: all procedures are done locally on your machine, no external services are used to process your email, and no data is sent outside of your local instance of Home Assistant. The only dependency of note in the requirements file is small, which is what you would expect from an integration that downloads a few images and assembles them: ```text imageio python-resize-image ``` The repository structure is the standard Home Assistant custom component layout, with a custom_components/ directory, a hacs.json for the store metadata, an info.md description, resources/ for icons, a docs/ directory, tests/ and a test.py entry point, and a tox.ini with a .devcontainer/ for local development. There is also a pylintrc, a requirements_format.txt and a requirements_test.txt, and an AUTHORS file. ## The day boundary, and the rule that email cannot be deleted Two rules govern the lifecycle of the data, and both are consequences of counting mail rather than tracking parcels. The first is that the email can not be deleted until the next day. The integration reads the current day's messages, and once it has counted them, the messages themselves are no longer needed, but deleting them is the user's job. The documentation's suggestion is to have your email filtered into a folder and have the integration watch that folder, which keeps the noise out of your main inbox and makes the retention rule easy to honour. The second is the reset. The image will revert back to the no mail graphic after the first email check after midnight, local time. So the GIF you see in the morning is a snapshot of today's mail and nothing else, and the sensors reset on a local midnight boundary rather than on a UTC one, which matters if your day is not the same as the carriers' day. This design has a real consequence for automation. Because the counts are derived from a mailbox, the integration is really a poller over a filtered folder, and the reliability of your dashboard is the reliability of your mail provider and of the filter rule. If a carrier sends a notification that lands in another folder, or if the subject line changes, the count silently goes to zero rather than raising an error, and there is no upstream to tell you the data is missing. That is the price of the privacy model, and the documentation is upfront about it rather than pretending the integration has a direct line to the carrier. ## The USPS Informed Delivery image and the two sensors that expose it The USPS piece is a different mechanism from the package counting, and it is the part that produces the visual output. Informed Delivery sends a daily email with a scanned image of the mail that is due to be delivered. The integration downloads those images and combines them into a rotating GIF for the current day, which is a small and rather good use of an image service that most people delete without reading. Getting that image onto a dashboard requires the integration to write a file that the front end can fetch, and that is where the privacy note matters. Files stored in the www Home Assistant folder are publicly accessible unless you have taken security measures outside of Home Assistant to secure it. The documentation's advice is to increase security and simplicity at the same time: the USPS Informed Delivery image name is random by default and there is no longer an option to turn that on or off, so a predictable filename that could be guessed is no longer the exposure. Two sensors were created to make the image usable in different places: - sensor.mail_image_system_path, which gives the local file path. - sensor.mail_image_url, which gives a web accessible url, and requires that either External_URL or Internal_URL is defined in the general configuration options in Home Assistant. So the image can be used for displaying or sending through the various Home Assistant notification methods, whether you want a local path for a camera-style entity or a url for a phone notification. The template and example pages in the wiki cover the Informed Delivery image, a text summary message for people who do not want an image, and a notifications page. ## Installing it, and the configuration pages you will actually need The integration is distributed as a HACS default integration, so the installation path for a Home Assistant user is the standard one: add the repository through HACS, install it, and restart. The store badge in the project description marks it as a default integration rather than one that has to be added as a custom repository. After that, the real work is configuration, and the wiki carries it. The pages linked from the project description are: Configuration and Email Settings, Troubleshooting, and Supported Shipper Requirements, which is the list that determines which carriers produce any sensors at all. There are also template pages for the USPS Informed Delivery image, a mail summary message, and notifications. The configuration question that trips people up is which mailbox to point at. The integration connects to the email account where shipment notifications are sent, and it is designed to watch a folder rather than a whole inbox, so you need a filter rule that puts carrier mail in one place and an account whose credentials the integration can use. The email settings page in the wiki is the reference for that, and the troubleshooting page is where to look when the counts are zero, which is almost always a filter or a subject line issue rather than a bug. The project also has continuous integration worth noticing: a Pytest workflow, a CodeQL workflow, a Validate with hassfest workflow, which is the check that your manifest and services are valid for the Home Assistant release, and a codecov badge. The devcontainer configuration and tox.ini mean you can run the same checks locally. The maintenance badge on the project description is worth a second look, because it says 2022, while the releases in the repository are from October 2026 and the last push is the same day. The project description credits huge contributions from @firstof9 for moving the project forward and keeping it active, which suggests the badge is stale rather than the project abandoned. ## Where it is the wrong tool, and what to check before you trust the count The honest limits of this integration follow from its mechanism. If you need numbers that a carrier would recognise, this is the wrong tool. The counts are derived from subject line patterns, so they reflect what the carrier chose to put in the subject line, which may be a rounding of the real count, may not cover every package, and may break without warning when the carrier changes its wording. If you do not want an email credential in Home Assistant, it is also the wrong tool, because reading a mailbox is the whole design. There is no alternative path described in the documentation that avoids giving the integration access to an account. And if you intend to expose the instance to the internet, you have to deal with the www folder, because that is where the USPS image lands, and the documentation is explicit that those files are publicly accessible without measures taken outside Home Assistant. For a team evaluating it, three checks come first. Read the Supported Shipper Requirements page and confirm that your carrier is listed and that its notification language is among the recognised patterns. Set up the dedicated folder and filter, so that the rule that email cannot be deleted until the next day is something you control rather than something you have to remember. And decide how you will secure the instance, or restrict the www folder, before the first Informed Delivery image is written. With those three done, the integration is straightforward: it counts what is in transit and what has been delivered for the day, gives you a USPS mail count and a rotating image, and never sends your mail anywhere. That is a small, well documented and genuinely local piece of Home Assistant automation. ## Conclusion Adopt this integration if you want package counts on a Home Assistant dashboard without giving a carrier or a third party service your tracking data, and if you are willing to point it at a dedicated mailbox folder. Do not adopt it if you need carrier API accuracy, since the counts come from subject line matching, and do not expose the www folder on the public internet without securing it, because the USPS image file is written there. Before you install, read the Supported Shipper Requirements page, check that your shipper's notification language is in the list, and set up a folder that the integration can watch without you having to delete mail by hand. ## FAQ ### How does the Home Assistant Mail and Packages integration get its data? It connects to the email account you supply, reviews the subject lines of the current day's emails from the supported shippers, and counts those that match known language about their transit status. For USPS Informed Delivery emails it also downloads the mail images and combines them into a rotating GIF. ### Does the integration send my email data to an external service? No. The documentation states that all procedures are done locally on your machine, that no external services are used to process your email, and that no data is sent outside of your local instance of Home Assistant. ### Why do the counts reset at midnight, and why can I not delete the email straight away? The image reverts to the no mail graphic after the first email check after midnight, local time, because the sensors describe the current day only. The email can not be deleted until the next day, and the documentation recommends filtering your mail into a folder and having the integration watch that folder. ### How do I display the USPS Informed Delivery image in Home Assistant? Two sensors are provided, sensor.mail_image_system_path with the local file path and sensor.mail_image_url with a web accessible url, and the url sensor requires External_URL or Internal_URL to be defined in the general configuration options. The image file is written to the www folder, whose contents are publicly accessible unless you secure them outside Home Assistant. ### How do I install the Mail and Packages integration? It is published as a HACS default integration, so it is installed through HACS and then configured from the wiki pages on Configuration and Email Settings, Troubleshooting and Supported Shipper Requirements. The project ships Pytest, CodeQL and hassfest validation workflows, with a tox.ini and a devcontainer for local development. ## Sources - [Issues](https://github.com/moralmunky/Home-Assistant-Mail-And-Packages/issues) - [License: MIT](https://github.com/moralmunky/Home-Assistant-Mail-And-Packages/blob/master/LICENSE) - [moralmunky/Home-Assistant-Mail-And-Packages on GitHub](https://github.com/moralmunky/Home-Assistant-Mail-And-Packages) - [README](https://github.com/moralmunky/Home-Assistant-Mail-And-Packages/blob/master/README.md) - [Releases](https://github.com/moralmunky/Home-Assistant-Mail-And-Packages/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/moralmunky-home-assistant-mail-and-packages