Why aren't my Gmail Annotations showing up when I send a test email to myself?

No, annotations typically only appear for emails sent in bulk and from senders with a good reputation. Sending a single test email to yourself is not representative of how Gmail processes them for the Promotions tab. Always use the Google preview tool for testing before a larger campaign.

My email is breaking after I include the annotation code. What's wrong?

If your email is breaking, your ESP 's editor (especially WYSIWYG editors) might be altering or corrupting the JSON-LD code. After sending a test, view the email's original HTML to verify the annotation script remains intact and correctly formatted. You may need to insert the script directly into the HTML without editor interference.

Do I need to get my IP address whitelisted by Gmail to use annotations?

No, Gmail no longer requires specific IP address whitelisting for annotations. The key requirements are proper email authentication ( SPF , DKIM , DMARC ) and maintaining a good sender reputation. This ensures Gmail trusts your messages enough to display the enriched previews.

What is the correct value for the '@type' field in the JSON-LD for Gmail Annotations?

The @type field in your JSON-LD should specify a valid schema.org type, such as DiscountOffer or SaleEvent , not free text like "20% OFF". Using an incorrect @type will prevent your annotations from being recognized by Gmail .

Can Gmail's AI extraction interfere with my custom annotations?

Yes, Gmail's AI can perform automatic extraction of promotional data from your email content, even without explicit annotations. If there's a discrepancy between your manual JSON-LD and what the AI detects, the AI's extraction might override your annotations or place the email in a different tab. Consistency is key.

How do I implement Gmail Annotations and troubleshoot common issues? - Troubleshooting - Email deliverability - Knowledge base

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.