How to enable and use email annotations for Gmail

You will learn

Learn about email annotations, which enable you to display key information in the list view for Gmail inboxes (i.e., before someone opens the email). Email annotations allow you to highlight a deal or offer (e.g., a coupon code), or display product images directly in the inbox. 

About email annotations

Email annotations are supported in Gmail mobile inboxes for users with the Promotions tab enabled. These annotations only appear in the Promotions tab, not the primary inbox. 

There are 3 types of annotations: 

• Deal/offer
  Highlight a deal or offer, like a coupon code or free shipping, including the deal expiration date.
  
• Product carousel
  Display a carousel of product images, optionally including product details like name and price.
  
• Single image
  Show a single image, along with optional additional text.
  

Before you begin

Google maintains an allowlist of senders who can use annotations. Before using annotations, you must request that your brand be added to this allowlist. 

To request that Google add you to their annotations allowlist, send an email to p-Promo-Outreach@google.com with the following information: 

• All domains (e.g., example.com)
• All subdomains (e.g., send.example.com, blog.example.com, marketing-messages.example.com) 
• Your landing page URL(s) (e.g., your homepage) 

Any annotations code added to your messages will be ignored until you are added to the Google allowlist, which can take 7-10 business days or more. 

Add annotations to your emails

Add the following code within the body section of your HTML email template to add email annotations. There are 3 types of annotations available: 

• Deal annotations
• Product carousel annotations
• Single image annotations 

Deal

  <div itemscope itemtype="http://schema.org/DiscountOffer">
    <meta itemprop="description" content="DESCRIPTION"/>
    <meta itemprop="discountCode" content="DISCOUNT_CODE"/>
    <meta itemprop="availabilityStarts" content="START_DATE_TIME"/>
    <meta itemprop="availabilityEnds" content="END_DATE_TIME"/>
  </div>

Replace the following placeholders in the code: 

• DESCRIPTION
  A brief (1-2 line) text description of the offer
• DISCOUNT_CODE
  The code a recipient can enter at checkout to receive the offer
• START_DATE_TIME
  The offer start date/time, using ISO 8601 format
• END_DATE_TIME
  The offer end date/time, using ISO 8601 format

Product carousel

  <div itemscope itemtype="http://schema.org/PromotionCard">
    <meta itemprop="image" content="IMAGE_URL1"/>
    <meta itemprop="url" content="PROMO_URL1"/>
    // Optionally, include the following PromotionCard properties:
    <meta itemprop="headline" content="HEADLINE1"/>
    <meta itemprop="price" content="PRICE1"/>
    <meta itemprop="priceCurrency" content="PRICE_CURRENCY1"/>
    <meta itemprop="discountValue" content="DISCOUNT_VALUE1"/>
    <meta itemprop="position" content="POSITION"/>
  </div>
  // Build the second image preview in your product carousel:
  <div itemscope itemtype="http://schema.org/PromotionCard">
    <meta itemprop="image" content="IMAGE_URL2"/>
    <meta itemprop="url" content="PROMO_URL2"/>
    // Optionally, include the following PromotionCard properties:
    <meta itemprop="headline" content="HEADLINE2"/>
    <meta itemprop="price" content="PRICE2"/>
    <meta itemprop="priceCurrency" content="PRICE_CURRENCY2"/>
    <meta itemprop="discountValue" content="DISCOUNT_VALUE2"/>
    <meta itemprop="position" content="POSITION"/>
  </div>
  // To include more image previews, add additional PromotionCard objects.
  // You can include up to 10 image previews in a product carousel.

Replace the following placeholders in the code: 

• IMAGE_URL1, IMAGE_URL2, etc.
  The URL of a product image to display in the carousel. Supported aspect ratios are 4:5, 1:1, and 1.91:1. The aspect ratio for every image must be the same. 
• PROMO_URL1, PROMO_URL2, etc.
  The URL to a landing page for recipients who click the product image.
• HEADLINE1, HEADLINE2, etc.
  A short, 1-2 line description of the product. 
• PRICE1, PRICE2, etc.
  The base price of the product (number only, no currency). 
• PRICE_CURRENCY1, PRICE_CURRENCY2, etc.
  The 3-letter currency code (e.g., USD) for the item’s price.
• DISCOUNT_VALUE1, DISCOUNT_VALUE2, etc.
  If applicable, the amount an item is discounted (number only, no currency). 
• POSITION
  (Optional) a number indicating this item’s position in the carousel.

Single image

  <div itemscope itemtype="http://schema.org/PromotionCard">
    <meta itemprop="image" content="IMAGE_URL1"/>
    <meta itemprop="url" content="PROMO_URL1"/>
  </div>

Replace the following placeholders in the code: 

• IMAGE_URL1
  The URL of a product image to display in the carousel. Supported aspect ratios are 4:5, 1:1, and 1.91:1. 
• PROMO_URL1
  The URL to a landing page for recipients who click the product image.

About automatic annotation extraction

Sometimes, Google automatically extracts email data to add annotations, even when a sender hasn’t added the code outlined above. This is done at Google’s discretion, and cannot be controlled by the sender. 

Troubleshooting your annotations

Google has strict requirements for annotations. If your annotations are not appearing after following the steps outlined above, try these troubleshooting steps. 

Ensure your brand is allowlisted 

Google maintains an allowlist of a limited list of brands that are approved to use email annotations, in order to prevent spam and abuse. Reach out to Google using the steps outlined above, then allow 7-10 business days for a response. There is no guarantee that your brand will be added to the allowlist once you request it, as this is managed at Google’s sole discretion. 

Check your image quality

All images used for email annotations must pass through a quality filter. If your images do not meet Google’s image requirements, they will not display in the inbox. 

Make sure your images meet these criteria: 

• High quality (i.e., greater than 500 KB)
• Have very little, if any, text 
• Rectangular (don’t use a mask to make the image round, or another shape) 
• Are at least 256x256px 

Don’t use unique images per recipient

Images must be the same across recipients. You may add unique tracking parameters to the promo url, but not the image URL. Using a tool that creates CID images (i.e., images that are unique to each recipient) will result in your annotations not appearing in the inbox. 

Consider Gmail’s density cap

Google has a density cap that restricts how many images recipients can see in their inbox. This means that if a recipient’s inbox already has several recent emails with annotations, yours may not appear in order to keep the inbox uncluttered. This limitation is implemented at Google’s sole discretion and cannot be controlled by the sender. 

Annotations are for bulk sends, not previews 

Sending a test email to 1 or 2 recipients generally won’t result in annotations appearing in the inbox. The annotations feature is restricted to bulk sends, so annotations are likely to only appear when a message is sent to >100 recipients. 

Rather than sending a preview email to yourself to test your code, use Google’s promo tab preview tool for developers. This resource allows you to test your code and see how annotations will appear to those who see them. 

Annotations are supported in the Gmail mobile app’s promotions tab

Annotations are not supported in other Gmail inboxes, including: 

• Gmail in any browser (e.g., the mobile or desktop site) 
• Any tab other than Promotions
• Inboxes for users who do not have the Promotions tab enabled in their Gmail settings 

Additional resources

• How to use Klaviyo’s subject line assistant
• Understanding Gmail's tabbed inbox