How do I implement Gmail Annotations and troubleshoot common issues?
Michael Ko
Co-founder & CEO, Suped
Published 7 May 2025
Updated 17 Aug 2025
6 min read
Getting your promotional emails to stand out in a crowded inbox can be a challenge. Gmail's Promotions tab is designed to help users discover deals and offers, and Gmail Annotations are a powerful tool to enhance your email's visibility within this tab. By adding structured data to your emails, you can display eye-catching details like images, discounts, and expiration dates directly in the recipient's inbox, even before they open the email.
Implementing Gmail Annotations correctly requires attention to detail, especially when dealing with JSON-LD markup. While it can significantly boost your email engagement, many marketers encounter issues that prevent their annotations from appearing as intended. I often hear questions about why annotations aren't showing up or why emails break when the code is included. Understanding the proper setup and common pitfalls is key to successfully leveraging this feature for your email marketing campaigns.
Understanding Gmail annotations
Gmail Annotations allow you to provide rich previews for your promotional emails in the Promotions tab. This structured data, embedded in your email's HTML, enables features like deal badges, expiration dates, images, and even product carousels to appear prominently. These visual cues can dramatically increase your email's open rates and click-through rates by making your offers more enticing and immediately visible.
The core of implementing these annotations lies in embedding a JSON-LD script within the <head> section of your email's HTML. This script uses schema.org markup to provide Gmail with specific details about your promotion. The data includes elements like the promotion type (e.g., DiscountOffer), a brief description, valid dates, and image URLs. Careful adherence to the required format is crucial for Gmail to correctly parse and display your annotations.
It's important to remember that Gmail aims to provide a consistent experience for users, so your annotations must align with the content of your email. Mismatches or misleading information can lead to your annotations not being displayed, or even worse, impact your sender reputation. Always ensure the data you provide accurately reflects the offer within the email.
Implementing Gmail annotations with JSON-LD
The foundation of Gmail Annotations lies in placing a JSON-LD script within the <head> of your email's HTML. This script communicates directly with Gmail, providing the structured data it needs to display rich previews. The @context field should point to http://schema.org/, while the @type specifies the type of offer, such as DiscountOffer or SaleEvent.
The availabilityStarts and availabilityEnds fields must use the ISO 8601 format (e.g., YYYY-MM-DD). Other crucial fields include description, discountCode, and image (for the featured image). If you're setting up a logo for the Promotions tab, ensure it meets Google's guidelines to display correctly.
Example Gmail annotation JSON-LDhtml
<html>
<head>
<script type="application/ld+json">
[{
"@context": "http://schema.org/",
"@type": "DiscountOffer",
"description": "Save 20% on your first order",
"discountCode": "SAVE20",
"availabilityStarts": "2024-05-19T00:00:00-07:00",
"availabilityEnds": "2025-09-09T23:59:59-07:00",
"image": "https://example.com/images/promo_banner.jpg",
"logo": "https://example.com/images/company_logo.png"
}]
</script>
</head>
<body>
<!-- Your email content goes here -->
</body>
</html>
Once you've added the code, you can use the Google Promotions tab preview tool to validate your markup before sending. This tool is invaluable for catching syntax errors or misconfigurations that might prevent your annotations from displaying correctly.
Common implementation issues and troubleshooting
Even with correct JSON-LD, you might encounter issues. One common problem is your emails not landing in the Promotions tab, or the annotations simply not appearing. Gmail's algorithms consider various factors beyond just the annotation code, including sender reputation and email volume. Sending a single test email to yourself will likely not trigger the annotations, as Gmail expects annotations on bulk sends from established senders.
Another frequent issue is the email breaking entirely after including the annotation code. This often happens if the email marketing platform or WYSIWYG editor you are using modifies the HTML, corrupting the JSON-LD script. Always check the original HTML of the sent email to ensure the JSON-LD remains intact. If your Gmail deliverability rates are low in general, annotations are unlikely to resolve those underlying problems.
Common issues
Annotations not appearing: Email lands in primary inbox or no annotations show in Promotions tab.
Broken email layout: HTML of the email is corrupted or displays incorrectly after adding the JSON-LD.
Incorrect data display: Annotation details are wrong or misaligned with the email content.
Troubleshooting steps
Ensure proper authentication: Verify your domain has SPF, DKIM, and DMARC set up correctly. This is a prerequisite for Gmail to trust your sending.
Check email original HTML: After sending, view the original HTML of the received email to confirm the JSON-LD script is intact and hasn't been altered by your ESP.
Use the preview tool: Always test your annotation code with the Google Promotions tab preview tool before a large send to catch errors early.
Furthermore, Gmail's AI can sometimes override or replace your annotations if it deems its own extracted data more relevant, or if your overall email content and sending patterns don't align with promotional characteristics. This means even perfect code might not guarantee display if other factors are not optimal. Staying on top of your domain reputation is critical.
Best practices for effective Gmail annotations
To maximize your chances of successful annotation display, always ensure your emails are properly authenticated. This means having valid SPF, DKIM, and DMARC records in place. Without these, Gmail is less likely to trust your messages, regardless of annotations, and they may end up in the spam folder. Maintaining a strong sender reputation is a prerequisite for Gmail to display your annotations effectively.
Beyond technical setup, ensure your annotation content is accurate and appealing. Use high-quality images that load quickly and are relevant to your promotion. Avoid using unique images per recipient, as this can flag your emails as suspicious. Always align the promotion details in your JSON-LD with the offer inside the email itself to avoid confusing users or triggering Gmail's spam filters.
Best practices for Gmail annotations
Maintain high sender reputation: A good reputation is key for Gmail to consistently display your annotations.
Accurate and engaging content: Ensure your annotations accurately reflect the email's offer and use compelling visuals.
Use the preview tool religiously: Before any major send, validate your JSON-LD with Google's tool to catch errors.
Views from the trenches
Best practices
Ensure your domain has strong authentication, including SPF, DKIM, and DMARC, as these are prerequisites for annotations to show up.
Always validate your annotation code using Google's Promotions tab preview tool before deploying to a large audience.
Align the content of your annotations, such as images and descriptions, accurately with the actual email content.
Common pitfalls
Testing annotations on single sends, as Gmail typically requires bulk sending from established senders to trigger annotation display.
Using WYSIWYG editors without verifying the final HTML, as they can sometimes alter or corrupt the embedded JSON-LD script.
Providing incorrect schema types or date formats in the JSON-LD, leading to parsing errors by Gmail.
Expert tips
An expert from Email Geeks suggests that Google's AI can sometimes override manual annotations if it perceives a mismatch with the overall email content, emphasizing the importance of a consistent message.
An expert from Email Geeks points out that email marketing platforms occasionally modify the JSON-LD after insertion, recommending a thorough check of the email's original HTML in Gmail.
An expert from Email Geeks recommends focusing on improving overall domain reputation and email authentication as foundational steps, rather than solely relying on annotation code for display.
Marketer view
A marketer from Email Geeks implemented standard JSON to the email header but observed emails landing in the primary tab instead of promotions, even with clear promotional content, and struggled to find research on the "@context" data field.
2024-05-20 - Email Geeks
Marketer view
A marketer from Email Geeks confirmed no discount code was needed as the promotion automatically applied in the cart, simplifying the annotation data.
2024-05-20 - Email Geeks
Final thoughts on Gmail Annotations
Implementing Gmail Annotations can significantly enhance your email marketing efforts by making your promotional messages more visible and engaging in the Gmail Promotions tab. While the technical setup with JSON-LD requires precision, most issues can be resolved by adhering to Google's guidelines, maintaining strong email authentication, and thoroughly testing your code.
By understanding the requirements for these annotations and proactively troubleshooting common problems, you can ensure your campaigns achieve their full potential, capturing subscriber attention and driving conversions directly from the inbox. Continuous monitoring of your email performance and adaptation to Gmail's evolving standards will help you sustain the benefits of these powerful email enhancements.
Gmail, providing the structured data it needs to display rich previews. The @context field should point to http://schema.org/, while the @type specifies the type of offer, such as DiscountOffer or SaleEvent.
Google's guidelines to display correctly.
