Articles in this section

See more

Gmail Promotions Tab Annotations

Marketers frequently wonder how to ensure that Gmail delivers email to the Primary tab and whether it's bad if an email lands in the Promotions tab.

Modern ISPs are savvy at classifying email into categories. This can be a good thing, too—many people look at the Promotions tab specifically when they're seeking good deals from brands they prefer.

Google's updates to the Promotions tab make it possible to annotate emails so that they call attention to discounts, discount codes, logos and more—making it easy for recipients to spot your email and quickly understand its value.

These annotations appear on email categorized as top picks on Gmail's Promotions tab, and currently only in the mobile Gmail client. Because of this, they focus on deals and discounts.

In this article

Setup

To display email annotations in Gmail's Promotions tab, add an array of JSON objects to a <script> block inside the <head> tag your email's HTML template:

<head>  
<script type="application/ld+json">  
[  
    { ... },  
    { ... },  
    { ... }  
]  
</script>

WARNING

This will not work with Iterable's Drag and Drop Editor.

Each JSON object in the array represents a different attribute that Gmail should render in the Promotions tab.

The following sections describe how to incorporate your logo, a discount offer and a promotion card.

To include your brand's logo in the Promotions tab, include an Organization object in your code. For example:

<head>  
<script type="application/ld+json">  
[  
    {  
        "@context": "http://schema.org/",  
        "@type": "Organization",  
        "logo":"https://iterable.com/wp-content/uploads/2020/05/Iterable-Logo-Icon.png"  
    }  
    { ... },  
    { ... }  
]  
</script>
</head>

Change the logo field to a URL that points to your company's logo. Google recommends an HTTPS URL (this isn't required but may be in the future).

Discount offer

To provide a description of a discount offer (a percentage off, a cash savings or another promotion such as "Free shipping") include a DiscountOffer object in your code. For example:

<head>  
<script type="application/ld+json">  
[  
    { ... },  
    {  
        "@context": "http://schema.org/",  
        "@type": "DiscountOffer",  
        "description": "50% off",  
        "discountCode": "PROMO123",  
        "availabilityStarts": "2020-05-15T08:00:00-07:00",  
        "availabilityEnds": "2020-05-17T08:00:00-07:00"  
    },  
    { ... }  
]  
</script>
</head>

In addition to editing the description and discountCode fields, be sure to set appropriate availabilityStarts and availabilityEnds values for the discount. Gmail decides which messages to highlight to the recipient based on the recipient's engagement history and this time period (as compared to other deals).

Promotion card

A promotion card is an image that calls further attention to a promotion. This image appears in the Promotions tab even if the recipient never opens the message. Think of it like a subject line, but an image instead of words.

To add a promotion card, add a PromotionCard object to your code:

<head>  
<script type="application/ld+json">  
[  
    { ... },  
    { ... },  
    {  
        "@context": "http://schema.org/",  
        "@type": "PromotionCard",  
        "image": "https://iterable.com/wp-content/uploads/2020/05/Iterable-Logo_Promotions.png"  
    }  
]  
</script>
</head>

Change the URL in the image field so that it points to the image you'd like to use. Also, remember that Iterable can personalize this image using Handlebars and merge parameters.

Put it all together

Your final code block should look similar to the following:

<head>  
<script type="application/ld+json">  
[  
    {  
        "@context": "http://schema.org/",  
        "@type": "Organization",  
        "logo":"https://iterable.com/wp-content/uploads/2020/05/Iterable-Logo-Icon.png"  
    },
    {
        "@context": "http://schema.org/",
        "@type": "EmailMessage",
        "subjectLine": "[PROOF] Iterable Deals for the Holidays!"
    },
    {  
        "@context": "http://schema.org/",  
        "@type": "DiscountOffer",  
        "description": "50% off",  
        "discountCode": "PROMO123",  
        "availabilityStarts": "2020-05-15T08:00:00-07:00",  
        "availabilityEnds": "2020-05-17T08:00:00-07:00"  
    },    
    {  
        "@context": "http://schema.org/",  
        "@type": "PromotionCard",  
        "image": "https://iterable.com/wp-content/uploads/2020/05/Iterable-Logo_Promotions.png"  
    }  
]  
</script>  
</head>

In Gmail, top picks appear similar to the following:

Gmail Promotions Tab

Notice how the "50% off" and "PROMO123" are called out with badges, making the promotion easy to spot—even before the recipient opens the email. Similarly, the promotion card image creates space and elevates your content.

Keep in mind

Remember:

  • Gmail displays these custom elements for top picks. It selects top picks each time it displays the Promotions tab—even refreshing the view may change the results.
  • Custom attributes on the Promotions tab (including a custom logo) only render for users of the Gmail app on a mobile device—with the Promotions tab enabled. Moving an email from Promotions to another tab will remove the custom attributes from view.
  • Custom attributes show only in the Promotions tab. They do not show in the Primary tab or any other tabs.
  • There is a small chance, based on your domain and IP reputation, that some other email providers/ISPs may not allow the use of a <script> tag inside an email. If you suspect this is causing deliverability issues, try using Handlebars to insert the <script> section only for recipients whose email address contains @gmail.

If you have any further questions, feel free to reach out to your customer success manager.

Want to learn more?

For more information about some of the topics in this article, check out these resources:

Related articles