Mailkit’s Guide to Schemas – Part 3
28 March, 2025
Mailkit’s Guide to Schemas – Part 4
Now that we have arrived at the final saga of our Schemas guide, I just wanted to thank you for reading. This was designed to be a reference for folks creating their own schemas, and if it helps you dear reader, then I am pleased. Maybe you don’t read it fully today or tomorrow, but hopefully it will help you one day in the future when you begin to implement schemas in your own emails.
One key takeaway I would like to reiterate: Yes, schemas make your emails more interactive, easy to read, and beautiful. However, the power of schemas lies not just in their aesthetic appeal, but also in their ability to connect the dots between your various email marketing channels. By adding schemas to your emails, Mailbox Providers (MBPs) can pair the reputation of your emails to your website branding, thus allowing for more accurate classification when they receive your mail. And as we’ve mentioned in previous posts, when MBPs have an easier time recognizing your brand reputation, that is a good thing for your deliverability and ultimately inbox placement.
Stand out in the inbox with Email Annotations for promotional mail
Email Annotations, as the title mentions, are able to be used for promotional or marketing mail. The code samples below should be added to the head section of the HTML of your email. Here are main schemas to know when it comes to Email Annotations. They are:
- DiscountOffer, which allows you to create Deal annotations.
- PromotionCard, which has some flexibility depending on how many images you want to include:
- Single Image preview
- Product Carousels
- Organization, by far the most simple of the three, is used to add a logo to a promotion.
If you are experiencing any problems when testing out email annotations, it is a good idea to make sure you are following best practices for each type.
DiscountOffer code, as viewed on desktop
Deal Annotations/Discount Offer
This is a text-based medium, but you can still see the tiny green image of a tag in the example above, from Notino. Deal annotations include details such as a discount code or expiration date – and the expiration date MUST be for a date in the future, if you would like that code to be displayed as expected. Otherwise, check out the yellow images below to see how a Deal annotation will display befor and after the expiration timestamp.
JSON-LD
<script type="application/ld+json">
[{
"@context": "http://schema.org/",
"@type": "EmailMessage",
"subjectLine": "15% sleva na celou objednávku k Mezinárodnímu dni žen"
},{
"@context": "http://schema.org/",
"@type": "DiscountOffer",
"description": "",
"discountCode": "womanday",
"availabilityStarts": "2025-03-03T00:00:00+00:00",
"availabilityEnds": "2025-03-10T00:00:00+00:00"
}]
</script>
Microdata
<div itemscope itemtype="http://schema.org/EmailMessage">
<meta itemprop="subjectLine" content="15% sleva na celou objednávku k Mezinárodnímu dni žen"/>
<div itemscope itemtype="http://schema.org/DiscountOffer">
<meta itemprop="description" content=""/>
<meta itemprop="discountCode" content="womanday"/>
<meta itemprop="availabilityStarts" content="2025-03-03T00:00:00+00:00"/>
<meta itemprop="availabilityEnds" content="2025-03-10T00:00:00+00:00"/>
</div>
</div>
Example Discount code + Single Image preview schema in action, compliments of Google.
PromotionCards
While Deal Annotations are primarily text-based, the two PromotionCard types provide a way to visually display your promotions. Of all the Email Annotations, PromotionCard annotations (which include Single Image Preview and Product Carousels) come with the most complications. If you are having trouble testing these, here are some things to note:
- The schema will only display if the end recipient has a Gmail account that was created outside of the EU. This limitation exists for now, but we are hopeful that Gmail will roll this feature out worldwide.
- It also needs to be opened on mobile from the Promotions tab in order to view the product carousel.
- The email itself must be sent to more than 100 recipients to reach the volume threshold for Google.
Example of an (expired) promotion card with a Single Image Preview, from Gmail’s mobile app.
Single Image Preview
Single image preview annotations is an opportunity to highlight just one image in the Gmail Promotions Tab.
JSON-LD
<script type="application/ld+json">
[{
"@context": "http://schema.org/",
"@type": "PromotionCard",
"image": "https://email-images.ritual.com/Marketing+Emails/Monthly+Blast/Asset+Folder/Photo_Bank/3bottlesyellow.jpg",
"url": "https://ritual.com/",
}]
</script>
Microdata
<div itemscope itemtype="http://schema.org/PromotionCard">
<meta itemprop="image" content="https://email-images.ritual.com/Marketing+Emails/Monthly+Blast/Asset+Folder/Photo_Bank/3bottlesyellow.jpg" />
<meta itemprop="url" content="https://ritual.com/"/>
</div>
Example of how Polish provider Onet displays Product Carousel code on their mobile app.
Product Carousel
Product carousels will have up to 10 unique image previews for a given promotion. These are best used for a new seasonal release, when you would like to showcase a wide array of new products.
JSON-LD
<script type="application/ld+json">
[{
"@context": "http://schema.org/",
"@type": "PromotionCard",
"image": "https://skypicker-pub.s3.eu-west-1.amazonaws.com/email+campaigns/gmail_annotations/2024_q3_price_level_0.jpg",
"url": "https://www.kiwi.com/searchDeep?origin=prague_cz&transport=aircraft&departure=14-11-2024_13-12-2024&priceMin=1&priceMax=49&return=no-return¤cy=eur&sortBy=price&sortAggregateBy=price&pageName=tilesPage&utm_term=markup-level-1",
"headline": "Deals under 49 Euro",
"position": 1
},{
"@context": "http://schema.org/",
"@type": "PromotionCard",
"image": "https://skypicker-pub.s3.eu-west-1.amazonaws.com/email+campaigns/gmail_annotations/2024_q3_price_level_1.jpg",
"url": "https://www.kiwi.com/searchDeep?origin=prague_cz&transport=aircraft&departure=14-11-2024_13-12-2024&priceMin=1&priceMax=99&return=no-return¤cy=eur&sortBy=price&sortAggregateBy=price&pageName=tilesPage&utm_term=markup-level-2",
"headline": "Deals under 99 Euro",
"position": 2},{
"@context": "http://schema.org/",
"@type": "PromotionCard",
"image": "https://skypicker-pub.s3.eu-west-1.amazonaws.com/email+campaigns/gmail_annotations/2024_q3_price_level_2.jpg",
"url": "https://www.kiwi.com/searchDeep?origin=prague_cz&transport=aircraft&departure=14-11-2024_13-12-2024&priceMin=1&priceMax=199&return=no-return¤cy=eur&sortBy=price&sortAggregateBy=price&pageName=tilesPage&utm_term=markup-level-3",
"headline": "Deals under 199 Euro",
"position": 3},{
"@context": "http://schema.org/",
"@type": "PromotionCard",
"image": "https://skypicker-pub.s3.eu-west-1.amazonaws.com/email+campaigns/gmail_annotations/2024_q3_price_level_3.jpg",
"url": "https://www.kiwi.com/searchDeep?origin=prague_cz&transport=aircraft&departure=14-11-2024_13-12-2024&priceMin=199&priceMax=9999&return=no-return¤cy=eur&sortBy=price&sortAggregateBy=price&pageName=tilesPage&utm_term=markup-level-4",
"headline": "Deals over 199 Euro",
"position": 4}]
</script>
Microdata
<div itemscope itemtype="http://schema.org/PromotionCard">
<meta itemprop="image" content="https://skypicker-pub.s3.eu-west-1.amazonaws.com/email+campaigns/gmail_annotations/2024_q3_price_level_0.jpg"/>
<meta itemprop="url" content="https://www.kiwi.com/searchDeep?origin=prague_cz&transport=aircraft&departure=14-11-2024_13-12-2024&priceMin=1&priceMax=49&return=no-return¤cy=eur&sortBy=price&sortAggregateBy=price&pageName=tilesPage&utm_term=markup-level-1"/>
<meta itemprop="headline" content="Deals under 49 Euro"/>
<meta itemprop="position" content="1"/>
</div>
<div itemscope itemtype="http://schema.org/PromotionCard">
<meta itemprop="image" content="https://skypicker-pub.s3.eu-west-1.amazonaws.com/email+campaigns/gmail_annotations/2024_q3_price_level_1.jpg"/>
<meta itemprop="url" content="https://www.kiwi.com/searchDeep?origin=prague_cz&transport=aircraft&departure=14-11-2024_13-12-2024&priceMin=1&priceMax=99&return=no-return¤cy=eur&sortBy=price&sortAggregateBy=price&pageName=tilesPage&utm_term=markup-level-2"/>
<meta itemprop="headline" content="Deals under 99 Euro"/>
<meta itemprop="position" content="2"/>
</div>
<div itemscope itemtype="http://schema.org/PromotionCard">
<meta itemprop="image" content="https://skypicker-pub.s3.eu-west-1.amazonaws.com/email+campaigns/gmail_annotations/2024_q3_price_level_2.jpg"/>
<meta itemprop="url" content="https://www.kiwi.com/searchDeep?origin=prague_cz&transport=aircraft&departure=14-11-2024_13-12-2024&priceMin=1&priceMax=199&return=no-return¤cy=eur&sortBy=price&sortAggregateBy=price&pageName=tilesPage&utm_term=markup-level-3"/>
<meta itemprop="headline" content="Deals under 199 Euro"/>
<meta itemprop="position" content="3"/>
</div>
<div itemscope itemtype="http://schema.org/PromotionCard">
<meta itemprop="image" content="https://skypicker-pub.s3.eu-west-1.amazonaws.com/email+campaigns/gmail_annotations/2024_q3_price_level_3.jpg"/>
<meta itemprop="url" content="https://www.kiwi.com/searchDeep?origin=prague_cz&transport=aircraft&departure=14-11-2024_13-12-2024&priceMin=199&priceMax=9999&return=no-return¤cy=eur&sortBy=price&sortAggregateBy=price&pageName=tilesPage&utm_term=markup-level-4"/>
<meta itemprop="headline" content="Deals over 199 Euro"/>
<meta itemprop="position" content="4"/>
</div>
Organization
Possibly the most straightforward option, this type allows you to set a logo to include in the promotion.
One thing to note here: we are not including an image of the Organization schema in action, because you cannot always expect it to display the logo. The main benefit to adding the Organization schema to your emails is in the connection MBPs are able to make between your emails and your online branding presence.
We mentioned this schema type in Part 3 as well, because it is so versatile and can be paired with both transactional and promotional schemas.
JSON-LD
<script type="application/ld+json">
{
"@context": "http://schema.org",
"@type": "EmailMessage",
"description": "Check out your order"
},
"publisher": {
"@type": "Organization",
"name": "Mailkit",
"url": "https://www.mailkit.com",
"url/googlePlus": "https://logo.jpg"
}
</script>
Microdata
<div itemscope itemtype="http://schema.org/EmailMessage">
<meta itemprop="description" content="Check out your order"/>
<div itemprop="seller" itemscope itemtype="https://schema.org/Organization">
<meta itemprop="name" content="Mailkit"/>
<meta itemprop="url" href="https://www.mailkit.com" content="https://www.mailkit.com" />
<img itemprop="logo" src="https://logo.jpg" alt="Logo" height="0" />
</div>
</div>
Who supports schemas?
Gmail and Yahoo
Gmail and Yahoo are by far the biggest MBPs that support schemas, and they share the same strictness of requirements for respecting and displaying schemas.
Onet
Very recently as of October 2024, it seems that Onet is supporting schemas. In my own testing, I can confirm that both desktop and mobile versions of Onet display Discount codes and Promotion Cards. As previously stated, it is always a good idea to do your own extensive testing prior to sending large campaigns, expecting them to display in the Promotions tab with codes surfaced.
Image from the main view in Onet Poczta using the DiscountOffer schema code.
Example of a birthday coupon after clicking on the email above.
Interia
Although Interia does also recently support schemas, it seems that they have stricter requirements - specifically, it is necessary for any sender using schemas in their content to also enable Boost, which improves security and verifies the authenticity of messages. Boost is a paid add-on to Interia Premium Sender services. The price varies by contract, but for Mailkit clients, it’s 150 Euro/month. Boost enables the BIMI logo (or a manually provided logo), schemas, and other features. You can reach out to Interia for more details on getting set up with Boost.
In conclusion
Adding schemas to your email templates is one of the easiest, most cost effective, and prettiest ways to improve inbox placement - assuming all best common practices are already being followed. That said, like with anything, these changes are more about the engagement and UX boost that will result in improved deliverability.
In this growing email marketing landscape, standing out in the inbox and improving the user experience of your readers is of utmost importance. Schema-enhanced emails are truly the way of the future. We hope this guide gives you the tools you need to succeed, but we are always open to feedback on future improvements, so stay in touch and happy coding!
