HomeEngagementContentDiscoveryOther resources
Guides

Gmail annotations setup

Suggest Edits

This article explains how to add Gmail annotations to your emails using Bloomreach Engagement. You'll learn the technical steps, requirements, image specs, and platform tips.

📘

Note

Gmail doesn't always display annotations, even when you set everything up correctly. If you run into issues, read the troubleshooting guide.

Prerequisites

  1. Get Gmail allowlist approval. You can't test annotations until Gmail approves your sending domain.
    1. Email [email protected] with your sending domain name.
    2. Wait 7–10 business days for processing.
  2. Make sure you have the right user roles for managing email campaigns and scenarios.
  3. Prepare to send to at least 100 Gmail recipients. Single-person tests won't show annotations in most cases.

Choose your email builder

You can use either the HTML builder or Visual builder in Bloomreach Engagement. Each has advantages and limitations for adding Gmail annotations.

HTML builder

  • Full control over code placement.
  • Better reliability for annotation display.

Visual builder

  • Easier email design process.
  • Requires workaround for code placement.

Add code to your email

The email builder you chose affects where you place the code.

HTML builder: add to head section

Adding annotations to the HTML <head>:

  • Increases the likelihood of annotations being displayed correctly.
  • Makes the email body easier to work with.

📘

Important

Add code directly in the <head> section. If you place code in other places (like in the email body), Gmail might ignore it or fewer customers will see annotations.

Visual builder: use workarounds

The Visual builder doesn’t let you edit the <head> section directly.

Store JSON-LD scripts as Blocks in the Asset Manager. Then add them as "dynamic blocks" at the top of your email. Place them above your header as the first block.

📘

Backup option

Add code to the <body> section instead of <head>. Gmail still accepts this, but it causes more display issues during testing. Based on our experience, annotations are less likely to display in a real campaign.

Set up deal badges

Deal badges show text-based details about promotions, like discount codes or expiration dates.

Code

<script type="application/ld+json">
{
  "@context": "http://schema.org/",
  "@type": "DiscountOffer",
  "description": "<discount description>",
  "discountCode": "<promo code>",
  "availabilityStarts": "<start date in ISO format>",
  "availabilityEnds": "<end date in ISO format>"
}
</script>

Fields

All fields are optional. You can include values or leave them out.

FieldDescriptionExample
descriptionShows deal text25% off
discountCodeShows promo codeSUMMER25
availabilityStartsSets start date2025-05-21T00:00:00-07:00
availabilityEndsSets end date2025-06-30T23:59:59-07:00

Best practices

  • Keep it short: Use 4 words or fewer. The badge space competes with your subject line.
  • Be specific: Include exact discount percentages or promo codes.
  • Avoid sentences: Don't use full sentences or run-on text.

Set up single image previews

Single image previews display one image to showcase an important product.

Code

<script type="application/ld+json">
{
  "@context": "http://schema.org/",
  "@type": "PromotionCard",
  "image": "<https://example.com/product-image.jpg>",
  "url": "<https://example.com/product-page>",
  "headline": "<New summer collection>",
  "price": <49.99>,
  "priceCurrency": "<USD>",
  "discountValue": <10>
}
</script>

Set up product carousels

Product carousels display multiple image previews. You can include up to 10 products.

Code

<script type="application/ld+json">
[
  {
    "@context": "http://schema.org/",
    "@type": "PromotionCard",
    "image": "<https://example.com/product1.jpg>",
    "url": "<https://example.com/product1>",
    "headline": "<Summer dress>",
    "price": <39.99>,
    "priceCurrency": "<USD>",
    "position": <1>
  },
  {
    "@context": "http://schema.org/",
    "@type": "PromotionCard",
    "image": "<https://example.com/product2.jpg>",
    "url": "<https://example.com/product2>",
    "headline": "<Beach sandals>",
    "price": <29.99>,
    "priceCurrency": "<USD>",
    "position": <2>
  }
]
</script>

Image preview and carousel fields

FieldRequired?DescriptionExample
imageYesShows your product imageProduct photo URL
urlYesLinks to your landing pageProduct page URL
headlineOptionalAdds descriptive textNew summer collection
priceOptionalShows price49.99
priceCurrencyOptionalSets currencyUSD
discountValueOptionalShows the discount amount10 (displays as $39.99)
positionOptionalOrders carousel items1, 2, 3

Content guidelines

Expiration date requirements

  • Include time zones: Always specify the time and time zone (example: "2025-12-30T23:59:59-07:00").
  • Remove old dates: Don't keep expired dates in annotations. Gmail sees them as old offers. It won't show your email in bundles.
  • Get double exposure: Emails with expiration dates can appear twice in bundles - once when sent and again within 3 days of expiring.

Content restrictions

Gmail blocks annotations for some content types:

  • Adult content.
  • Debt collection.

Your email might not show annotations if it fits these categories.

Image requirements

Technical specs

  • Format: Use PNG or JPEG only.
  • URLs: Host images on public servers with HTTPS URLs (not HTTP).
  • Aspect ratios:
    • Single images: 1.91:1
    • Carousels: 4:5, 1:1, or 1.91:1
  • Consistency: Use the same aspect ratio for all images in one carousel.
  • Unique URLs: Give each carousel image a different URL.

Quality guidelines

  • Minimize or remove text on images.
  • Keep backgrounds simple and clean.
  • Use high-quality, clear product photos.
  • Use rectangular images without rounded corners.
  • Don't reuse images. Gmail may ignore emails with duplicate images as spam.
  • Gmail automatically center-crops images.

Check if annotations work

To see how your annotations perform in Gmail, follow the testing guide.

Updated 1 day ago