Google Annotations

Steven Sayo
5 min readJan 31, 2019


Just before the Christmas holidays, Google announced their new feature within Gmail called Google Annotations. It is no longer the wish of an Email Marketer to hit Gmail’s Primary inbox, but instead, to hit the place they once feared. The Promotions Tab.

Gmail Promotions Tab Ft. New Annotations Card (Credit: Google)

In the image above, you can easily see how the offers in the ‘Top Deals’ stand out. Google Annotations allow you to add a custom logo, offer detail, offer code, expiry date and an image to these promo cards.

As a B2C (Business to Consumer) Email Marketer, this announcement was like an early Christmas present. The Winter Sale period was upon us and this new feature would help my emails stand out above the rest during the busy email marketing event. This inspired me to get this feature implemented ASAP. So the question was ‘how do I do it?’.

Luckily, within a few days, online tools from big names in the Email Industry were released to help email marketers take advantage of this feature. These tools are available from Email on Acid, Litmus and Fresh Inbox.

Litmus Gmail Promotions Builder

These builders have easy to follow forms where you can simply fill in the information for your promotion card and it will generate the HTML code for you to add to your email.

Adding Google Annotations to your email.

There are two methods in which you can make the Promotion Card. The first is using JSON code and the other is Microdata. While discussing the implementation of this new feature on the #EmailGeeks Slack Channel it was said that some Email Service Providers (ESPs) can automatically strip out the JSON code and that inboxes that aren’t Gmail could issue warnings because of having JSON code embedded in the email. Therefore I opted to use Fresh Inbox’s Microdata Tool.

Fresh Inbox Gmail Promotions Tab Markup Tool

Using the tool was so simple and easy to follow, it made creating the Google annotations promotion card a breeze. Once my code was generated, all I had to do was paste it just after the opening <body> tag in my email’s HTML and voila! I could now use this new feature to help promote the Winter Sale and stand out from other retailers in the Gmail Promotions tab.


Not seeing your annotations appear in the Gmail App? While testing and discussing this feature with other Email Geeks I have come up with a few tips for troubleshooting your promo card.

  1. Make sure your app and phone operating system is up to date.
  2. Check your Gmail account settings. Not only do you need to have the tabbed view enabled but it is also recommended that you have “Conversation View” turned on as well.
  3. If you do not see the ‘Top Promotions’ section in your app. Try force closing the app and re-opening it. Sometimes I have to do this step to make it appear again.
  4. Mark all other items in your promotions tab as read (keeping the email you are testing unread) this will ensure that your email will appear in the ‘Top Promotions’ section. It may take a couple of refreshes for it to appear.
  5. Create a new Gmail account for testing*

*Note: I didn’t need to do this on my existing account but some EmailGeeks found that, for some reason, annotations did not work on their current Gmail account but creating a new account worked. Google themselves also advise that you might have to create a new account as your current account may be contained within a “holdback group” This also confirms the speculations that this feature is being treated as an A/B test on certain accounts. The guidelines for creating a new account are naming it as follows —

If these troubleshooting suggestions have not helped you generate a preview of your Google Annotation promotion card there is a new tool by Google where you can enter your HTML, with your chosen implementation of Google Annotations, and it will render a preview if your code is correct.

ESP Quirks

<!- -The following quirk has been resolved by Gmail and should no longer affect your Google Annotation. I have left this is for reference.- - >

When discussing implementation and troubleshooting with other email geeks, I discovered a bug. If a <style> block is added before the Microdata code, for the Gmail Promotion Card, it stops working.

Currently, Salesforce Marketing Cloud (SFMC) has a preview text field in their email builder that automatically adds a <style> block just after the opening <body> tag thus affecting the Promotions Card.**

** It is worth noting that I tested adding a <style> block after the Microdata and it did not affect the promotion card appearing in ‘Top Deals’.

Salesforce Marketing Cloud Preheader field

If you know HTML and can implement preview text with custom HTML, I would recommend you do so. On the other hand, if you don’t know how to do this and would like help, be sure to join the #EmailGeeks Slack Group where the friendly community is always willing to help.

Another bug, per se, was found while helping another Email Geek, Jenna, test her Google Annotations. It turned out that my preferred method of implementation didn’t work for her. However, when Jenna used the Email on Acid Tool it started working.

What was deduced from this is that the Email on Acid tool adds both the JSON script and the Microdata. That seemed to be the only difference between my implementation and hers. Also, the ESP that Jenna uses is Responsys. At this moment in time, I have not found any evidence that suggests Responsys adds code to the HTML email that stops the Microdata only version from working. However, if your email service provider is Responsys and the Microdata method is not working for you. Try the Email on Acid Tool like Jenna and hopefully it will work for you, as it did for her.


This Google Annotations feature is truly a great advancement in email marketing. It makes the inbox experience better for the user by giving them the ability to pick out top deals and allows email marketers to get more creative in getting their audience's attention. It will definitely be interesting to see how other email providers like Outlook or Yahoo respond to this feature.

If you have found this article helpful or have some suggestions to improve it you can always reach out to me on Twitter or catch me on the #EmailGeeks Slack Channel.



Steven Sayo

The Northern Email One Man Army — Email Design, Developer, Strategist, CRM and Active #emailgeek