How can you use the Gmail REST or Apps API to add a custom star to a message? Is there an alternate label name we can use for the Gmail REST API? Is it even possible from the Google Apps Script API?
Context
A Gmail user can change their settings to customize which stars they want to use. These used to be called "superstars" named after the Labs feature that introduced them. It continues to appear when working them, like the asset URL: ...superstars/star_lit_green_check3.png.
Gmail REST API
The Gmail REST API does not provide an endpoint to set a custom star. You can star or unstar by using the User.messages.modify endpoint to add or remove the STARRED
label. There doesn't seem to be any documentation indicating what other labels are available for full set of stars.
Since the documentation doesn't offer clues how to set custom stars, inspecting the network requests using Gmail gives us a lead.
The "sslbl" follows the pattern of where the prefix is ^ss_
, the type is s
for a star or c
for the custom types, and the first letter of the color. Working through them all gives us the list:
Stars: ^ss_sy, ^ss_so, ^ss_sr, ^ss_sp, ^ss_sb, ^ss_sg
Custom: ^ss_cr, ^ss_co, ^ss_cy, ^ss_cg, ^ss_cb, ^ss_cp
A little research later, and you'll end up with:
- A list showing the search queries and their shorthand for superstars
- The similar shorthand for other common locations
Unfortunately these internal labels aren't recognized by the REST API. Testing another internal ^
-prefixed label also fails, suggesting that you can't use these here. Notice how the CATEGORY_FORUMS
label in the screenshot above is applied to the message. The corresponding ^smartlabel_group
label fails.
~~
Edit: Based on @TarunLalwani's suggestion, I've tried User.messages.modify
using a URL encoded label. For ^ss_sy
, that is encoded as %5Ess_sy
. Here's the result:
~~
Another barrier - using Users.labels.list doesn't include any labels related to the custom stars in the system or user labels.
What label name can we use from the Gmail REST API?
Google Apps Script Gmail API
This API falls short:
- You can only star/unstar messages
- The API limits you to getting user-created labels
- Using
GmailApp.getUserLabelByName("^ss_sy")
returnsnull
There doesn't seem to be a way to access the internal labels. Is it even possible with this limited API?