Sharing Gmail script to trigger Hubitat maker-api from received emails

I've been looking for the holy grail for years that would allow proprietary alarm systems (like vivint, alarm.com etc) to send one way notifications on the state of the system (alarms, arming, contact sensors, door lock state etc) to a smart hub from email notifications from the alarm service (since the IFTTT ability was lost). There seems to be a number of solutions out there, most of which require one of a paid subscription service, or a raspberry pi or some other always on devices, or a dedicated phone/tablet receiving push notifications that can trigger a listening app. Inspired by an old Reddit post by /Godbeard who wrote a gmail script that can do this natively within gmail (for IFFT triggers in that case), I've modified the code (my first foray into google app coding!) and written a simple script that will search my (dedicated) inbox every minute for a particular notification from alarm.com, and from that trigger a webhook in maker api. It may not be the entirely local, instantaneous holy grail, but I think it will work for me, and should be easy for anyone else to implement following these instructions. Yes I use the great ADC integration for system alarm control, but this specifically allows me to track current state of locks, door sensors or any number of other alarm.com devices on a hubitat dashboard or in rules. I'm attaching a link to the simple script if anyone else wants to try it. I'm in the process of writing a more complex one that will poll for the current status (most recent notification) on all 5 of my door locks. Will share when it's done.

The script template: https://script.google.com/d/1mybHQhtuq-Hsxb3WGxN0WLCAhnZBzOMmcPFi-UZlOvOatut-93UBwA6b/edit?usp=sharing

Installation instructions:

1- Setup gmail tags on incoming email notifications
ā€¢ Copy the subject line of the notification message
ā€¢ Click the settings gear- "see all settings"- "Filters and Blocked Addresses"
ā€¢ Create a new filter
ā—‹ Paste the copied text into the subject line and press create
ā—‹ Select "apply label" and create the label name you want applied.
ā€¢ Now this label will be automatically applied when matching subject emails arrive

2- Setup the webhook URLs of the device you want triggered in Hubitat.
ā€¢ Using maker api, add the devices you want to control.
ā€¢ Be sure to enable cloud URLs. These are the webhook addresses you will use in the google script.

3- Create a Google app script
ā€¢ Again settings gear- See all settings
ā€¢ Select "add-ons" and click on "Apps Script"
ā€¢ Press "New Project"
ā€¢ Copy the script from the sample app, and paste it (over-write what is there) in the new script window.
ā€¢ Rename it if you wish, and press save.

4- Customize the script
ā€¢ Enter the exact text of the filter label you created in gmail as the TriggerLabel variable text (between the parentheses).
ā€¢ Copy and paste the exact webhook URL from maker api to be triggered as the CalledAPI variable text (between the parentheses).
ā€¢ Comment or uncomment the last 2 lines ( // is the comment symbol) as per your preference. You must chose at least one of these, or the script will not distinguish between old and new messages. Only one is needed.
ā—‹ Label.removeFromThreads will remove the label from the message, but not delete it.
ā—‹ GmailApp.moveThreadsToTrash will delete the message entirely after the script runs. This keeps the inbox cleaner.

5- Set-up the script to run
ā€¢ Save and press "Run." You will need to grant permission for this untrusted (i.e. not reviewed and approved by google) script to run in your account the first time. Once approved, run a second time to test
ā€¢ Click the clock icon- triggers, then "create a new trigger."
ā€¢ Here you will specify when the script runs. Most often you will select a time interval for when you want it to run.
ā€¢ That's it- get creative!

5 Likes

Here is a link to the more complex version of the script I wrote. This one works to keep a maker-api connected switch up to date with the current on/off or locked/unlocked status based on notification emails from a third party. I am using it to track the current state of 5 door locks connected to an alarm.com system, in order to display their state on a hubitat dashboard. Since the script can only be run once a minute, there is a risk of the device getting out of sync if there are multiple state change notifications since the last check (i.e. a lock is locked, unlocked, and locked again within a few seconds). To account for that, this script calls notification emails for both states, and then runs three different checks:

  • If there are only new notifications for one condition (i.e. locked), then only that api is called. First one exclusive condition is checked, then the other.
  • If there are notifications for both events present (i.e. lock and unlock), the script calls for the time of receipt of the most recent message for each event, then calls the appropriate api based on the most recently received email.

This script is set to delete the examined emails after running, but can easily be configured to remove the labels instead.

The script template includes a section for 2 different locks (front door and back deck in this example). You can easily scale it up or down for any number of locks, or other on/off devices by simply copying and pasting the routine multiple times, and updating the trigger label name and corresponding webhook api for each device. Or delete the second routine if you only have one lock to manage.

I've only had it running for a day, but so far it works very smoothly. Display status almost always updates in less than a minute. It is most dependent on the reliability of the alarm.com notifications being successfully sent, and in the proper order in the event of someone rapidly flipping a lock. :slight_smile: I'm completely new to google script writing, so had to figure out what I was doing from scratch and a few similar online scripts I found. For that reason I've tried to make the instructions as simple as possible for someone else to try. If you can set up maker-api, this is pretty much just copying and pasting to get going. I hope it's helpful for someone else.

https://script.google.com/d/1R5xG8bPGeVEAn02nXnW79VbiY-zPoI57rp6XJk2ub9tK1F_cu5_e2q3F/edit?usp=sharing

2 Likes

Thank you for sharing your hard work here and offering it up to others. I never thought of using a GMail script to hit some webhook URL's in Hubitat. It opens up some interesting thoughts on how I could use this to give me a dashboard of my multiple restaurants security system status potentially.

1 Like

Happy to share- I've borrowed enough of other people's work!

1 Like

Thank you so much! Your script and detailed instructions helped me accomplish two things:

  1. Now when someone buys one of my items on Ebay I get a voice alert on Google Home and a pop alert on my LG smart tv.

  2. I get the same voice alert and tv pop up when an Amazon order arrives.

I know people will point out that I can see these two things on my phone but due to constant spam I keep it muted most of the time.

I believe with your script I could get those alerts for anything that an email comes in for.

Thanks again!

1 Like

I would also like to thank you for that script.

Let me tell you my situation.
I have a number of Amcrest cameras that send out an email when they detect motion.
It's very easy to add another cc to the email list.
I want to use that email to change a virtual motion sensor to "active".
Should be simple, right?
I checked and the following is my webhook to turn a virtual motion sensor to active:
https://cloud.hubitat.com/api/00a5a796-5e99-4614-XXXX-2e831f6b4a1a/apps/2083/devices/3433/active?access_token=XXXX0f1e-bd6c-413d-ac1c-afbc9553XXXX

Yes, that's the idea. That should do the trick. Just use active instead of lock and inactive instead of unlock. Will be up to a 1 minute delay in my experience if that is an issue. I'm using Surveillance station on a NAS to monitor my cameras which is able to directly trigger the web-api, but if your camera can't do that, then email seems like a good intermediary.

By the way, you might want to delete the hubID in the link you pasted (https://cloud.hubitat.com/api/HUBID/....) That will give anyone who finds it access to your hub.

Glad people are finding uses for the code!

Thanks for sharing this. Iā€™m going to give this a shot to check status on my Pella Insynctive door sensor/locks.

First of all thanks for your contribution. This will help me insure that if I have a water leak the email notification from Flume will be a secondary backup to make sure the valve gets closed.

I have followed your instructions to the letter but the webhook URL is not firing from within the script or with a test email. If I paste the url into my browser it fires and the incoming email filter is doing what it is supposed to.

Any ideas? I can PM you the script if necessary.

Has anyone been able to make these scripts work?

Yes, I've tested the first script and it does work. In my testing I found that there is about a 30 second delay between the time when the email is received and the device is triggered.

If you want to PM me your script I would be more than happy to take a look.

1 Like

Download the Hubitat app