Gmail Inbox Actions can improve your transactional emails

If you use Gmail, you may have noticed small buttons on the right side of previews in your inbox. These are called “Actions” or “Inbox Actions,” and they’re based on open standards from schema.org.  Despite being based on open standards, Gmail is currently the only provider with widespread adoption, but given Gmail’s rather large market share, there’s a good chance Inbox Actions could improve the experience for a meaningful portion of your userbase.

What are Inbox Actions? #

We’re going to dive in to see some samples of what can be done with Actions and then take a look at what it takes to add them to your emails. At the highest-level, Inbox Actions add convenient interactions to messages without the user even having to open their email. This makes things like RSVP’s and product reviews very easy. 

By surfacing the common interactions, your recipients can work through their inbox faster and have richer more consistent displays of information within their emails. 

Due to the fact Inbox Actions are ripe for abuse, Gmail currently has some strict controls in place to make sure that actions only show up for good senders. This means that you must authenticate your domain, only use secure URLs for actions, and register to be whitelisted with Google. 

Don’t worry if this all sounds difficult or time-consuming. It’s easier than it might sound, but it’s definitely worth understanding the requirements before you get to work on implementation. So we’ll start there.

Do you meet Gmail’s requirements to offer Inbox Actions on your emails? #

Setting up Inbox Actions is fairly straightforward, but since you have to register with Gmail in order to be whitelisted, it’s important that you make sure you meet the basic requirements before getting too deep into implementation. The requirements are reasonable, but if you don’t meet them yet, you can save yourself a lot of implementation effort. So let’s take a look at the requirements first, and then we’ll talk implementation.

In order to register to be whitelisted and enable Inbox Actions with Gmail, you need to meet their registration guidelines. All of their requirements are really just good practices anyways. One of the best ways to stay out in front of delivery issues or troubleshoot potential problems is to use Gmail Postmaster Tools. Let’s run through the requirements…

• You must be a high volume sender (at least 100 emails per day to Gmail addresses) and have a consistent history of sending that volume for at least a few weeks.
• You must have a low rate of spam complaints. Gmail Postmaster Tools can help you check on this if you’re unsure.
• You may only setup Inbox Actions for transactional emails. Gmail’s guidelines explicitly state that Inbox Actions are only for transactional emails and not bulk marketing emails.
  
• You may only use secure (https) links in your Actions.
• You must authenticate your emails with either DKIM or SPF. Here at Postmark, we highly recommend setting up both SPF and DKIM as well as DMARC anyways.
• You must send from an email address matching the domain name from your authentication. Subdomains are alright as long as the primary domains match. So ‘something.example.com’ would match with ‘example.com’
• You must send the emails from a static address. (i.e. hello@example.com)
• You must already have Inbox Actions implemented prior to your application and be able to send a live test email from the real address directly to Gmail for testing purposes.  
• You must follow the Gmail Bulk Sender Guidelines. If you’re a Postmark customer, many of these guidelines are handled for you automatically.

If you meet all of these requirements, then you’re in the right place. If you don’t meet the requirements, you’ll want to take a step back and make sure you’re able to do all of this prior to going through the process of setting up Inbox Actions.

How to set up Inbox Actions for your transactional emails #

The level of configuration varies for the four Inbox Actions available in Gmail. At the simpler end of the spectrum, One-Click Actions just need a URL, label, and description. But the other actions require multiple endpoints in your application for processing the various requests initiated by the Actions. We’ll get into the specifics of each type of Action later, but let’s start with a quick overview of how Actions work in general.

Writing Actions markup #

Gmail’s documentation covers Inbox Actions in plenty of detail, but there are some points worth highlighting here. There are two options for writing the code that Gmail uses to parse Inbox Actions from your emails. The first is JSON-LD (JavaScript Object Notation for Linked Data), and the second is Microdata which is detailed HTML with a series of specialized attributes. One important caveat to remember is that Google expects all dates and times to be in the ISO 8601 format.

The Microdata version of a Go-To Action would look like this:

<div itemscope itemtype="http://schema.org/EmailMessage">
  <div itemprop="potentialAction" itemscope itemtype="http://schema.org/ViewAction">
    <link itemprop="target" href="https://watch-movies.com/watch?movieId=abc123"/>
    <meta itemprop="name" content="Reset Your Password"/>
  </div>
  <meta itemprop="description" content="Visit our site to reset your password."/>
</div>

If you’re using Postmark Templates, you’ll need to use the Microdata approach since Postmark strips script tags from templates. The JSON-LD version of a Go-To Action would look something like this:

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "EmailMessage",
  "description": "Watch the 'Avengers' movie online",
  "potentialAction": {
    "@type": "ViewAction",
    "target": "https://watch-movies.com/watch?movieId=abc123",
    "name": "Watch movie"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Google Play",
    "url": "https://play.google.com",
    "url/googlePlus": "https://plus.google.com/106886664866983861036"
  }
}
</script>

Since Postmark strips script tags from templates and won’t allow the JSON-LD markup, the rest of our examples will focus on Microdata. That way, the examples will work for both Postmark Templates and any templates within your own codebase. If you need to easily switch your Actions markup between JSON-LD or Microdata, this handy RDF Translator can save you some time.

For things like reservations, events, and order tracking, you could write the JSON-LD or Microdata markup yourself, but you can also use Google’s Structured Data Markup Helper. That way, you can provide your existing markup for your messages, select the type of structured data you want to create, and then the tool will prompt you for the necessary data to create the markup for the relevant structured data. This can be faster and easier as well as help you recognize potential data that could be added to your notifications.

Publisher Data #

In addition to the basic action information, you can also add Publisher information to your markup. This information will be used for the meta data for specific types of interactions and provide additional useful information to recipients.

For instance, in the review menu below, you’ll see “via Wildbit” and “Publish on Wildbit”. This information comes from the Publish Data included in the Inbox Action markup.

Here’s a look at the associated markup:

<div itemprop="publisher" itemscope itemtype="http://schema.org/Organization">
  <meta itemprop="name" content="Wildbit"/>
  <link itemprop="url" href="https://wildbit.com"/>
  <link itemprop="url/googlePlus" href="https://plus.google.com/123456"/>
</div>

Looking at the markup, you can see how Gmail uses the publisher name for the additional information on the Inbox Action. If you have a Google+ profile, you can link to that as well, and Gmail can display additional information.

Testing Actions markup #

Once you’ve written the markup for your actions, you’ll want to test them to ensure that everything’s accurate. Since testing emails can be tedious, Gmail has an Email Markup Tester that will review your action code to verify that it’s written correctly. The nice thing is that it even goes a step further and ensures that all of the required elements for the type of Action you’re using are included.

Once you know your markup is valid, you can test by sending emails to yourself. So as long as the from and to addresses are the same address at gmail.com, you’ll be able to see the actions in your Gmail inbox to test them. You must test from a gmail.com address because domains setup with Google Apps will not display Inbox Actions until the sending address has been whitelisted with Google. One other catch is that Gmail will not display RSVP actions for dates in the past. So if you’re testing RSVP Actions and they’re not showing up, make sure your test dates are in the future. For more details on a quick and easy way to perform these tests, Gmail has a great writeup about using Apps Script to send yourself test emails.

Expiring Actions #

By default, Gmail is smart enough to not present actions on events and travel reservations if the date is in the past, but you may also explicitly add expiration dates to actions. For instance, if you have a time-limited coupon or a given page tied to the action will be out-dated a week after sending, you can set your own start and end times for the action to be valid. Just don’t forget to use the ISO 8601 format for your dates and times.

Securing Action requests #

While some actions are just glorified hyperlinks, others change the state of data in your system. Those that change state are considered “In-Line Actions” and should be secured, and they have more detailed requirements about how they should be handled and processed on your system. We already know that all actions must use secure URLs and must come from SPF or DKIM authenticated domains.  However, Gmail also strongly encourages using server logic to help keep the action endpoints secure. While Gmail offers some basic advice and pointers for implementing these security controls, ultimately, this is code and logic that will need to be written and live within your application.

The first recommendation is that In-Line Actions should use Access Tokens to prevent Replay Attacks. This ensures that In-Line actions can only be interacted with one time and that further attempts to reuse the interaction will fail. The second recommendation is to use Bearer Tokens to verify that requests are coming from Google. Just to be clear, Gmail provides some basic documentation on how to implement these security features, but that code will ultimately live within your application for verifying and handling these requests.

POST /rsvp?eventId=123 HTTP/1.1
Host: events-organizer.com
Authorization: Bearer AbCdEf123456
Content-Type: application/x-www-form-urlencoded
User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions)

rsvpStatus=YES

The third technique is to validate the User Agent to further verify that the request originated from Google. While this technique can help mitigate against accidental usage, User Agents can easily be manipulated, so this shouldn’t be relied on as the only method of verification. 

The User Agent for Action requests is:

Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions)

So what can be done with Inbox Actions? #

Now that you have an understanding of Gmails requirements to enable Inbox Actions for your sending addresses, let’s run through the types of actions and see how powerful they can be. There’s currently four types of Inbox Actions supported in Gmail: One-Click Actions, RSVP Actions, Review Actions, and Go-To Actions. Even if you run an application that doesn’t fit the obvious use cases, chances are good that there are creative and meaningful ways to use Inbox Actions to help your customers.

Go-To Actions #

Go-To Actions are the simplest of all of the available actions, and they’re useful for all sorts of scenarios where you want to make a link available to someone so they can follow a link to something without opening the email. One thing that’s handy to know about Go-To actions is that they’ll also automatically mark the email as read once someone interacts with the action.

Within Go-To Actions, you link to an informational page or you could use anchors to deep link to a form or a specific piece of content on a page.  A great example of this would be password reset emails. With a Go-to action configured, your users don’t even need to open the email. They can just go directly to the reset password form and be on their way. 

From a  technical standpoint, Go-To Actions are the simplest. Since they’re essentially a hyperlink, you only need a URL (the “target”), the text for the button (the “name”), and the alternate text (the “description”). 

Here’s a quick example of a Go-To Action with publisher data included:

<div itemscope itemtype="http://schema.org/EmailMessage">
  <meta itemprop="description" content="Visit our site to reset your password"/>
  <div itemprop="potentialAction" itemscope itemtype="http://schema.org/ViewAction">
    <link itemprop="target" href="https://example.com/password/reset"/>
    <meta itemprop="name" content="Reset Password"/>
  </div>
  <div itemprop="publisher" itemscope itemtype="http://schema.org/Organization">
    <meta itemprop="name" content="Example, Inc."/>
    <link itemprop="url" href="https://example.com"/>
    <link itemprop="url/googlePlus" href="https://plus.google.com/example"/>
  </div>
</div>

One more benefit of Go-To Actions is mobile deep linking. A web URL is required for the Target attribute on Go-To actions, but you may also add links to content in native mobile apps on Android and iOS.  This way, if a recipient opens your email on a mobile device and they have your native app installed, the link will take them to your app instead of the web. If they don’t have your app installed, the action will fall back to the web URL.

Here’s a quick example of including additional target options from Gmail’s documentation:

<link itemprop="target" href="<web url>"/>
<link itemprop="target" href="android-app://<android package name>/<scheme>/<host>/<path+query>"/>
<link itemprop="target" href="ios-app://<App store ID>/<scheme>/<host>/<path+query>"/>

And here it is in the context of the full action:

<div itemscope itemtype="http://schema.org/Event">
  <meta itemprop="name" content="John's Birthday Party"/>
   ... information about the event ...
  <div itemprop="potentialAction" itemscope itemtype="http://schema.org/RsvpAction">
    <meta itemprop="target" content="https://events-organizer.com/rsvp?eventId=123"/>
    <meta itemprop="target" content="android-app://com.eventorg.android/http/events-organizer.com/rsvp?eventId=123"/>
    <meta itemprop="target" content="ios://12345/eventorg/events-organizer.com/rsvp?eventId=123"/>
  </div>
</div>

One-Click Actions #

One-Click Actions make it easy for users to interact with your system without even leaving Gmail. This could mean adding a newly released movie to their queue, checking in to a reservation, confirming a subscription to a newsletter, and much more. 

The only limitations with One-Click Actions are that they can only be interacted with once. So while a Go-To Action is little more than a link that can be visited repeatedly without any state change within your application, One-Click Actions are one-and-done. When you think about what they’re doing, this makes sense. You wouldn’t need to confirm a subscription or check-in more than once.

There are two types of One-Click Actions: a Confirm Action and a Save Action. While fairly similar, the idea is that a confirm would be used to change the state of something and a save action would add an item to list. Because these involve one-time interactions, their design in the inbox is slightly different than Go-To Actions. Once used, these actions will display a checkmark next to the Action label.

Some ideas for One-Click Actions:

• Add to Queue (For songs, movies, or other media.)
• Confirm Subscription
• Approve Request
• Acknowledge Request
• Add to List
• Add to Cart

The biggest structural difference in the code for One-Click Actions is the inclusion of a Handler in place of a Target. This is the URL that will be activated when the user interacts with the Action button.

Here’s an example of the Microdata markup for a One-Click Action:

<div itemscope itemtype="http://schema.org/EmailMessage">
  <div itemprop="potentialAction" itemscope itemtype="http://schema.org/ConfirmAction">
    <meta itemprop="name" content="Approve Expense"/>
    <div itemprop="handler" itemscope itemtype="http://schema.org/HttpActionHandler">
      <link itemprop="url" href="https://myexpenses.com/approve?expenseId=abc123"/>
    </div>
  </div>
  <meta itemprop="description" content="Approval request for John's $10.13 expense for office supplies"/>
</div>

RSVP Actions #

RSVP Actions are where things become a little more complex since they allow the user to have a higher level of interaction within Gmail. The recipient can trigger a menu that offers the options to RSVP inline.

With RSVP actions, you’ll include information about the start and end dates, location, and the options for RSVP. The options are Yes, No, and Maybe, but you’ll need to specify a URL for each response option. Due to the more complex nature of RSVPs, you can also extend them to include information about additional guests.

Here’s an example of the Microdata markup for an RSVP Action:

<div itemscope itemtype="http://schema.org/Event">
  <meta itemprop="name" content="Taco Night"/>
  <meta itemprop="startDate" content="2015-04-18T15:30:00Z"/>
  <meta itemprop="endDate" content="2015-04-18T16:30:00Z"/>
  <div itemprop="location" itemscope itemtype="http://schema.org/Place">
    <div itemprop="address" itemscope itemtype="http://schema.org/PostalAddress">
      <meta itemprop="name" content="Google"/>
      <meta itemprop="streetAddress" content="24 Willie Mays Plaza"/>
      <meta itemprop="addressLocality" content="San Francisco"/>
      <meta itemprop="addressRegion" content="CA"/>
      <meta itemprop="postalCode" content="94107"/>
      <meta itemprop="addressCountry" content="USA"/>
    </div>
  </div>
  <div itemprop="potentialAction" itemscope itemtype="http://schema.org/RsvpAction">
    <div itemprop="handler" itemscope itemtype="http://schema.org/HttpActionHandler">
      <link itemprop="url" href="http://mysite.com/rsvp?eventId=123&value=yes"/>
    </div>
    <link itemprop="attendance" href="http://schema.org/RsvpAttendance/Yes"/>
  </div>
  <div itemprop="potentialAction" itemscope itemtype="http://schema.org/RsvpAction">
    <div itemprop="handler" itemscope itemtype="http://schema.org/HttpActionHandler">
      <link itemprop="url" href="http://mysite.com/rsvp?eventId=123&value=no"/>
    </div>
    <link itemprop="attendance" href="http://schema.org/RsvpAttendance/No"/>
  </div>
  <div itemprop="potentialAction" itemscope itemtype="http://schema.org/RsvpAction">
    <div itemprop="handler" itemscope itemtype="http://schema.org/HttpActionHandler">
      <link itemprop="url" href="http://mysite.com/rsvp?eventId=123&value=maybe"/>
    </div>
    <link itemprop="attendance" href="http://schema.org/RsvpAttendance/Maybe"/>
  </div>
</div>

Review Actions #

The last type of action we’ll cover is Reviews which can be used for things like restaurants, albums, movies, hotel stays, or just about any product or commodity service. The Review Action prompts users for a review from one to five stars and as well as a space for a text review which may be required or optional.

Just like One-Click and RSVP actions, Review Actions involve more code and properties to accommodate the ratings, the item being reviewed, and meta data for the rating and text inputs to be passed to the review handler on your service.

While targeted at consumer goods and services, Review Actions could also be a handy way to increase the convenience of letting your customers provide feedback. You could include the option for a review on every receipt that you send your customers.

Here’s an example of the Microdata markup for a Review Action:

<div itemscope itemtype="http://schema.org/EmailMessage">
  <div itemprop="potentialAction" itemscope itemtype="http://schema.org/ReviewAction">
    <div itemprop="review" itemscope itemtype="http://schema.org/Review">
      <div itemprop="itemReviewed" itemscope itemtype="http://schema.org/FoodEstablishment">
        <meta itemprop="name" content="Joe's Diner"/>
      </div>
      <div itemprop="reviewRating" itemscope itemtype="http://schema.org/Rating">
        <meta itemprop="bestRating" content="5"/>
        <meta itemprop="worstRating" content="1"/>
      </div>
    </div>
    <div itemprop="handler" itemscope itemtype="http://schema.org/HttpActionHandler">
      <link itemprop="url" href="http://reviews.com/review?id=123"/>
      <div itemprop="requiredProperty" itemscope itemtype="http://schema.org/Property">
        <meta itemprop="name" content="review.reviewRating.ratingValue"/>
      </div>
      <div itemprop="optionalProperty" itemscope itemtype="http://schema.org/Property">
        <meta itemprop="name" content="review.reviewBody"/>
      </div>
      <link itemprop="method" href="http://schema.org/HttpRequestMethod/POST"/>
    </div>
  </div>
  <meta itemprop="description" content="We hope you enjoyed your meal at Joe's Diner. Please tell us about it."/>
</div>

What’s next? #

Once you’re ready to go, you can submit your registration form to Gmail. You’ll need to submit it once for each type of email and Action that you plan to offer. This can take a little time, so make sure to plan ahead. We also strongly advise reading through the registration form ahead of time so you know what to expect. That way you can avoid any surprises once you’re ready to submit your application. Then, all you have to do is wait. Once you’ve submitted your application, the process generally takes about one week, but you should definitely plan for longer just to be safe.

While not trivial to implement, adding Gmail’s Inbox Actions to your transactional emails can be a significant improvement to a large portion of your customers. However, before you get too deep into the process, you probably want to determine what proportion of your userbase uses Gmail to make sure enough of your customers would benefit from the feature. And, just as important, you’ll want to double and triple-check Gmail’s requirements for approving a sender to be whitelisted and display Inbox Actions.