Gmail Promotions tab annotations: are they worth it?
TL;DR
Gmail Promotions tab annotations are schema.org markup in your email head that turns a plain row into a card with an image, a logo, a promo code and an expiry date. They render in the Gmail mobile app only, for senders Google has allow-listed, and nobody has published an adoption figure. Our position: an annotation is a click tactic that spends opens to buy clicks. Good bet for a retail sender with a live discount, bad bet for an editorial newsletter whose sponsors are billed on opens.
Gmail Promotions tab annotations have been available to senders for years, and in that time not one independent study has measured how many senders bother. What exists instead is a shelf of help-docs, every one of them published by a company that bills you for the feature: Iterable, Bloomreach, Customer.io, Bluecore, GetResponse. They all explain the markup competently. Not one of them tells you whether it works.
We parse other people's newsletters for a living, so we get asked about this. Below is the version we would defend to a client: what the markup is, why the adoption question has no honest answer yet, and who should skip it.
What Gmail Promotions tab annotations are
An annotation is structured data you put in the head of your email HTML. Gmail reads it and renders your message in the Promotions tab as a card rather than a row. Google's documentation supports two markup formats: JSON-LD inside a script type="application/ld+json" tag, and Microdata using itemscope and itemprop attributes. RDFa gets mentioned in a lot of secondhand blog coverage, including in the docstring of our own extractor, but it does not appear in Google's current spec. Use JSON-LD unless something in your pipeline forces you not to.
Two schema types carry the weight. PromotionCard drives the single image preview and the product carousel, taking image, url, headline, price, priceCurrency and discountValue. Google allows up to ten images in a carousel at aspect ratios of 4:5, 1:1 or 1.91:1, PNG or JPEG, with 1.91:1 for the single preview. DiscountOffer drives deal annotations and deal cards, taking description, discountCode, availabilityStarts and availabilityEnds, plus offerPageUrl and merchantHomepageUrl for the deal card variant.
One constraint matters more than any of that. Annotations render in the Gmail mobile app for users who have the Promotions tab turned on. Desktop Gmail shows your email as an ordinary row. So whatever share of your list reads on desktop sees the send you would have shipped anyway, which is why your preheader still does most of the work.
Why nobody can tell you the adoption rate
Search for the percentage of newsletters using annotations and you will find nothing. Not a low number, not a contested number. No study. The ESP help-docs never quote one either, which is telling, because a vendor with a good adoption stat would print it on the pricing page.
The gap is structural. Annotation markup lives in the raw MIME source of a message and only renders in one tab of one client. You cannot survey it from the outside the way you can survey a website. To measure it you would need to receive promotional mail at scale and parse the head of every issue, which is a small set of organisations, none of whom have published.
We could produce a number from our own ingestion. We are not going to, because it would be one corpus of subscribed senders dressed up as an industry figure, and that dressing-up is how most email statistics get made. Our parser reads JSON-LD script blocks and Microdata attributes out of every issue we take in and records the schema type and markup format it found. That tells you what a given set of competitors is doing. It does not tell you what "the industry" is doing, and a headline percentage would be claiming the second thing while measuring the first.
You can sample it yourself in about ten minutes, which is more than any published figure would give you. Open a promotional email in desktop Gmail, hit the three-dot menu, choose Show original, then search the source for ld+json. Do that across the last twenty promotional emails you received. Our prediction, and it is a prediction rather than a finding: you will find markup in the retail and DTC sends, and nothing at all in the editorial newsletters. If that holds in your mailbox, it tells you who has decided this feature is worth the engineering.
Check who ships annotations, starting with who sends what
Work out which platform a sender is on first. Some ESP editors strip the script tag annotations depend on, so the platform tells you whether a competitor could ship them at all.
Detect a newsletter's ESP →Do Gmail annotations increase open rates?
Here the vendors split, and the split is worth understanding because both camps are arguing past each other.
Validity has made the case that preview surfaces revealing the offer up front can pull opens down, on the reasoning that a recipient who can read the discount from the inbox has no reason to open. Mailgun has raised similar doubts. Mailmodo and Litmus take the other side, arguing that a card with a logo and an image gets noticed in a tab full of grey rows, and that visibility carries clicks with it.
Both are measuring one number and treating it as the scoreboard. An annotation does something specific: it moves information from behind the open to in front of it. Two things follow. Some people who would have opened to find out about the discount now take the discount straight from the card, so your open count falls. Other people who were never going to open at all see a deal card, and some of them click. The tactic trades opens for clicks. That is not a side effect, it is the mechanism.
Which means the decision is about your business model rather than the tactic. If you are a retailer measuring revenue per send, spending opens to buy clicks is a trade you should take. If you sell sponsorships priced on opens, you are handing back the number your invoices are built on. And open rate was already a shaky instrument before annotations arrived, for reasons we covered in what Apple Mail Privacy Protection did to open rates. Anchor the test on clicks and revenue, then check your position against current open rate benchmarks so you know what you gave up. We compare Mailmodo's analytics side in our Newsletrix versus Mailmodo breakdown.
How to add Gmail Promotions tab annotations
The markup is the easy part. Here is a deal annotation, dropped into the head of your email HTML alongside anything else living there:
<script type="application/ld+json">
{
"@context": "http://schema.org/",
"@type": "DiscountOffer",
"description": "20% off everything",
"discountCode": "AUGUST20",
"availabilityStarts": "2026-08-13T09:00:00-04:00",
"availabilityEnds": "2026-08-20T23:59:00-04:00"
}
</script>Dates are ISO 8601 with an offset. Note the http in the context value, which is what Google's examples use. Every other mail client ignores the block entirely, so there is no rendering risk in shipping it.
The part that bites is delivery. Plenty of ESP template editors strip script tags out of email HTML on save, and if yours does, your annotation never leaves the building. Test with a real send to a Gmail address and read the source, rather than trusting the editor preview. If the tag gets stripped and you cannot change it, the Microdata form is your fallback, since it survives as ordinary attributes. Senders on hosted publishing platforms like Beehiiv, Substack or ConvertKit should check whether they can inject head markup at all before planning a campaign around this.
Then there is approval. Annotations render for senders Google has allow-listed, and Google points senders at [email protected] for help with annotation features. Sort your authentication first; our guide to SPF, DKIM and DMARC covers the setup. Even approved, Google's documentation says quality filters and frequency limits affect whether an annotation appears. You are asking, not instructing.
What silently kills an annotation
This is the section the vendor docs skip, and it is the reason we would tell a small team not to bother.
Our validator flags four ways an annotation block breaks once it is in the message: the JSON is malformed, @context is missing, @type is missing, or the root is not an object, usually because someone wrapped it in an array. Beyond the markup itself, an availabilityEnds date in the past kills the card, images outside Google's aspect ratios kill the card, and a stripped script tag means there was never a card.
Now the part that makes this expensive. Gmail tells you nothing. There is no error, no warning, no report. The card simply does not appear, and because it only ever renders on mobile for approved senders, you cannot distinguish broken markup from pending approval from Google deciding not to show it on this particular send. Three very different problems, one identical symptom. Debugging that means sending real mail to real handsets and looking, which is a manual loop nobody enjoys. We would rather spend that hour on the subject line.
When to skip annotations
Skip them if your goal is escaping the Promotions tab. Annotations are a bet on Promotions: they make you look better inside it, which is the opposite of getting out. If Primary is the objective, the work is in sender reputation and engagement, and we wrote that up separately in how to land in Gmail's Primary tab. Pick one strategy. Doing both is incoherent.
Skip them if you have no discount. DiscountOffer wants a code and an expiry date. A B2B or editorial newsletter has neither, and inventing a deal to fill a deal card is a bad reason to run a promotion. There is no annotation type for "good essay this week".
Skip them if you cannot control the head of your template, and check that before you plan the campaign rather than after. The honest summary for most newsletter operators: this is a retail feature with a retail payoff, it costs real engineering time, it fails silently, and the ceiling is a nicer-looking row in the tab your reader visits least. If you sell products with codes and expiry dates, ship it. Otherwise the same hour spent on your first hundred words will pay better, and our notes on Gmail clipping point at a more common culprit than anything in the Promotions tab.
Frequently asked questions
What are Gmail Promotions tab annotations?
They are schema.org markup you place in the head of an email so Gmail can turn a plain row in the Promotions tab into a card with an image, your logo, a promo code and an expiry date. Google's documentation supports two markup formats, JSON-LD in a script tag and Microdata using itemscope and itemprop attributes. The two schema types that matter are PromotionCard, used for a single image preview or a carousel of up to ten images, and DiscountOffer, used for deal annotations and deal cards.
Do Gmail annotations increase open rates?
Probably not, and that is the wrong question. Validity has argued that preview surfaces which reveal the offer up front can reduce opens, because the recipient no longer needs to open to learn the discount. Mailmodo and Litmus argue the opposite from visibility. Both sides are measuring one number. An annotation moves the offer from behind the open to in front of it, so it trades opens for clicks. Judge it on revenue per send, not on open rate.
Do I need Google approval to use Gmail annotations?
Yes in practice. Annotations render for senders Google has allow-listed, and Google's own documentation points senders to [email protected] for help with annotation features. Even once approved, Google states that quality filters and frequency limits affect whether an annotation is shown, so a correctly marked-up email can still render as a plain row. You cannot force the card to appear.
Do annotations work on desktop Gmail?
No. Annotations render in the Gmail mobile app, for users who have the Promotions tab enabled. On desktop Gmail your email appears as a normal row with a subject line and preheader, so all your desktop readers see the version you would have shipped anyway. This is why the preheader still carries the message for a large share of your list.
What percentage of newsletters use Gmail annotations?
No published figure exists, and we are not going to invent one. Annotation markup sits in the raw MIME source of an email and renders in one tab of one mail client, so measuring adoption requires receiving promotional mail at scale and parsing the head of every message. Nobody who can do that has published a number. You can sample it yourself in Gmail with Show original and a search for ld+json.