Use Gmail markup and annotations in your emails

Deliver more value in the Gmail Promotions tab and increase your marketing impact. Put the most valuable parts of your email right at recipients’ fingertips with special annotations that appear right in the inbox, increasing your email’s visibility and making it easier to engage with your brand.

Gmail allows you to use email markup based on >>, a markup vocabulary standardized and managed as a collaboration of Google and other companies, to accelerate user actions and highlight the most important information users need from an email, but also to support your promotional activity.


From the recipient’s point of view, email markup appears as additional information accompanying your email on the list of messages in their inbox in the mobile Gmail app. Such short annotations (or snippets) allow you to highlight key information included in the email, such as deals, expiration dates, and promo codes. You can also add images to your annotations, creating a product carousel.

With email markup, the recipient can click on a Call-to-Action button or a link (image) without opening the email.

Read this article to understand what Gmail markup is, how it works, and how you can implement it in your emails. The article also describes all challenges and limitations involved in using this feature.


  1. What is Gmail schema markup and how it can benefit you
    1. Warnings and limitations
  2. Use Gmail markup in your emails
    1. Registering with Google
    2. Preparing JSON code
    3. Testing your email
  3. Gmail markup in the Email Design Studio

1. What is Gmail schema markup and how it can benefit you

Gmail Markup is a feature provided by Google that enables marketers to enrich their emails with annotations, Call-to-Action buttons, and product carousels that are displayed right in the recipient’s inbox. The feature works only for the Gmail inbox, and more precisely, only for the Promotions tab:

This means that email markup will not work in any other email clients (e.g., Outlook) or under any other Gmail tabs (Primary or Social). Additionally, some markup elements may work only in the mobile Gmail application, while others may work only in the browser (on desktop computers).

From the Promotions tab, users can click on the annotated text or image to learn more information or perform a specific action, without having to open the email. For example, if the email is an event confirmation, the recipient may see details such as the event title, date, time, and location, as well as an “Add to Calendar” button that allows them to add the event to their calendar with just one click.

Email markup is based on structured data and uses vocabulary. The two encodings supported by this Gmail feature are JSON-LD or Microdata—you can use either of them to markup information in your emails.

NOTE: When creating emails in the SALESmanago Email Design Studio, use the JSON-LD format.

What are the benefits of email markup for marketers?
  • Improved visibility: Emails accompanied by an annotation or a product carousel take up more space in the inbox, making your email stand out from the rest.
  • Increased engagement: Email markup takes the form of a Call-to-Action button or an image with a link, which can be clicked directly in the inbox, without actually opening the email. This makes it easier to engage with your brand and may appear as a more attractive option than opening an email, as it saves time and effort.
  • Improved user experience: Email markup allows you to highlight the information that is the most important to your recipients, such as expiration dates, deadlines, and promo codes. This way, the recipient doesn’t need to look for the information, but is provided with it at no additional effort. Moreover, email markup allows the recipient to take action directly from the inbox – saving them the step of opening the email and searching for the Call-to-Action button that enables them to perform the required action. This greatly contributes to the recipient’s convenience.

A. Warnings and limitations

As Google informs in one of its guides >>:

A variety of factors affect whether email annotations are shown to users, including quality filters and frequency limits. Your annotations might not be visible to all users that receive the email.

When implementing Gmail Markup in your emails, you should be aware of the following factors:

  • Gmail schema markup works only for Gmail, and only for the Promotions tab. This means that for this feature to work, your email must land in the Promotions tab of the recipient’s inbox. The markup will not be displayed in any other email client (e.g., Outlook) or under any other Gmail tabs (Primary or Social).
  • To implement Gmail schema markup in your emails (for the purpose of highlighting important information concerning, e.g., order confirmations, order summaries, and delivery tracking), first you need to register with Google and get whitelisted.
  • The display of email markup and annotations may depend on your mailing history and the frequency with which individual recipients open your emails. In Google’s Email Sender Quality guidelines, you can read that the following are required (among other things):
    • Emails must be authenticated via DKIM or SPF (see instructions for the SALESmanago platform >>)
    • A consistent history of sending large numbers of emails from your domain (at least several hundred emails sent to Gmail per day), for at least several weeks.
    • A very low rate of spam complaints from users.
  • The display of email markup may also be prevented by the settings or filters applied by individual recipients on their accounts. For instance, in Google’s Troubleshooting guide >>, you can read:
  • Before you begin troubleshooting a problem, check your account-level settings. Be sure you’ve enabled the settings below in order to test the latest experiences in the Gmail Promotions tab. These are the default settings:
    • Images: Always show.
    • Conversation view: On.
    • Enable Bundling of Top Email: On.
  • This suggests that Gmail markup may not be displayed to users who have altered these (and possibly also other) default settings.
  • Email markup and annotations may not be displayed on certain devices, especially older smartphone models.

If you want to implement Gmail schema markup in your emails to highlight important information, make sure to read and follow the Google Registration Guidelines >>

Despite these disadvantages, Gmail schema markup is still worth implementing, as it can help marketers create more effective emails that stand out on the list of messages, and can help provide a more interactive and engaging experience for email recipients.

2. Use Gmail markup in your emails

A. Registering with Google

In order to use Gmail schema markup in your emails to highlight important information, you need to register with Google.

IMPORTANT: You don’t need to register with Google if you want to implement email promotions, i.e., annotations and product carousels.

The registration process is described in a dedicated Google guide >>. Make sure to follow all the guidelines and requirements listed there.

NOTE: You don’t need to register with Google for the purpose of running tests. The registration is only required if you want to actually implement email markup in messages sent to a real audience (and not a test mailbox).

B. Preparing JSON code

To use the Gmail markup feature in your email, you need to include a <script> tag containing JSON-LD code in the body or head section of your email.

  • To highlight the most important information in your email, include a <script> tag in the body section of your email. Remember that to use this feature, you need to register with Google (see above).

Read the Get Started guide by Google >>

  • To use annotations or product carousels, include a <script> tag in the head section of your email. 

Read the Annotate emails in the Promotions tab guide by Google >>

C. Testing your email

When you have included the code for Gmail markup, annotations, or product carousels in the email template, make sure to check whether the feature works correctly by sending a number of test emails.

You do not need to register with Google for this purpose: just make sure that the sender and the recipient are the same account. If for some reason the feature does not work on your test mailbox, create a new account ending in, e.g.: Use the new account for testing purposes.

TIP: If you are using a new account, emails sent from your marketing account will probably go to the Primary tab. To solve this problem, drag a received test email from the Primary tab to the Promotions tab and send another email (with a different subject line) from the same sender address. Now the test emails should start appearing in the Promotions tab.

Note that DKIM or SPF authentication is still required for self-testing, and that Gmail markup may not work on all mobile devices (especially older models).

For more information, read the Test Your Schemas guide by Google >>

A good idea is to use the Email Markup Tester >>, which is a Google tool that allows you to test the correctness of your structured data.

Experiencing any problems? Read Google’s Troubleshooting guide >>

3. Gmail Markup in the Email Design Studio

The Email Design Studio is a state-of-the-art, feature-rich email designer that allows you to engage your customers and increase conversions while building true intimacy with your audience.

Learn more about the Email Design Studio—the only mobile-first Email Designer with conversion tools and Zero-Party Data capabilities >>

The Email Design Studio allows you to add Gmail schema markup and annotations to your emails. If you have already followed the registration process described above, navigate to the Email Design Studio and select the Body settings tab. Open the Scripts in head section and check the box Add custom JSON data:

A new field will appear.

Click on it to open a text editor and enter your JSON-LD code, for example:

Note that the <script> tag [A] is already included.

When writing your JSON-LD code, try to follow Google’s Best Practices >>

TIP: Make sure that the brackets match and that the last property in each block is not followed by a trailing comma.

When you have written or pasted your code, just close the editor and continue editing your email.

Remember to run a test to check if the email markup works as intended.

Read the Test Your Schemas guide by Google >>

IMPORTANT: The Gmail markup feature works only for Gmail inbox and only for the Promotions tab. Even if you have registered with Google, and even if your email goes to the Promotions tab, your markup and annotations may not be displayed to all individual recipients. Read the entire article, and especially Section 1.A—Warnings and limitations, for more details.

If you need more information about the topic mentioned above, please contact us: +1 800 960 0640