How To Install Mail and Packages Integration Home Assistant

In this guide, I’m going to show you how to install and setup the Mail and Packages integration in Home Assistant. This integration will show a snapshot of mail and/or packages that are scheduled to arrive on a current day. It can even show a rotating gif of images (if those are provided by the shipper) directly on Lovelace.

This guide will require you to connect your email account to the integration, but I will walk you through how to do that below.

There are quite a few moving pieces to set this up, but in short, here’s what we’ll be doing in this tutorial:

• Installing the Mail and Packages integration from HACS
• Connecting the integration to your Gmail account / showing you how to create an “app password”
• Add new sensors to Lovelace
• Installing the Mail and Packages Custom Card (to display total deliveries, in transit, images, etc)

Let’s get started!

---

How It Works

Before I get started, I figured I should let you know how this integration works.

First, the Mail and Packages integration connects to an email account where your shipment notifications get sent to. It checks the subject lines for keywords or phrases that are typically used (For example, “Your Amazon.com order has shipped”), and uses that info to populate the integration.

To further secure this, you can create email rules or filters to move these shipment notifications to a subfolder if you’d like. Or, you can forward these notifications to a completely different email account that is only used for this purpose.

---

Step 1: Install Mail and Packages

First, you need to install the Mail and Packages integration from the Home Assistant Community Store (HACS). This can be done manually, but it’s much easier to install from HACS.

From your Home Assistant sidebar, click HACS > Integrations > Explore and Add Repositories.

Search for “Mail and Packages“.

Click the integration and then click Install This Repository in HACS. Once installed, you’ll need to reboot Home Assistant from Configuration > Server Controls.

---

Step 2: Create Gmail App Password

Next step is to create an “app password” to use with your Gmail account. For security purposes, you can’t supply just your email address and password, so creating an app password is required. 2FA is required to create an app password.

Go to your Gmail account. and select the Security tab.

Under Signing in to Google, click App Passwords.

It may prompt you to sign into your Google Account.

On the App Passwords screen, choose Select app and type “Home Assistant“. Then click Generate.

Copy the app password to your clipboard. Then go back to Home Assistant.

---

Step 3: Add Integration to HA

Now that Mail & Packages has been installed and your app password has been created, we need to add the integration to Home Assistant.

Configuration > Integrations > Add Integration. Search for Mail and Packages.

Click the integration and on the next screen (the Step 1 of 2 screen), enter the following values. For the password, use the app password, not your Gmail password.

• Host: imap.gmail.com
• Port: 993
• Username: your gmail email address
• Password: your newly generated app password

On the Step 2 of 2 screen, select the folder you want Mail and Packages to monitor (Inbox) and choose the sensors you want to add.

I shop at Amazon 99% of the time, so the sensors I added are:

• Mail Updated (required for Lovelace card!)
• Mail Amazon Packages
• Mail Amazon Packages Delivered
• Mail Amazon Hub Packages
• Mail Packages Delivered
• Mail Packages in Transit

You are welcome to add them all if they apply to you. You can always go back to Integrations page, click the 3 dots on Mail and Packages > System Options to add future shippers.

If you plan on setting up the rotating gif of mail/letters that have been mailed to you, you should also select all USPS sensors.

If you aren’t forwarding Amazon emails to a 2nd inbox, you can leave the “Amazon forwarded email addresses” field alone.

You can optionally check the two boxes for Create mp4 from images. I recommend clicking the create image for notifications.

Once complete, click Submit.

If all goes well, you should see a Success! message.

It should now show up in your Integrations list and you should see that a few new sensors have been created.

---

Step 4: Add Mail and Packages Sensors to Lovelace

To ensure the sensors are working correctly, click the blue entities link to view all of your entities. Then, add them to a Lovelace Entities card:

Displaying these in an Entities card isn’t the way to go, so the next step should be adding the Mail and Packages Custom Card.

---

Step 5: Install Custom Card

Go to HACS > Frontend > click the 3 dots in the top right corner > Custom Repositories.

Then, paste this URL: https://github.com/moralmunky/Home-Assistant-Mail-And-Packages-Custom-Card 

For the category, choose Lovelace.

Then click Add.

A new Frontend integration will appear. Click Install on it.

Then, add a new Manual card to Lovelace and paste this in:

type: 'custom:mail-and-packages-card'
name: Mail Summary
updated: sensor.mail_updated
details: true
image: false

Click the Show Visual Editor button.

You’ll then need to assign your different sensors, like this:

Or, you can paste in this code to the YAML config to the YAML code editor for the card:

type: custom:mail-and-packages-card
name: Mail Summary
details: true
image: false
amazon_packages: sensor.mail_amazon_packages
camera_entity: camera.mail_amazon_delivery_camera
gif_sensor: gif
updated: sensor.mail_updated
packages_in_transit: sensor.mail_packages_in_transit
packages_delivered: sensor.mail_amazon_packages_delivered
deliveries_message: camera.mail_amazon_delivery_camera
usps_mail: camera.mail_usps_camera
camera: true

This will now create a Lovelace card that looks like this, showing you any incoming deliveries + an image of already delivered packages!

---

Create GIF of Mail (USPS Informed Delivery Image)

If you’d like to display a rotating gif of images (i.e. – the actual letters that are being delivered to your mailbox), there’s a few extra things you need to do. More info on their wiki here.

First, you need set up USPS Informed Delivery. This will allow you to receive an email of all letters that are being delivered.

There are two ways you can set this up: using a gif (which is stored in the publicly accessible www folder), or create a local camera entity and an automation to update the images.

If you are just setting up USPS Informed Delivery, then you’ll have to wait a few days until you start receiving emails from USPS.

Option 1: Gif

Edit the card you just created. Under Camera Entity, use camera.mail_usps_camera (If you don’t have this entity, you’ll need to go back to the Integrations page, click the 3 dots on Mail and Packages > System Options to the USPS sensors)

And here’s the yaml for the USPS card:

type: custom:mail-and-packages-card
name: Mail Summary
details: true
image: false
amazon_packages: sensor.mail_amazon_packages
gif_sensor: gif
updated: sensor.mail_updated
packages_in_transit: sensor.mail_packages_in_transit
packages_delivered: sensor.mail_amazon_packages_delivered
deliveries_message: camera.mail_amazon_delivery_camera
usps_mail: camera.mail_usps_camera
camera: true
camera_entity: camera.mail_usps_camera

Option 2: Create Local Camera Entity + Automation

Go to File Editor > Configuration.yaml. If you don’t already have a camera: portion, add that first and then paste the below code.

  
- platform: local_file
    file_path: /config/custom_components/mail_and_packages/mail_none.gif
    name: mail_usps

Then, create an automation like this and restart Home Assistant:

alias: Update USPS Mail Camera Path on Hass Restart
trigger:
  - platform: state
    entity_id: sensor.mail_updated
  - platform: homeassistant
    event: start
action:
  - service: local_file.update_file_path
    data_template:
      entity_id: camera.mail_usps
      file_path: '{{ states(''sensor.mail_image_system_path'') }}'
mode: single

---

Wrapping Up

Overall, this was a really fun integration to setup. It’s great to be able to see if a package has been delivered today, or quickly see what has been shipped and is in transit.

There’s still more than I could add with this integration, such as:

• Displaying a rotating gif of images – i.e. – the actual items I purchased that show up in the emails)
• Add shipper logos instead of icons
• Creating automations to alert you when mail arrives, is in transit, etc

But for now, I hope this guide gets you started! I will probably create a separate post and link it to this guide once I get some of those extras setup. There’s also an incredibly long Community Form Post with more info regarding this integration.