Gmail Schemas: How To Mark Up Your Emails

As we have mentioned previously, Schemas in Gmail let you mark up information. This lets ‘Google understand the fields and provide the user with relevant actions, and cards’.

Right now these quick-action buttons only render in Gmail, but since this project is schema-based, we’re betting it won’t be too long before other email clients adopt the same technology.

What’s more, there’s no need to worry if you send an email with schema markup to a non supported email client, the client will simply ignore the markup, and there will be no negative rendering effects.

How Are Google Cards Created?

Google cards are created by adding markup to the emails you send your users.

What Is Schema.Org? is a ‘markup vocabulary that is standardized and managed as a collaboration of Google and other companies’. say that ‘most webmasters are familiar with HTML tags on their pages. Usually, HTML tags tell the browser how to display the information included in the tag. For example, <h1>Avatar</h1> tells the browser to display the text string “Avatar” in a heading 1 format. However, the HTML tag doesn’t give any information about what that text string means—”Avatar” could refer to the hugely successful 3D movie, or it could refer to a type of profile picture—and this can make it more difficult for search engines to intelligently display relevant content to a user’.

Instead, provides a ‘collection of shared vocabularies webmasters can use to mark up their pages in ways that can be understood by the major search engines: Google, Microsoft, Yandex and Yahoo!’

Schemas in Gmail support both JSON-LD and Microdata, this lets Google ‘understand the fields and provide the user with relevant search results, actions, and cards. For example, if the email you’re sending is about an event reservation, you might want to mark the start time, venue, number of tickets, and all other information that defines the reservation’.

Click here to see an example from Google as to what the marked-up email looks like in both JSON-LD and Microdata.

Marking Up Your Emails:

In today’s post we’re going to talk you through the information that you’ll need to input in order to mark up your emails for Google action cards.

OK, so imagine that you’re sending out tickets to your customers about a Christmas event that you’re running and you want to use  semantic information in these emails.  Google say that ‘your ticket confirmation email should (at the very least) contain HTML like the following:

      Dear John, thanks for booking your Google I/O ticket with us.
      Order for: John Smith<br/>
      Event: Google I/O 2013<br/>
      When: May 15th 2013 8:30am PST<br/>
      Venue: Moscone Center, 800 Howard St., San Francisco, CA 94103<br/>
      Reservation number: IO12345<br/>

Google say that ‘marking up this email is very easy’, adding that ‘relevant pieces of information in the email body can be added anywhere inside the body of the email’s HTML in a structured form corresponding to one of the supported formats’.

This is what the marked-up email looks like in JSON-LD, which is an alternative to the HTML oriented Microdata Schemas. To see what it might look like in microdata or microdata (inline), click here.

    <script type="application/ld+json">
      "@context":              "",
      "@type":                 "EventReservation",
      "reservationNumber":     "IO12345",
      "underName": {
        "@type":               "Person",
        "name":                "John Smith"
      "reservationFor": {
        "@type":               "Event",
        "name":                "Google I/O 2013",
        "startDate":           "2013-05-15T08:30:00-08:00",
        "location": {
          "@type":             "Place",
          "name":              "Moscone Center",
          "address": {
            "@type":           "PostalAddress",
            "streetAddress":   "800 Howard St.",
            "addressLocality": "San Francisco",
            "addressRegion":   "CA",
            "postalCode":      "94103",
            "addressCountry":  "US"
      Dear John, thanks for booking your Google I/O ticket with us.
      Reservation number: IO12345<br/>
      Order for: John Smith<br/>
      Event: Google I/O 2013<br/>
      Start time: May 15th 2013 8:00am PST<br/>
      Venue: Moscone Center, 800 Howard St., San Francisco, CA 94103<br/>

Google say that the above example contains only the minimal set of information to define an event reservation. Marketers can markup additional information to further ‘improve the user experience’.

Word Of Warning:

The Google bods say that ‘some of the schemas used by Gmail are still going through the standardization process of, and therefore, may change in the future’ – we (dotdigital) will of course update you if and when and it does.

Right, let’s get started:

Gmail currently supports 4 types of actions and 1 interactive card:

  • RSVP Action for events
  • Review Action for restaurants, movies, products and services
  • One-click Action for just about anything that can be performed with a single click
  • Go-to Action for more complex interactions
  • Flight interactive cards

The RSVP Action:

If you choose to implement this action then Gmail will show your recipient an event card next to the email, ‘including buttons for RSVP-ing attendance in the event’.

There are some basic required properties that you’ll have to include within your markup, but there are also a few additional properties that you might choose to add if suitable for the event in question:

Required Properties:

  • The name of the event
  • The start date & time of the event, which should be included in this format: ‘2013-02-14T13:15:03-08:00’ (YYYY-MM-DDTHH:mm:ssZ)
  • An action
  • An action Handler & URL supported by the RSVP action, more details about this can be found here.

Marketers also have the option to include:

  • An end time of the event
  • A location and/or address
  • The postcode

The full list of optional properties can be found here.

The Review Action:

The review action will ‘prompt the user for a numeric review value and / or a user comment’ when asking a user to review or rate a product or service.

Unlike the RSVP action, there are no optional properties that can be included within the markup. In this instance, the markup must include;

  • The name of the ‘thing’ being reviewed
  • The lowest possible rating
  • The highest possible rating
  • The handler and the handler URL that is supported by this action.

More details can be found here.

One Click Actions:

This is my favorite action by far because it can be used for ‘just about anything that requires a single click’. One Click actions are performed by ‘declaring an HttpActionHandler with your service URL’.

The One Click actions currently supported in Gmail are the:

  • ConfirmAction

and the:

  • SaveAction

Let’s take a look at an example of a ConfirmAction…

Google say that senders can add a one click button to an email when they require a user to ‘approve, confirm and/or acknowledge something’.

When a recipient clicks on the button, an http request ‘will be issued from Google to your service, recording the confirmation’. It is important to note that ‘ConfirmAction can only be interacted with once’.

When implementing either the ConfirmAction or the SaveAction, senders must ensure that ALL of the ‘property paths’ listed at the bottom of this page are included within the email. If you miss one out then your markup will not be recognized as valid and will not display properly (or at all) to recipients.

Go To Actions:

Go to actions are designed to be used for more complex interactions. This action currently only supports a ViewAction although Google have said that more actions MIGHT be supported in the future. ViewAction buttons are designed for senders that require their recipients to visit their webpage to complete the desired action.

In order for your markup to be recognized as valid markup by Google you will need to include:

  • A snippet of text describing the contents of the email
  • A URL to navigate to when a user executes the action
  • A user visible name that is shown in the user interface associated with the action

Flight Reservation Schemas:

For flight notifications, Gmail has a slightly different card to the ones mentioned above. This card will be displayed above the message and it can include real-time information about the flight as well as a “check-in” button.

This card has several uses. Senders can use it to send basic flight confirmation emails, add a check-in button, to describe flights with multiple segments and/or with multiple passengers.

There is a lengthy list of property specifications here, Google suggest that senders review the details of their email to see whether any of the listed properties apply to their send because the more relevant properties that are marked up, the richer description of the flight reservation Google will deliver to the user.

Phew, and we’re done…almost!

Before you hit send, make sure that you test your schemas. You can either test them yourself by sending emails with schemas to your Gmail account from your Gmail account; emails where the sender and the recipient are the same account flout the registration requirements so that they can be used for self-testing.

Alternatively, you can use Google’s nifty little ‘Schema Validator’ tool that lets you simply copy your markup and paste it in the text box here to test it.

If you have any questions that you are struggling to find answers to then please get in touch; either tweet us or leave a comment in the box below, we’ll always respond.

The Holiday Hub: deliver emails with impact this holiday season

Like the 2020 holiday season, 2021 will present some unknowns that marketers will need to adapt to, but there are plenty of things we do know that can help us prepare for the upcoming busy period that…

A successful return to live UK events

In March 2020, we – like many other businesses – made the transition from live to virtual events. Committed to providing valuable educational content to our clients, we adapted. We never stopped engaging with you, starting interesting…

Behavioral campaign ideas you can use

We’re coming to the end of our deep dive on using neuroscience and the purchase formula in your campaigns. We’ve discussed why the purchase formula is so important, and why increasing reward activation in the brain is…