Google annotations: promotion markup in Gmail

What this screen is

The sidebar calls it Google annotations. The screen itself is headed Google annotations analysis, and the subtitle underneath names what it looks for: the Schema.org structured data that lets Gmail show an email as something richer than a subject line. Two questions get answered here. Do the newsletters you track ship that markup, and is what they ship valid?

Annotations are a block of machine-readable data hidden inside the email HTML. Gmail reads it to build the extras that sit around a message. A promo card with a price and an expiry date in the Promotions tab. A loyalty card, a flight or hotel summary, a parcel tracking line, an RSVP button. None of that is visible when you open a competitor's email in a normal preview, so you cannot tell by looking whether a brand has put engineering time into rich Gmail rendering. This screen is where that layer becomes visible.

The screen has two halves. The outward half counts what your tracked senders do. It totals the annotation objects and the emails carrying them, works out what share of your collection that represents, groups everything by Schema.org type and follows whether adoption has risen over the last twelve months. The inward half is a validator. Markup passes when it can be read and declares both of the fields Gmail requires, and the card lists the structural problem behind everything that fails. Every problem comes with example subject lines, so you can go and fix your own template.

Two things it will not tell you. It never reports opens, clicks or how many people saw a promo card, because Newsletrix receives these emails as an ordinary subscriber. And it does not preview the Gmail rendering. The validity check confirms that a block of markup can be read and declares a context and a type. It does not verify that the type is a real Schema.org type, that the price is formatted correctly, or that Gmail will choose to render anything at all. Gmail's decision also turns on sender registration and whitelisting, which nothing in the email body reveals.

Expect small numbers. Structured email markup is a niche practice concentrated in retail, travel and ticketing. A Coverage figure of two or three percent across a mixed set of tracked newsletters is a normal, healthy reading, not a sign that the screen is broken.

Open it when

• You want to know whether competitors in your set already use Gmail promo annotations before you spend engineering time adding them yourself.
• You have just added Schema.org markup to your own template and want to confirm it can be read and carries both required fields.
• A Gmail promo card stopped rendering and you need to rule out malformed markup before blaming Gmail.
• You are preparing a deck slide on annotation adoption in your category and need a twelve-month trend line with real counts behind it.
• You want a quick list of the newest annotated sends, including the product name and price a brand exposed in its markup.
• You are auditing a new client's competitive set and want a quick read on how technically mature their rivals are.

Screen anatomy

One scrolling column, top to bottom. The header and the explainer banner come first, then a two-card row holding the trend and the validator, then three tiles, then two charts and two tables. Numbers on the mock match the walk-through underneath it.

1. Why annotations matter A fixed explainer. Its five tiles name what Gmail can do with each family of markup, from promo tab highlights through to event RSVPs, and two links go out to Google's email markup spec and the Schema.org email vocabulary. It is open on every visit and collapses with the Hide control.
2. Adoption rate trend Monthly coverage over the last twelve months, drawn as an area sparkline. The headline prints the first month and the latest one, the pill gives the change in percentage points, and the footer carries the peak month and the raw ratio behind the last point.
3. Validator feedback The share of sampled markup that passes the two-field check, next to a health badge. Below that, one block per structural problem, each with a fix hint and up to three example subject lines. Three external tools sit at the bottom of the card; they check a snippet you paste.
4. Total annotations How many individual markup objects were found across your collection. One email can contribute several, so this is always at least as large as the next tile.
5. Newsletters with annotations How many distinct emails carried at least one annotation. This is the numerator of the Coverage tile.
6. Coverage The share of everything you have ever collected that carries any markup, shown to two decimals with the caption "of all newsletters". Lifetime, with no date window.
7. Annotation types A doughnut of markup objects per Schema.org type. The biggest arc is the vocabulary your tracked set leans on, typically Product and Offer for retail and Event for webinars.
8. Markup formats A doughnut of the encodings the markup was found in. Only two ever appear, json-ld and microdata.
9. Annotation type breakdown One row per type and format pair with its count, most frequent first. This is the exact pairing behind both doughnuts, useful when the same type appears in two encodings.
10. Recent annotations The newest annotated sends, with the product, event or offer name and price lifted out of the markup, the subject line and sender address, and the send date.
11. Page header and help button The title, the subtitle and a round question-mark button on the right, which opens a static explainer called "Gmail Optimization Insights". Its wording is the same for every account.
12. Loading state The two top cards each show a centred spinner and both tables show a single spinner row while the screen is still filling in. It loads once, when you open it.
13. Empty states Each panel has its own wording rather than one shared empty screen. They are shown in the second mock further down.

Every panel explained

Why annotations matter

A tinted banner. Five tiles map each family of annotation to the Gmail feature it drives, and two links point at the official specifications.

How it is calculated. It is not. The copy is fixed, identical for every account, and it never looks at your own newsletters at all. The five tiles pair Offer and Product with promo tab highlights, LoyaltyCard and OrderAction with loyalty cards, the three reservation types with flight and hotel confirmations, ParcelDelivery and Order with tracking summaries, and Event and ConfirmAction with RSVPs.

How to read it. As a vocabulary map to read before the type doughnut, so that seeing "Offer" or "FlightReservation" in your own data means something concrete. It is open by default on every visit, and collapsing it is not remembered between visits.

Adoption rate trend

The share of your newsletters carrying markup, month by month, over the last twelve months.

How it is calculated. Every newsletter sent inside the last twelve months is grouped by its calendar month. For each month, the count of distinct emails carrying at least one annotation is divided by the count of distinct emails in that month, multiplied by 100 and rounded to one decimal. The headline compares only the first month present with the last month present, and the pill shows that difference in percentage points. Colour follows a threshold. Above +1pp the pill turns green with an up arrow, below -1pp it turns red with a down arrow, and anything in between stays grey and flat. Peak is simply the highest monthly value in the window.

How to read it. A rising line means the brands you track are adopting rich Gmail rendering, which is a reason to take the format seriously in your own roadmap. A flat line near zero means annotations are not yet a competitive factor in your set.

Validator feedback

A pass rate for the markup Newsletrix has collected, a health badge, and a list of the structural problems found, each with example sends.

How it is calculated. The card checks the 500 most recent annotations, newest first. Markup that is empty or cannot be read is flagged as malformed, and markup that is neither a single object nor a list of them shows up under an unexpected root shape. Where one email carries a list of annotation objects, only the first counts towards the pass rate. An annotation counts as valid only when both @context and @type are present and non-empty. The pass rate is valid divided by checked, as a percentage with one decimal. Four fixed bands drive the badge. 95% and above is "Healthy", 80 to 94.9 is "Mostly OK", 50 to 79.9 is "Needs work" and below 50 is "Broken". Only issues with a count above zero are shown, and each issue lists up to three example subject lines.

How to read it. Anything under 100% means some of the markup in your set would silently fail to produce a Gmail card. Use the example subject lines to find the offending sends, then paste the snippet into one of the three linked tools. Those tools check the snippet you give them and nothing else; they never see your Newsletrix account.

Total annotations

The raw number of markup objects found across your newsletters.

How it is calculated. One count per annotation object found, across everything you have collected, with no date window. A single email that embeds a Product, an Offer and an Organization contributes three.

How to read it. As volume of markup, not volume of email. Divide it by the next tile to see how rich the average annotated send is.

Newsletters with annotations

How many distinct emails carried at least one annotation.

How it is calculated. A count of the distinct emails carrying at least one annotation, again across your whole history.

How to read it. This is the numerator of Coverage. A plain-text send has no HTML for markup to hide in, so it can never show up here.

Coverage

The share of your collected newsletters that carry any markup, to two decimals.

How it is calculated. Newsletters with annotations divided by all newsletters you have collected, multiplied by 100, shown with two decimal places. If you have collected nothing, it reads 0.00%.

How to read it. As a lifetime baseline for your whole tracked set. Low single digits is the normal reading for a mixed set of senders.

Annotation types

A doughnut showing how many markup objects fall into each Schema.org type.

How it is calculated. Every markup object in your collection counts once, and the slices are the totals per type. Labels carry the short type name the markup declares, so a sender writing out the full Schema.org address for Product still shows as Product. Markup that declares no type at all shows as Unknown. The slice palette is fixed at six colours, in the order blue, purple, green, amber, red, pink.

How to read it. As the vocabulary your tracked brands actually use. Product and Offer dominance means retail promotion markup. A meaningful Event slice means webinar or ticketing senders in your set. A large Unknown slice usually means senders are wrapping their markup in a container object rather than declaring a top-level type.

Markup formats

A doughnut showing which encoding the markup was written in.

How it is calculated. The same objects, totalled by encoding instead of by type. Markup that never names its encoding shows as Unknown. The palette here is purple, blue, green.

How to read it. A dominant json-ld share is normal and is what Google's own email markup guidance recommends. A microdata share means a brand inlined the markup into the body HTML instead.

Annotation type breakdown

A table of every type and format pair with its count, most frequent first.

How it is calculated. One row per type and format pair, with the number of annotations behind it, largest first. Anything the markup left blank shows as an Unknown badge. There is no cap and no pagination, so a set with many exotic types produces a long table.

How to read it. This is the source data for both doughnuts, which is why it is worth scanning when the same type appears twice. Seeing Event under both json-ld and microdata usually means two different senders, or one sender who changed template.

Recent annotations

A table of the newest annotated sends with the details each brand exposed in its markup.

How it is calculated. The table lists the 20 newest annotated sends by date. Details shows the product name where the markup carries one, otherwise the event name, otherwise the offer type, with the currency and price on a second line when a price is published. The Newsletter column shows the subject line over the sender address, and dates print as a short month, day and year. Where a value is missing you get a dash or "N/A".

How to read it. As a spot check on what competitors are actually publishing. Product names and prices here come straight out of the markup, not out of the email body, which is why they are sometimes more precise than the visible copy. Prices only appear for Product and Offer shapes; Event rows carry the event name with no date column of their own.

Empty and loading states

Each panel carries its own empty message rather than one shared empty screen, which is useful because they fail for different reasons.

How it is calculated. The adoption card shows "No trend data yet" when there are not enough months of history. The validator card shows "No annotations to validate" when no markup exists to inspect. Both doughnuts show "No data available", the breakdown table shows "No annotation data available" and the examples table shows "No recent annotations found". The three tiles fall back to 0 and Coverage to 0.00%.

How to read it. An empty screen with a healthy newsletter count almost always means your tracked senders simply do not use markup, which is itself a finding. An empty screen on a brand-new account means nothing has been collected and analysed yet.

Metric definitions

Filters and controls

That is the complete list. There is deliberately no date range, no brand selector, no type filter, no search, no sort control, no export and no pagination on this screen, and no refresh button either. The screen fills in once when you open it, so reload the page to pull in newer sends. If you need annotations sliced by brand, start from Brands or Newsletters instead. Everything here is already scoped to your own account and your own tracked newsletters.

How to use it

1. Read the banner first, once The five tiles tell you which Gmail feature each markup family drives. Without that map, the type doughnut is just a list of nouns. After the first visit you can collapse it.
2. Check Coverage against the sparkline The tile gives you the lifetime baseline, the last sparkline point gives you the current month. If the current month is well above the lifetime figure, adoption in your set is accelerating and the format deserves a place on your roadmap.
3. Find out which vocabulary matters in your category Read the Annotation types doughnut, then confirm the pairing in the breakdown table. If Product and Offer dominate, promo cards are the play. If Event leads, the value is in RSVP actions instead.
4. Turn the validator inward If your own newsletter is in the tracked set, the validity rate and the issue blocks are a free audit of your template. Take the example subject lines, pull the snippet from the send, and paste it into the Gmail Annotations tester.
5. Spot check the recent list before you build The 20 newest rows show real product names and prices competitors exposed. That tells you how much detail brands in your space are comfortable publishing, which is a useful reference point for your own markup scope.
6. Come back after your next template change The screen only reflects what has been collected and analysed, so re-check it a send or two after you ship markup rather than the same afternoon.

Limits and caveats

• Validity is a two-field check, not full specification validation. Only the presence of @context and @type is tested. A block of markup with a nonsense type, a badly formatted price or missing required sub-properties still counts as valid here.
• The validator samples. It inspects the 500 most recent annotations. The tiles and the breakdown table do not sample, which is why their totals can be far larger than "500 checked".
• Per-issue counts cap at five. Any single issue displays at most "5 flagged" regardless of how many sends it affects. The summary line above the issues carries the accurate figure for the sample.
• RDFa markup is invisible. Only json-ld and microdata are read. A sender using RDFa looks identical to a sender using nothing.
• Microdata is under-counted. At most one Microdata item is counted per email, so the split between the two format slices understates Microdata volume.
• Only a few fields from the markup reach the screen. Product name, price, currency and event name are what you see in the Recent annotations table. Everything else a sender published is shown nowhere on this screen.
• Older months can look empty. A newsletter carries no annotations here until it has been analysed, so sends collected before this screen existed contribute nothing to the trend and leave older months looking emptier than they were.

FAQ

Related screens