> [!NOTE]
> **Note:** For assistance with troubleshooting or to learn more about the following annotation features, send an email to [p-Promo-Outreach@google.com](mailto:p-Promo-Outreach@google.com).
Email annotations bring email messages in the Promotions tab to life with
features such as images, deals, and expiration dates.
When you annotate emails, Gmail users view and interact with your
promotions directly from their inbox. From the Promotions tab, users can click
the annotated text or image to learn more about the promotion, without having to
open the email.
This page explains how to annotate emails using
[JSON-LD](https://developers.google.com/workspace/gmail/markup/reference/formats/json-ld) and
[Microdata](https://developers.google.com/workspace/gmail/markup/reference/formats/microdata). To learn more
about email markup, review the
[Getting started](https://developers.google.com/workspace/gmail/markup/getting-started) guide. For a list of
markup fields that you can use in email annotations, visit the
[reference documentation](https://developers.google.com/workspace/gmail/promotab/reference).
## Build email annotations
You can annotate emails to display the following features in the Promotions tab:
- [Create a product carousel](https://developers.google.com/workspace/gmail/promotab/overview#product-carousel)
- [Create a single image preview](https://developers.google.com/workspace/gmail/promotab/overview#single-image-preview)
- [Create a deal annotation](https://developers.google.com/workspace/gmail/promotab/overview#deal-annotation)
- [Create a deal card](https://developers.google.com/workspace/gmail/promotab/overview#deal-card)
The following sections explain how to create each type of email annotation.
> [!NOTE]
> **Note:** 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 who receive the email.
### Create a product carousel
Product carousels display multiple image previews for a promotion, such as the
following:
You can include up to 10 image previews in a carousel, and each image must be
unique.
To create a product carousel:
1. In your marketing email platform, create an email and open the email's HTML editor.
2. In the `head` section, add a `script` tag. For each image in your product
carousel, add a
[`PromotionCard`](https://developers.google.com/workspace/gmail/promotab/reference#promotioncard)
object:
### JSON-LD
// The message of your email
### Microdata
// Build the first image preview in your product carousel:
// Optionally, include the following PromotionCard properties:
// Build the second image preview in your product carousel:
// Optionally, include the following PromotionCard properties:
// To include more image previews, add additional PromotionCard objects.
// You can include up to 10 image previews in a product carousel.
// The message of your email
For each `PromotionCard` object, replace the following values. For the
optional properties, you can either include a value, or omit the property
from your code.
- `IMAGE_URL`: The URL to your image in
PNG or JPEG format, such as `https://www.example.com/image.png`. The
supported aspect ratios are 4:5, 1:1, and 1.91:1. For product
carousels, each image must have a unique URL and use the same aspect
ratio.
- `PROMO_URL`: The URL for the promotion. When
users click the image from the Promotions tab, they visit this URL.
- `HEADLINE` (Optional): A one- or two-line
description of the promotion that displays under the preview image.
- `PRICE` (Optional): The price of the promotion.
- `PRICE_CURRENCY` (Optional): The currency of the
price in three-letter
[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)
format, such as `USD`. Determines the currency symbol displayed with the
`price`.
- `DISCOUNT_VALUE` (Optional): The amount
subtracted from the `price` to display an adjusted price. The adjusted
price is displayed next to the original price.
For example, if the `discountValue` is `25`, the `price` is `100`, and
the `priceCurrency` is `USD`, the adjusted price displays as `$75`.
- `POSITION` (Optional): The position of the card
in the carousel.
3. In the `body` tag, write the message for your email.
### Create a single image preview
Single image preview annotations display one image to showcase an important
product in the Gmail Promotions tab, such as the following:
You can use this feature for a single image. All recipients must receive the
same image and image URL. For more information, see the
[FAQ](https://developers.google.com/workspace/gmail/promotab/faq).
To create a single image preview:
1. In your marketing email platform, create an email and open the email's HTML editor.
2. In the `head` section, add a `script` tag that includes the data type
[`PromotionCard`](https://developers.google.com/workspace/gmail/promotab/reference#promotioncard):
### JSON-LD
// The message of your email
### Microdata
// Build the single image preview:
// Optionally, include the following PromotionCard properties:
// The message of your email
Replace the following values. For the optional properties, you can either
include a value, or omit the property from your code.
- `IMAGE_URL`: The URL for the preview image in PNG
or JPEG format, such as `https://www.example.com/image.png`. The
supported aspect ratio is 1.91:1.
- `PROMO_URL`: When users click the `image`, the
URL that directs to the promotion.
- `HEADLINE` (Optional): A one- or two-line
description of the promotion that displays under the preview image.
- `PRICE` (Optional): The price of the promotion.
- `PRICE_CURRENCY` (Optional): The currency of the
price in three-letter
[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)
format, such as `USD`. Determines the currency symbol displayed with the
`price`.
- `DISCOUNT_VALUE` (Optional): The amount
subtracted from the `price` to display an adjusted price. The adjusted
price is displayed next to the original price.
For example, if the `discountValue` is `25`, the `price` is `100`, and
the `priceCurrency` is `USD`, the adjusted price displays as `$75`.
3. In the `body` tag, write the message for your email.
### Create a deal annotation
Make your email stand out with a deal annotation. This feature adds a
promotional badge directly to your email in the inbox, calling out key
information---like a discount code or offer details---right next to your subject
line.
To enable deal annotations, follow these steps:
1. **Add the schema to your email's HTML** : In your marketing email platform,
open the HTML editor for your campaign. In the `head` section, add a
`script` tag that includes the data type
[`DiscountOffer`](https://developers.google.com/workspace/gmail/promotab/reference#discountoffer) with
the following structure:
### JSON-LD
// The message of your email
### Microdata
// The message of your email.
2. **Customize the deal annotation properties**: Update the values in the
script to match your specific promotion.
**Required values:** In the sample code, replace **at least one** of the
following variables to generate a deal annotation.
- `DESCRIPTION`: A short, compelling summary of
your offer.
- Example: "20% off sitewide" or "Buy one, get one free".
- `DISCOUNT_CODE`: The promo code a user needs to
apply at checkout.
- Example: 20TODAY.
- `END_DATE_TIME`: The end date and time of the
promotion in
[ISO 8601](https://support.google.com/merchants/answer/7055760) format.
- Example: 2025-09-23T18:44:37-07:00.
**Highly recommended properties:**
- `START_DATE_TIME`: The start date and time of the
promotion in
[ISO 8601](https://support.google.com/merchants/answer/7055760) format.
- Example: 2025-08-24T18:44:37-07:00.
3. **Write your email message** : In the `` tag, write the message and
design the layout for your email as you normally would.
4. **Validate and preview your deal annotation** : Before sending your campaign,
validate your code and see a [preview](https://developers.google.com/workspace/gmail/promotab/preview)
of how your deal annotation looks.
### Create a deal card
Deal cards are visual summaries of your promotions that Gmail
generates. They can appear in the Promotions tab and within the email itself,
giving your offers maximum visibility.
To enable deal cards, follow these steps:
1. **Add the schema to your email's HTML** : In your marketing email platform,
open the HTML editor for your campaign. In the `head` section, add a
`script` tag that includes the data type
[`DiscountOffer`](https://developers.google.com/workspace/gmail/promotab/reference#discountoffer) with
the following structure:
### JSON-LD
// The message of your email
### Microdata
// The message of your email.
2. **Customize the deal card properties**: Update the values in the script to
match your specific promotion.
**Required values:**
- `DESCRIPTION`: A short, compelling summary of
your offer.
- Example: "20% off sitewide" or "Buy one, get one free".
- **At least one of the following URLs:** Provide an offer page URL if
available.
- `OFFER_PAGE_URL`: The URL for this specific
offer landing page. This creates a "Shop now" (or similar) button on
the deal card. If provided, Gmail prefers the offer
page URL.
- `MERCHANT_HOMEPAGE_URL`: Use this only if a
specific offer page is not available. This links to your main
homepage.
**Highly recommended values:**
- `DISCOUNT_CODE`: The promo code a user needs to
apply at checkout.
- Example: 20TODAY.
- `START_DATE_TIME`: The start date and time of the
promotion in
[ISO 8601](https://support.google.com/merchants/answer/7055760) format.
- Example: 2025-08-24T18:44:37-07:00.
- `END_DATE_TIME`: The end date and time of the
promotion in
[ISO 8601](https://support.google.com/merchants/answer/7055760) format.
- Example: 2025-09-23T18:44:37-07:00.
3. **Write your email message** : In the `` tag, write the message and
design the layout for your email as you normally would.
4. **Validate and preview your deal card** : Before sending your campaign,
validate your code and see a
[preview](https://developers.google.com/workspace/gmail/promotab/preview) of how your deal card looks.
## Next steps
- View the [reference documentation](https://developers.google.com/workspace/gmail/promotab/reference) to learn about the available email markup fields.
- Learn about [best practices](https://developers.google.com/workspace/gmail/promotab/best-practices) for email annotations.