Gmail Annotations
Gmail annotations enhance how your email appears in Gmail by embedding schema.org JSON-LD markup in the message content. OptiPub builds this markup for you from a visual editor in the content form, so you never write code. When Gmail recognizes the markup, it can surface richer previews in the Promotions tab and a one-click button in the inbox.
There are three kinds of annotation:
- Deal badge — a discount/offer label shown next to your subject line in the Promotions tab.
- Image cards — a carousel of up to 10 product previews (image, headline, price) shown in the Promotions tab.
- Action button — a one-click "Go-To" button Gmail can show in the inbox row. Available on auto responders only.
Annotations are hints, not guarantees. Gmail decides whether to display them based on its own quality filters, eligibility, and sender reputation, so they may not appear for every recipient. See Google's Annotate emails in the Promotions tab guide for details.
Where to Configure
The Gmail Annotation editor lives in the email settings of each content type:
| Surface | Where to configure | Action button? |
|---|---|---|
| Message | The Gmail Annotation row in the content step | No |
| Resource | Email Settings > Gmail Annotation | No |
| Auto Responder | Gmail Annotation row in the content step | Yes |
| Auto Responder Variation | Email Settings > Gmail Annotation | Yes |
The editor renders a live preview styled like a Gmail message. It uses the selected publication's name and logo/favicon for the brand, and your subject line for the preview text, so what you see closely matches the recipient's inbox.
Enabling and Clearing
By default the annotation is off and the preview shows a masked overlay with an Enable button, making it clear nothing will be added to the email. Click Enable to start configuring.
To turn it back off, use the Clear button inside the preview. This removes the deal, image cards, and action button, and returns the editor to its disabled state. Nothing is saved to the email while the annotation is empty.
Deal Badge
Click the deal badge area in the preview to configure a discount offer (DiscountOffer):
| Field | Notes |
|---|---|
| Deal badge | Short description of the offer (for example, 20% off). Keep it under ~4 words so it doesn't compete with the subject. |
| Discount code | Promo code shown in the inbox, prefixed by Gmail with "Code". |
| Offer starts | Optional start date and time. |
| Offer expires | Optional end date and time. |
Dates are captured in the editor's local time zone and stored as ISO 8601 with the time-zone offset, the same way message scheduling works. An expired offer is never shown by Gmail.
Auto responders reuse one template for every future send, so a fixed expiry will eventually pass and Gmail will stop showing the deal. For evergreen auto responders, leave Offer expires empty.
Image Cards
Click Add in the carousel to add a product card (PromotionCard). You can include up to 10 cards. Each card opens the asset picker so you can choose or upload an image; if you close the picker without choosing one, the empty card is discarded.
| Field | Required | Notes |
|---|---|---|
| Image | Yes | Chosen from your Assets. Must be served over HTTPS. |
| Link URL | Yes | Where the card links when clicked. Must be HTTPS. |
| Headline | No | Short description shown under the image. |
| Price | No | Displayed with the card. |
| Discount | No | Amount subtracted from the price to show an adjusted price. |
Use the ⋮ menu on each card to edit its details, and the × to remove it.
Gmail enforces a few image rules, which the editor validates for you:
- All cards must share one aspect ratio: 4:5, 1:1, or 1.91:1.
- Each image must be unique — Gmail disregards reused images.
- Images must be served over HTTPS.
Validation messages appear under any card that has a problem, and image-quality issues (duplicate, HTTPS, aspect ratio) take priority over the "add a link URL" prompt.
Action Button
The action button is available on auto responders and their variations only, not on bulk messages or resources.
Registration required. Gmail does not make emails actionable for unknown senders. To use Go-To action buttons, your sending domain must be registered (whitelisted) with Google and meet their sender requirements first — otherwise the markup is added but Gmail will not render the button. See Google's Register with Google guide.
Gmail can show a one-click Go-To action button in the inbox row. In the preview header, click the Add + button to configure it:
| Field | Notes |
|---|---|
| Button label | The text shown on the button (for example, View offer). |
| Button URL | Where the button links. Must be served over HTTPS. |
A button needs both a label and a URL to be valid. If the label is set but the URL is missing or not HTTPS, the button turns red and shows a ! indicator so you can spot the problem before opening the menu.
How It Works
When the email is prepared for sending, OptiPub converts your annotation into a single <script type="application/ld+json"> block injected into the <head> of the content:
- The deal badge becomes a
DiscountOffernode. - Each image card becomes a
PromotionCardnode. - The action button becomes an
EmailMessagenode with aViewActionpotentialAction.
OptiPub owns all JSON-LD in the email — re-processing the same content (for example, copying a message) regenerates the markup from your saved settings rather than stacking duplicate scripts.