Mailkit’s Guide to Schemas - Part 3
28 March, 2025
Mailkit’s Guide to Schemas - Part 2
Before we dive into schema testing strategies, we should discuss the difference between transactional mail and bulk marketing, or promotional mail (we will use these last two terms interchangeably)
Transactional vs Bulk marketing email
Transactional email is a bit more straightforward. These are the 1-1 order confirmation or shipping notification emails you receive after placing an order online. They are your password reset emails, or messages from your bank letting you know about a potential security issue. You can think of transactional mail as a reactive medium that is triggered based on an event or an action taken by the end recipient (not necessarily a recent action). These emails may have specific recipient data such as name and salutation, but they may also contain address information, order number, account data, invoice information, and many more pieces of data, depending on the nature of the email.
Conversely, promotional mail is a purely commercial medium used by senders to reach out proactively to a database of emails with an announcement or update. These are, for example, emails promoting a new clothing or perfume line, a holiday sale, or a periodic update from the company. While these emails may also contain some personalization such as first name and salutation, it is rare that they will contain too much personalized information. And while personalization and segmentation is highly recommended for this kind of mail to increase the likelihood of engagement, promotional mail by design is meant to engage a wider audience, and is generally sent in bulk to a database of emails.
One other significant difference between these two mail streams is that only bulk promotional mail requires an unsubscribe link (according to the Yahoogle updates from October 2023). By its very nature, purely transactional email is wanted mail and there is not a reason to unsubscribe from it. For example, it doesn’t make sense to unsubscribe from an email containing your order receipt or flight details. If you are resetting your password, it is in your best interest to receive the email that allows you to do so. If you place an order on a website, you want to receive the order notification email that documents the order and provides updates so you know what to expect moving forward. And so on.
Further, depending on the vertical and region, these types of emails may also be required by law. For that reason, there are also strict rules around putting promotional content in transactional email – it can be quite nuanced, but in short, you should probably steer clear of doing so (especially in the EU). Even a legitimately transactional email can be considered promotional if there is a sales pitch in the message. The biggest risk here is that including promotional content may cause your mail to be misclassified, making necessary, important, and often time sensitive mail less noticeable in the inbox.
As these two channels (transactional vs promotional) serve different purposes, it makes sense to have different schemas for each, and for them to have different requirements. For transactional mail, we will talk about how to use Schema Markup (Inbox Actions, Orders, and Reservations) to streamline the user experience (UX). For promotional mail, we will discuss how Email Annotations can make your bulk marketing mail stand out in the inbox.
Streamline the UX with Schema Markup for transactional mail
Meeting sender requirements
It is absolutely worth mentioning that there are more hoops to jump through when it comes to implementing Schema Markup (such as Inbox Actions), for transactional mail. It will involve first making sure you are building a positive reputation for your sending domain using the steps below, and then ultimately registering your domain with Google.
In order to qualify for Schema Markup and register your domain with Google, you must first:
- Be sending from a domain authenticated with DKIM and SPF.
- Since Mailkit and Omnivery already require senders to set up these records, along with DMARC, this part should be complete for our customers.
- Have implemented the new Yahoogle requirements outlined in late 2023.
- Already be sending a consistent volume to Gmail domains (defined as 100 emails a day at a minimum), maintained over a period of at least three weeks.
- Have a very low spam rate (less than 0.3%). If you are unsure of your spam rate, you can lean on Google Postmaster Tools as a resource here.
- This is a great tool to use even outside of schemas, if you are able to interpret the results.
Registering with Google
Once you have met the above requirements solidly for about a month, it is time to register your domain with Google:
- Send the email from your production servers, and from the email domain you are registering with Google, directly to schema.whitelisting+sample@gmail.com.
- Make sure this is a direct send and not a test or a forward since Gmail will strip schema from forwarded mail.
- Make sure the email contains your markup/schema and it has been checked for errors (more on testing your schema below).
- Include as much information as possible in this schema.
- And finally, fill out the Google registration form.
It is necessary to complete all these steps in order to have your application reviewed. If you fill out the registration form and do not send in the schema samples (or vice versa), you risk your application being silently discarded.
Mobile and desktop views of test email using Apps Script method described below.
How to test Schema Markup
It is possible (and recommended) to test your schemas before officially registering with Google. Here are some methods and resources below:
- Our favorite: If you are more on the technical side (or even if you are not – don’t doubt yourself!), you can create an Apps script in Google that you can use to send an email to/from yourself. In this case, setting up DKIM or SPF is not necessary, as you are sidestepping the registration guidelines outlined above.
- We are attaching images below to illustrate what this process looks like, but to see the code in action, check out the emails on mobile and desktop above with “Test Email Markup” as the subject line.
App Script Code.gs
Full HTML of the test email
- There is the Email Markup Tester tool, where you can paste in your full HTML email with schemas included, and it will parse the schema, or tell you where you went wrong.
- Linked in the Email Markup Tester tool is also the Structured Data Markup Helper, which allows you to select a data type to get even more granular. This is available for some Reservation and Order related schema.
- You are also able to send your schemas to and from the same Google account (from me@gmail.com to me@gmail.com) and they will display in the Gmail app. This method will ignore registration guidelines listed above, since it is simply self-testing. That said, DKIM or SPF must still be set up in this case.
- This is one of the more difficult ways to test schema markup functionality, and if you want to see schemas in action before registering, we personally recommend the first option above for testing (Apps Script).
Stand out in the inbox with Email Annotations for promotional mail
How to test Email Annotations
- When you want to test your Email Annotations, you can paste the HTML in here to preview how the content should look. This tool is specifically for:
- Deal annotations
- Product carousels
- Single image preview
- It is also possible to use the Email Markup Tester tool for Email Annotations.
Best Practices and Troubleshooting
Setting up Email Annotations in the Promotions tab is much more streamlined than using Inbox Actions, but there are still caveats to keep in mind:
- Put your code for Email Annotations in between the opening and closing <head> tags.
- Email Annotations only exist in the Promotions tab in the inbox. If your mail is ending up in a different folder, make sure the email domain you are sending from is one that is typically used for promotional mail. Also ensure you are not using any filters that are changing where your promotional mail is delivered.
- And finally, it may be necessary to drag your mail to the Promotions folder if it is ending up somewhere else. After doing so, make sure to send an additional testing email from the same email address and domain and a different subject line. This should ensure the email ends up in the right folder.
- An email containing sensitive topics (such as adult content or debt collection) may not be bundled and displayed, even with the annotations.
- Make sure the expiration date on your DiscountOffer is a time in the future, or the code may not display.
- Avoid using text only since this medium is designed for images. When using images, crop appropriately since all images are automatically center-cropped. The supported aspect ratios are 4:5, 1:1, 1.91:1.
- Product carousels are only visible on mobile, specifically using the native Gmail mail application.
- There is something referred to as Gmail’s density cap, where only a limited number of Product carousels will be displayed in an inbox per day. If you are sending otherwise correctly configured promotional mail with Promotion cards that are not appearing, the issue may be that the recipient you are sending to has subscribed to a lot of senders using Product carousels, and enough of them have already sent promotional mail that day.
For even more specific examples of troubleshooting, check out this article from Google. There are also details in here for how to avoid account-level limitations that could be preventing your Email Annotations from showing up as expected.
Special caveats for all schema:
- All dates and timestamps (whenever necessary) need to be in ISO 8601 format.
- Depending on the Email Service Provider (ESP) you are using to send your mail, you will need to decide whether to use Microdata or JSON-LD. It is possible the ESP you use will strip your script tags, so microdata might be the way to go.
- All links should be secure (HTTPS).
- Any actions that, when taken, can change the state of data in your system need to be secured. These are also referred to as In-Line Actions.
- The User Agent for Action requests is Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions)
Parts 3 and 4 coming soon!
This guide is divided into multiple articles, so stay tuned for parts three and four in the coming weeks. We'll cover:
✔ Which MBPs support schemas, and to what extent
✔ Common use cases for specific schemas
✔ And include code snippets designed to be copied and pasted into templates
