Add custom star to Gmail Message using Gmail REST

Question

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") returns null

There doesn't seem to be a way to access the internal labels. Is it even possible with this limited API?