If you’re an email geek who hasn’t been completely swept up by the flurry of holiday or year-end preparations, you’ve probably heard the latest news about Gmail’s promotions tab. Litmus has a great overview of the changes, but the quick summary is that Gmail is allowing email marketers to define certain elements that will display in the Top Promotions bundle if your email is selected by the algorithm. You can define your logo, set a preview image (!!), highlight your email offer and promotion code, and set an expiration date for your deal, like the Land’s End section of the Top Promotions below.

In a webinar last month with Jordan Grossman, the product manager for Gmail, we learned a bit more about what’s going on behind the scenes. Grossman revealed that Gmail considers tab usage “a very important metric.” If consumers find something of value in the promotions tab, they’ll come back to this tab again and again, and they’ll be more likely to open and engage with more emails.

Currently this functionality is only available if you’re viewing email for a @gmail.com account in the Gmail app (so no G Suite functionality yet). Desktop Gmail support is expected to roll out by Q2 2019.

How does an email get picked to be a Top Promotion?

One of the burning questions was how an email gets selected as a Top Promotion. The Gmail classifier determines which tab an email ends up in, and whether to show it in the Top Promotions section. According to Grossman, the classifer is not overly concerned with the open rate of your email. On a user-by-user basis, it determines what is the most helpful email to put in that Top Promotions section. Behavior patterns are analyzed to presume what is most useful for that consumer based on past email interactions. However, the infrequency of an email may also get it into the Top Promotions bundle—for example, an email that only comes out a couple times a year may be more likely to show in Top Promotions because of its novelty factor.

How can you find out how many people saw your Top Promotion?

Unfortunately, Gmail does not offer any reporting metrics for how many people saw or interacted with your Top Promotions content. However, there are some creative workarounds people have come up with, like serving up unique images via NiftyImages for the preview image so you can get metrics on how many images are served up. Using this method, one tester reported 13 Gmail promo image opens for every 100 unique Gmail domain opens. Grossman cautioned us not to be overly concerned about how often our emails end up in the Top Promotions bundle because it’s out of our control. “Just keep creating valuable content for your users,” he said.

If I use this code, will it put my email in the Promotions tab?

If you don’t annotate your email, it will not prevent your email from ending up in the Top Promotions section— it just means that you’ll miss out on the chance to get more exposure when you’re there. And by adding the code to your email, you’re not influencing the Gmail classifer to place you in the promotions tab instead of the primary inbox, either. Grossman said, “The classifer to determine which tab emails go into does not look at annotation at all. In the future we may allow you to tell us in the code that ‘This email belongs in the promotions tab’ but the reverse will never be true—we’ll never allow you to push your email into the primary tab via annotation.”

Ok, ok, just give me the code

Litmus has a great tool that allows you to preview what this will look like and then gives you the JSON or Microdata code to add to your email. In our tests so far, we’ve only had success with the Microdata code because our email service provider strips out the JSON script before mailing. We’re dropping the annotations code right inside the <body> tag.


If you’re concerned about deliverability to other (non-Gmail) domains, you might consider only including this snippet of code in the template sent to your Gmail users. The jury is still out on whether this code might negatively impact other domains’ deliverability.

How do I test this?

  • You’ll only see Top Promotions if you use the tabbed inbox experience (Promotions, Social, Primary).
  • The Gmail algorithm will determine whether or not your campaign shows up in this section and there’s no way to force it to display.
  • To test this, create a new gmail account ending in “[email protected]” and use that new account for testing (e.g. [email protected]). You can also preview how your code will work by using that Litmus tool.


  • You should deliver to a @gmail.com address, since this does not currently work with G Suite email (email hosted by Gmail that’s not @gmail.com).
  • Be sure you have latest Gmail app, and then:
    • refresh the promo tab (pull down to refresh)
    • In Gmail app settings, be sure “Show Sender Images” is enabled
    • In the Gmail app settings for the particular account you’re looking at, be sure “Conversation view” is enabled and “Enable Bundling of Top Email” is enabled.
  • You may be part of a holdback group. There is a small percentage of users who won’t get this feature so Gmail can monitor the long term impact of this feature. Set up fresh @gmail account to ensure you are not part of holdback group.
  • More troubleshooting tips on the Gmail Developers site.

More tips

Defining the logo that displays in Top Promotions:

  • It’s a circle logo image served via https, center-cropped.
  • You can display a different logo to different groups of users if necessary.

Details on the deal badge:

  • Good to use for free shipping, BOGO, and % off deals
  • Remember: it is not a second subject line!
  • Keep it short
  • Don’t have a deal? Then don’t use this field


Details on the promo code:

  • The field value is always preceded by the word “Code”
  • Just like the deal badge, remember that it is not a second subject line.
  • Keep it short
  • Don’t have a promo code? Leave the field blank.


Set the expiration date for your deal:

  • Not recommended for flash sales
  • Use the time zone for when the actual sale starts and ends
  • Your email may be pulled into a bundle if it’s about to expire—additional exposure for expiring deals!


Single image preview:

  • It’s best if the image reflects content of the email.
  • Don’t use text-only designs for image (this will annoy the user and performance will suffer).
  • If you already have an image inside the email, it’s fine to reuse it but just know that center-crop may cut text/image off.
  • Sample images are 538 x 138 pixels in size and have a 3.9 aspect ratio. GIF and WEBP images are not supported.

Don’t reuse the same promo image in each email—this also annoys consumers. Email messages that reuse the same image may be disregarded as duplicates.

Future features Gmail promises

  • Gmail will allow you to annotate the subject line so it’s different if your email is chosen to be in a bundle
  • Topic bundles will be coming (entertainment, travel, dining, clothing, etc.)
  • Catalog cards with CTAs in the promo area
  • Carousels

Additional Resources

Here are a few more sites that have resources to help you understand and implement Google Top Promotions: