I've been using the Gmail.gem to pull email counts in a Personal Dashboard for a couple years. And, in Gmail, I use Superstars, which are flags you can toggle through on an email. I was disappointed not to be able to filter Superstars through the email.

A recent Stack Overflow article pointed me in the right direction. I use Gmail Superstars, which enables additional flags where the standard yellow-star is used. Below, you can see the red-bang and green-check.

How I Use Superstars

I use red-bang for emails I need to respond to. I use the orange-guillemet for emails that I'm awaiting a response on. I use the green-check for emails I have completed. (Though, most of the time I just archive things as I complete them). And, I use the yellow-star for informational items, sorta like a bookmark.

Searching for GMail Superstars

Superstars labels are searchable through the Gmail interface using 2 syntaxes.

• has:yellow-star or l:^ss_sy
• has:blue-star or l:^ss_sb
• has:red-star or l:^ss_sr
• has:orange-star or l:^ss_so
• has:green-star or l:^ss_sg
• has:purple-star or l:^ss_sp
• has:red-bang or l:^ss_cr
• has:yellow-bang or l:^ss_cy
• has:blue-info or l:^ss_cb
• has:orange-guillemet or l:^ss_co
• has:green-check or l:^ss_cg
• has:purple-question or l:^ss_cp

Superstars and the Gmail.gem

So, using the Gmail .gem, I was delighted to find I can access these specific counts. Here's how:

gmail = Gmail.connect(@email_address, @password)
@red_banged_emails = gmail.inbox.emails(gm: '"l:^ss_cr"')

Or, as I use them

@starred = gmail.inbox.emails(gm: '"l:^ss_cy"')
@requires_my_follow_up = gmail.inbox.emails(gm: '"l:^ss_cr"')
@requires_a_response_from_somebody_else = gmail.inbox.emails(gm: '"l:^ss_co"')

Thanks to Google and Stack Overflow for persisting this knowledge!