#6: How many packages do I have? Using email readers and Home Assistant!
Home Assistant Automation

#6: How many packages do I have? Using email readers and Home Assistant!

William Zink

Introduction

I will start by saying that I cannot stand email, my goal is to have a Zero Inbox at all times, and with this mentality you have to figure out what is actionable and what isn't. One of the ways emails would pile up is if I was on vacation, emails about packages (UPS, USPS, FedEx) would arrive and I would just leave them in my inbox until I got back. Well, I felt like I could come up with a better solution than that right?? So here's how I did it.

TL;DR: In this post I start from scratch to create a sensor to tell me how many packages that I have received since I have been gone, how many I have received for the year, and a nice friendly alert when I get home to go pick them up!

The Goal

The goal is to be able to incrementally add packages that come via several emails. For example, if I am gone for a week, and I receive 2 different emails about 2 different packages during that timeframe. My goal would be to have one notification when I get back that I have two packages waiting for me to pick up. This way I know what to expect when going to pick them up.

Requirements

So to configure all of the pieces together we will need quite a few things to get all the end result that I am looking for.

The absolute first thing we need to setup is the IMAP Email Reader sensor - IMAP (Internet Message Access Protocol) is a protocol that allows a client to access emails. For my case I will be using Gmail, so IMAP is a way for Home Assistant to communicate with Gmail over port 993.

The next thing we need to do is setup (2) Input Numbers in Home Assistant. These two will manage the different states that I want to keep track of. The first being how many packages I have received since I have been gone. The second how many packages I have received for the year. Home Assistant lets us interact with this input number by incrementing it's value (by the step number defined in the config) or quickly setting it to a value (which I will use to set to zero to reset the counter).

The last piece of the puzzle is tying these two pieces together. I am going to use Node-Red to handle the automations, but I need a sensor that will read the email body and tell me how many packages I have received per email. I will create a Node-Red automation that says anytime a new email comes in, read how many packages I have for that single email. So this last component will create the 'glue' that will read the body of the email, and know what to increment my counter by.

In Home Assistant

1) We need to add our Home Assistant - IMAP Email Content Integration sensor so that Home Assistant can read our emails and put them into a sensor for us. For this instance I am using Google's Gmail.
Note: My format my look a little different as I break everything out into component yaml files. Source Code for my IMAP Component

- platform: imap_email_content
  server: imap.gmail.com
  name: pickup_packages_email
  port: 993
  username: !secret my_gmail_address
  password: !secret my_gmail_password
  senders:
    - !secret concierge_email_address

For the password we are going to follow the steps for the setting up IMAP with Gmail and generate an App Password.

Note from Google:

An App Password is a 16-digit passcode that gives a less secure app or device permission to access your Google Account. App Passwords can only be used with accounts that have 2-Step Verification turned on.

I am not defining a folder as Inbox is the default and works in my case, but if you want to specify there is an option for that.
I am also using a secret file for username and password. I would suggest doing the same. It's a good practice. Plus I store my code in the cloud and the less usernames and passwords out there the better.

2) Let's add our first input number to store how many packages I have received while I was not at the condo. I could be gone for multiple days so let's make it a bigger number.
Note: I put these two in the same file but you can separate them however you please. Source code for my input numbers

away_packages_received:
  name: 'Packages Arrived While Away'
  initial: 0
  min: 0
  max: 255
  step: 1
  icon: mdi:gift-off

3) The second input number will store our yearly packages, this is completely unnecessary but I am just curious to how many I get in the given year. We will just write a quick automation to clear the number to zero on December 31st.

yearly_packages_received:
  name: 'Total yearly packages received'
  initial: 0
  min: 0
  max: 1500
  step: 1
  icon: mdi:gift

4) The glue sensors that I was talking about earlier. These sensors will read the email...

We will use a regular expression to pull the number of packages, and then store it in this sensor. After we store it here, we will increment our number with the number of packages.

The template sensor that will be doing the work
Source Control for template sensor (near the bottom)

    package_items_found:
      friendly_name: Package Items Found In Email
      value_template: >
        {{ state_attr('sensor.pickup_packages_email', 'body')
          |regex_findall_index("([0-9.]) item\(s\)") }}

5) This is an important one!! Getting packages into your email
Sign up for USPS informed delivery, it's free and worth it, it will email you information about your packages.
https://informeddelivery.usps.com/box/pages/intro/start.action
Note: I have a central system (my concierge emails me personally) but this is a great piece of communication if you don't have it.

Here is a link to the entire commit in Git

Let's Test!

First let's check our IMAP sensor to make sure the email is being imported!

Second let's test our value template sensor!

Boom! Let's jump on to Node-Red!

Automations

Now that all of our pieces in Home Assistant are setup for us. We will check to see if the date of the email changes. When that change happens, we will see how many packages are in the email and increment our counter by that amount. It's that easy! So let's go to Node-Red

The way the input number API is handled in Home Assistant we have to define a step so each time we increment the value will increase by that number. This isn't a problem we will just call the increment the amount of times that was defined by package_items_found.

Test scenario
Loop Node

Now that our testing is complete, let's finish this up!

First automation

Stepping through this first automation
1) If we receive a new email
2) get the number of packages in our sensor variable (package_items_found)
3) Increment the yearly count no matter what
4) If I am not home, then increment the away packages count.
Not too bad

Second Automation

Second automation, at December 30th (NYE I'm busy) clear the yearly variable out and send a notification. Here we will bring in the cron-plus palate into Node-Red.

Third Automation

The last automation is just for messaging when I get home. When my person gets home it will come into the far left arrow.
1) Check the away package count
2) If it's zero it will not modify the message
3) if it's above zero it will add 'There is {{payload}} package(s) 📦 for pickup.'
4) it will set the away counter back to zero.

And that's it! Now I can delete those pesky delivery notification emails!

Conclusion

Here is a picture of the notification!

I hope you enjoyed this in-depth run through of automating reading an email and setting a counter on it. Let me know if you have any questions or need to see the nodes in more depth.

Merry Christmas!!!

Question?

What are some uses you have for this?