« Beeminder home

Beeminder Blog

Gmail Zero (with labels)

Announcement! We’ve reworked Gmail goals to use a label instead of an arbitrary search query, because Google is making us. (Not just us. Any app wanting access to things like arbitrary search queries has to go through a $10k+ security audit now!) If you need to do something about your Gmail goal to keep it working, you’ll get an email explaining what. Other than maybe having to do a one-time thing, this makes (almost) everything better for (almost) everyone!

If you don’t already have a Gmail goal, you don’t have to care about any of this at all. Except you should go create one! Starting today it’s simpler and better and we no longer need you to grant permission for Beeminder to read your email. [1]

We’ve supported beeminding your inbox for years through our Gmail integration. You can connect Gmail and Beeminder, set up a new goal, and Beeminder starts tracking the number of read messages in your inbox. To get that number, Beeminder needed permission to perform searches of your email. Gmail is tightening the restrictions on what it takes to get this permission, and we won’t be able to do this. You may have noticed that over the past year, many services that used to integrate with Gmail have stopped or have changed their integration. We haven’t been able to find a good non-developer-oriented page from Google about this, but they do have a developer FAQ.

This is a net positive change for the world. If fewer malicious actors steal email because of this change, it’s probably worth the hassle of Beeminder changing how it works. And we think the new way of beeminding Gmail should be better or just as good as the old way for nearly everyone.

So, how does beeminding your Gmail work now? Our new permissions only allow us to view your labels. This includes how many messages are read and unread for each label, but doesn’t include any details about the emails themselves.

When you create a Gmail goal, Beeminder shows you this screen:

Screenshot of the UI for picking what label to beemind

By default, it looks for read messages in your inbox, but there are two dropdowns where you can set Beeminder to look at only unread, only read, or all messages that match any of your labels.

What if you want to beemind something else with your email?

Not everyone has used Gmail labels, but they’re pretty slick. You can manually label emails. There are also a few built-in labels, like INBOX, that are auto-applied. Otherwise, the main way to label email is by doing a search, and then creating a filter from that search.

One Little Tricksy Caveat

Labels applied by filters are applied when the email arrives, and this means that not all searches that used to be supported will be supported in this new world order. Gmail actually warns you if you try to create a label from a filter that doesn’t apply to new email — things like “email older than 3 days” — because email won’t be older than 3 days the moment it arrives.

If you’re using a search that can’t be turned into a label-applying filter, there’s at least one other way to get your email labeled. Google says that Google Apps Script running on your own email won’t fall afoul of their new restrictions. I actually use this to do complicated things with my email already. If you need this, I can write a tutorial on applying labels using Google Apps Script. Let us know! [EDIT: Done! forum.beeminder.com/t/gmail-labeler-script]


We are emailing everyone with existing Gmail goals to explain what they need to do in order to keep their goals working.

Folks who were using the default “beemind read messages in my inbox” will have their search migrated over automatically. Folks who had custom Gmail search queries will need to migrate their search query to a label and set the label in the goal’s settings page.

Everyone who was beeminding Gmail before will have to disconnect and reconnect Gmail in their Beeminder Account Settings. This will get you the right permissions, limiting us to just looking at labels.

In conclusion:

  • If you already have a Gmail goal, you’ll get an email saying what you have to do (and by when!)
  • New Gmail goals are already on the new setup and will use labels the whole time
  • Folks can sleep a little easier knowing that Beeminder will no longer be asking for email-searching permission to beemind your Gmail
  • We think that the new setup is a global positive, even though there may be a few goals that aren’t easily transferred to the new setup. (Although, if this is you, we want to hear about it!)



[1] Previously, to count your messages, Beeminder needed users to grant it full read-only permission on your email in order to do arbitrary search queries. Not great! We totally support Google tightening this up so we only need permission for exactly what we’re doing: counting your messages.