30 апреля 202610 мин чтения

Gmail Annotations: как превратить вкладку «Промоакции» в витрину

Most marketing emails in Gmail land in the Promotions tab. That is not a death sentence — it is an opportunity. Gmail Annotations let you attach rich cards, deal badges, and image carousels directly to your message in that tab. The result: your email looks like a product listing, not another grey line of text. This guide covers the schema.org markup you need, the rendering rules Gmail actually enforces, and the mistakes that cause annotations to silently fail.

What Gmail Annotations actually are

Gmail Annotations are structured data fragments embedded in the HTML head of an email. They use a subset of schema.org vocabulary. When Gmail’s parser finds valid annotation markup, it renders a visual card in the Promotions tab: an image, a logo, a deal badge with a discount amount, or a carousel of product images. The email itself is untouched — the annotation lives in the <head> section and is invisible to the reader if the client does not support it.

Google introduced annotations in 2016 with the Promotions tab redesign and has been expanding the feature since. As of early 2026, annotations render on Gmail for Android, iOS, and the web client. Other mail clients ignore the markup — it does no harm.

There are two main annotation types: the single image promo card and the product carousel. Both are defined through JSON-LD blocks. Gmail also supports a deal badge overlay that shows a discount value or promo code.

Single image promo card

The simplest annotation. It shows one image at the top of the email preview in the Promotions tab, plus an optional deal badge. Here is the complete JSON-LD block:

<script type="application/ld+json">
{
  "@context": "http://schema.org/",
  "@type": "PromotionCard",
  "image": "https://example.com/promo-header.png",
  "url": "https://example.com/sale",
  "headline": "Summer sale — 30% off everything",
  "sender": {
    "@type": "Organization",
    "name": "Example Store"
  },
  "discount": {
    "@type": "DiscountOffer",
    "description": "30% OFF",
    "discountCode": "SUMMER30",
    "availabilityStarts": "2026-06-01T00:00:00-07:00",
    "availabilityEnds": "2026-06-30T23:59:59-07:00"
  }
}
</script>

Place this block inside <head> of your HTML email, before the closing </head> tag. The image field is the hero banner. Gmail renders it at roughly 538×138 pixels on desktop, so horizontal images with a 3.9:1 aspect ratio work best. The image must be served over HTTPS.

The discount object is optional. When present, Gmail shows a green badge with the description text (“30% OFF”) overlaid on the card. The discountCode appears alongside it. The availabilityStarts and availabilityEnds fields control when the badge is visible — outside that window, Gmail hides the deal badge but still shows the image.

Product carousel

The carousel shows up to ten product images that the user can swipe through without opening the email. Each item links to its own URL. This is the annotation type with the highest engagement in e-commerce, because it turns the Promotions tab into a browsable catalog.

<script type="application/ld+json">
[
  {
    "@context": "http://schema.org/",
    "@type": "PromotionCard",
    "image": "https://example.com/promo-header.png",
    "url": "https://example.com/sale",
    "headline": "New arrivals this week",
    "sender": {
      "@type": "Organization",
      "name": "Example Store"
    }
  },
  {
    "@context": "http://schema.org/",
    "@type": "PromotionCard",
    "image": "https://example.com/product-1.png",
    "url": "https://example.com/products/1",
    "headline": "Linen shirt — $49",
    "position": 1
  },
  {
    "@context": "http://schema.org/",
    "@type": "PromotionCard",
    "image": "https://example.com/product-2.png",
    "url": "https://example.com/products/2",
    "headline": "Cotton shorts — $35",
    "position": 2
  },
  {
    "@context": "http://schema.org/",
    "@type": "PromotionCard",
    "image": "https://example.com/product-3.png",
    "url": "https://example.com/products/3",
    "headline": "Canvas sneakers — $65",
    "position": 3
  }
]
</script>

The first object in the array is the “hero” card. It appears as the main image. Subsequent objects (with position values starting from 1) form the carousel items. Each needs its own image and url. Product images should be square (1:1) and at least 116×116 pixels; 200×200 or higher is better.

You can combine the carousel with a deal badge by adding a discount object to the hero card. Gmail will render the badge over the main image and keep the carousel below it.

Deal badge without a promo image

Not every email has a banner. Transactional-promotional hybrids (order confirmations with a cross-sell, for instance) may not have a hero image at all. You can still add a deal badge:

<script type="application/ld+json">
{
  "@context": "http://schema.org/",
  "@type": "DiscountOffer",
  "description": "Free shipping",
  "availabilityStarts": "2026-05-01T00:00:00+03:00",
  "availabilityEnds": "2026-05-07T23:59:59+03:00"
}
</script>

This renders a small badge next to the subject line in the Promotions tab. No image, no carousel — just a green label that says “Free shipping.” Simple, but it catches the eye in a wall of undecorated subjects.

Technical requirements and gotchas

Gmail is strict about annotation parsing. If the markup is slightly off, the annotation disappears without any error. Here is what you need to get right:

Schema context must be HTTP. Use http://schema.org/, not https://schema.org. Gmail’s parser rejects the HTTPS variant for annotation types. This catches almost everyone the first time.
JSON-LD only. Microdata and RDFa are not supported for email annotations. The block must be a <script type="application/ld+json"> tag in the <head>.
Images must be HTTPS. HTTP image URLs are silently ignored. Gmail will not fetch them.
Image size limits. Hero images: minimum 538×138 px, recommended 1076×276 px (2x for retina). Carousel images: minimum 116×116 px, square. Maximum file size is not officially documented, but keep images under 1 MB.
Date format. The availabilityStarts and availabilityEnds fields must be ISO 8601 with a timezone offset. Omitting the timezone or using a different format causes the deal badge to not render.
Sender reputation matters. Gmail only renders annotations for senders with established reputation. New domains or domains with high complaint rates may see annotations ignored even when the markup is valid. Google does not publish the exact threshold.
One annotation block per email. If you include multiple <script> blocks with different annotation types, Gmail uses the first valid one and ignores the rest. For a carousel with a deal badge, combine everything in one JSON array or one object.

Testing annotations before sending

You cannot test annotations by sending from localhost. Gmail ties annotation rendering to sender authentication (SPF, DKIM, DMARC) and domain reputation. There are two practical ways to test:

1. Gmail Promotions Annotations Preview Tool

Google provides an official preview tool. Paste your full HTML email source and it shows how the annotation card will render. This validates the schema and shows a visual preview. It is the fastest feedback loop during development.

https://developers.google.com/gmail/promotab/overview

2. Send a test email from your production ESP

Use your actual sending infrastructure — the same domain, the same ESP, the same authentication. Send to a personal Gmail account and check the Promotions tab. If the annotation does not render, open “Show original” and verify that the JSON-LD block survived your ESP’s HTML processing. Some ESPs strip <script> tags from the head for security reasons.

If your ESP strips JSON-LD from the email head, annotations will never work through that provider. Check before investing time in markup.

ESPs known to preserve JSON-LD annotation blocks (as of early 2026):

Mailchimp (via custom code templates)
Klaviyo
Brevo (Sendinblue)
SendGrid (API sends)
Amazon SES
Postmark

ESPs that use visual editors without custom HTML access may strip the block. Always verify with a real send.

Full working example: promo card with deal badge

Here is a minimal but complete HTML email with a promotion annotation. Copy it, replace the URLs and text, send through your ESP:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width">
  <title>Summer Sale</title>

  <script type="application/ld+json">
  {
    "@context": "http://schema.org/",
    "@type": "PromotionCard",
    "image": "https://cdn.example.com/email/summer-sale-hero.png",
    "url": "https://example.com/summer-sale?utm_source=email",
    "headline": "Summer sale starts now",
    "sender": {
      "@type": "Organization",
      "name": "Example Store"
    },
    "discount": {
      "@type": "DiscountOffer",
      "description": "25% OFF",
      "discountCode": "SUN25",
      "availabilityStarts": "2026-06-01T00:00:00+03:00",
      "availabilityEnds": "2026-06-15T23:59:59+03:00"
    }
  }
  </script>
</head>
<body>
  <!-- your email body here -->
</body>
</html>

Three things to double-check: the @context uses HTTP (not HTTPS), dates include timezone offsets, and the image URL is HTTPS and publicly accessible. Get those right and the annotation renders.

Что такое Gmail Annotations и зачем они нужны

Откройте Gmail, перейдите во вкладку «Промоакции». Часть писем отображается с картинкой-баннером, иногда с зелёным значком скидки, иногда с каруселью товаров. Остальные - обычные строки с темой и отрывком текста. Разница между ними - несколько строк разметки schema.org в заголовке HTML-письма. Эта разметка называется Gmail Annotations.

Аннотации не влияют на то, попадёт ли письмо во вкладку «Промоакции» или в «Основные». Если письмо уже отсортировано в «Промоакции» (а большинство маркетинговых рассылок туда попадает), аннотации делают его заметнее. Вместо того чтобы бороться с вкладкой, вы используете её как витрину. По внутренним данным Google, письма с аннотациями получают на 10-20% больше открытий.

Если вы читали нашу статью про вкладку «Промоакции», вы знаете, что переместить коммерческое письмо в «Основные» сложно и не всегда нужно. Аннотации - альтернативный подход: не уходить из «Промоакций», а выделиться внутри них.

Два типа аннотаций

Промо-карточка (single image). Одно изображение-баннер над превью письма. Может содержать значок скидки с текстом («-30%», «Бесплатная доставка») и промокод. Подходит для анонсов распродаж, запуска продуктов, сезонных акций.

Карусель товаров (product carousel). Горизонтальная лента из нескольких товарных карточек. Пользователь листает их прямо во вкладке, не открывая письмо. Каждая карточка ведёт на свой URL. Подходит для подборок товаров, рекомендаций, каталогов.

Оба типа задаются через JSON-LD-блок в секции <head> HTML-письма. Примеры кода мы показали в английской части статьи выше - они универсальны, язык контента не влияет на разметку.

Требования к изображениям

Баннер промо-карточки: минимум 538×138 px. Для ретина-дисплеев лучше 1076×276 px. Пропорции около 3.9:1. Горизонтальная картинка. HTTPS обязателен.
Товарные изображения карусели: квадратные, минимум 116×116 px. Рекомендуется 200×200 px и выше. Чистый фон, один товар на картинке.
Формат: PNG или JPEG. GIF не поддерживается для аннотаций (хотя работает в теле письма). WebP формально не документирован.
Размер файла: официального лимита нет, но держите изображения до 1 МБ. Тяжёлые файлы Gmail может не подгрузить вовремя.

Ошибки, из-за которых аннотации не работают

Аннотации отваливаются молча. Gmail не показывает ошибок - просто рендерит письмо без карточки. Вот основные причины:

HTTPS в поле @context. Пишут https://schema.org вместо http://schema.org/. Gmail ожидает HTTP-вариант с косой чертой на конце. Это самая частая ошибка.
ESP удаляет тег script. Многие визуальные редакторы email-платформ вырезают <script> из соображений безопасности. Отправьте тестовое письмо, откройте «Показать оригинал» и проверьте, что JSON-LD на месте.
Даты без часового пояса. Поля availabilityStarts и availabilityEnds должны содержать ISO 8601 с таймзоной. Формат 2026-06-01T00:00:00+03:00 - правильно. 2026-06-01 - нет.
HTTP-ссылки на изображения. Все URL изображений должны быть HTTPS. HTTP-ссылки игнорируются без предупреждения.
Низкая репутация домена отправителя. Gmail рендерит аннотации только для доменов с установленной репутацией. Новые домены, домены с высоким bounce rate или большим количеством жалоб на спам могут не получить аннотации даже с корректной разметкой. Порог Google не публикует.
JSON-LD после закрывающего тега head. Блок должен находиться строго внутри <head>. Размещение в <body> не работает для email-аннотаций.

Связь между аннотациями и доставляемостью

Аннотации не помогут, если письмо не доходит до инбокса. Они работают поверх существующей инфраструктуры доставляемости. Базовые условия те же, что для любой рассылки: настроенные SPF, DKIM и DMARC, чистая репутация домена, низкий bounce rate. Если вы уже настроили BIMI - значит, фундамент у вас в порядке.

Отдельный нюанс - чистота базы подписчиков. Отправка писем с аннотациями на мёртвые адреса, спам-ловушки или одноразовые ящики поднимает bounce rate и роняет репутацию домена. Как только репутация падает, Gmail перестаёт рендерить аннотации - даже если разметка идеальна. Получается замкнутый круг: грязная база убивает репутацию, без репутации нет аннотаций, без аннотаций ниже open rate, ниже open rate - хуже метрики.

Поэтому перед тем как внедрять аннотации, проверьте базу. Удалите невалидные адреса, уберите рискованные контакты, убедитесь, что bounce rate ниже 2%. Тогда у аннотаций есть шанс сработать.

Пошаговый план внедрения

Проверьте, что ESP сохраняет JSON-LD. Создайте тестовое письмо с минимальной аннотацией (промо-карточка с одним изображением). Отправьте себе. Откройте «Показать оригинал». Если блок application/ld+json на месте - двигайтесь дальше. Если нет - проверьте настройки шаблона или смените способ отправки на API.
Подготовьте баннер. Горизонтальное изображение 1076×276 px, HTTPS, до 500 КБ. Текст на баннере должен быть читаем в уменьшенном виде - Gmail может отрендерить его в 538 px шириной.
Соберите JSON-LD. Используйте примеры из этой статьи. Для первого теста достаточно промо-карточки без значка скидки - меньше полей, меньше мест для ошибки.
Проверьте через Gmail Preview Tool. Вставьте полный HTML-код письма и убедитесь, что карточка отображается.
Отправьте тест с рабочего домена. Только реальная отправка покажет, рендерит ли Gmail аннотацию для вашего домена.
Добавьте значок скидки. Когда базовая карточка заработает, добавьте объект discount с промокодом и датами.
Попробуйте карусель. Добавьте 3-5 товарных изображений. Проверьте, что каждое ведёт на правильный URL.

Как измерить эффект

Gmail не отдаёт отдельную метрику «annotation views» или «annotation clicks.» Вы видите только стандартные метрики: open rate и click rate. Самый надёжный способ измерить эффект - A/B-тест: одинаковое письмо, одна группа с аннотацией, другая без. Сравните open rate по Gmail-адресам. Разница - вклад аннотации.

На практике мы видим прирост open rate от 8 до 22% у компаний с устоявшейся репутацией домена. У e-commerce с товарными каруселями эффект сильнее, потому что пользователь взаимодействует с контентом до открытия письма. У SaaS и B2B-рассылок эффект скромнее, но всё равно положительный: баннер с названием вебинара или обновлением продукта выделяет письмо на фоне серых строк.

Аннотации работают только для чистых баз

Gmail рендерит промо-карточки для доменов с хорошей репутацией. Хорошая репутация - это низкий bounce rate, минимум жалоб на спам и стабильная аутентификация. Всё начинается с того, кому вы отправляете.

Прежде чем добавлять schema.org-разметку в рассылки, убедитесь, что в базе нет мёртвых адресов и спам-ловушек. Загрузите список в uChecker - 30 бесплатных проверок, чтобы увидеть реальное состояние базы. Чистый список плюс правильная разметка - и вкладка «Промоакции» станет вашим инструментом, а не проблемой.

Gmail AnnotationsGmail промо-карточкиschema.org emailemail structured dataGmail Promotions tabдоставляемость email

← Все статьи