If you use gmail, you may have noticed little buttons on the right side of the previews in your inbox. they are called “actions” or “inbox actions” and are 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 fairly large market share, there’s a good chance that inbox actions could improve the experience for a significant part of its user base.
what are inbox actions? #
Let’s dive in to see some examples of what you can do with actions and then 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 having to open their email. this makes things like rsvp and product reviews a breeze.
By displaying common interactions, your recipients can work through their inbox faster and have richer, more consistent displays of information within your emails.
Because inbox actions are open to abuse, gmail currently has some strict controls in place to make sure that actions are only displayed for good senders. This means you must authenticate your domain, use only secure URLs for actions, and sign up to be whitelisted by Google.
Don’t worry if this all sounds difficult or time consuming. It’s easier than it sounds, but it’s definitely worth understanding the requirements before you start working on the implementation. so we’ll start there.
do you meet gmail’s requirements to offer inbox actions on your emails? #
Setting up your inbox actions is pretty straightforward, but since you need to sign up for gmail to be whitelisted, it’s important to make sure you meet the basic requirements before you get too deep into implementation. . the requirements are reasonable, but if you don’t already meet them, you can save yourself a lot of implementation effort. so let’s take a look at the requirements first and then we’ll talk about the implementation.
To sign up to be whitelisted and enable inbox actions with gmail, you must comply with their signup guidelines. all your requirements are really good practice anyway. One of the best ways to stay on top of delivery issues or fix potential problems is to use Gmail’s postmaster tools. Let’s review 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.< /li
- should have a low rate of spam complaints. gmail’s postmaster tools can help you check this if you’re unsure.
- you can only configure inbox actions for transactional emails. gmail’s guidelines explicitly state that inbox actions are only for transactional emails and not mass marketing emails.
- You may only use secure links (https) in your actions.
- You must authenticate your emails with dkim or spf. Here at postmark, we we recommend that you configure spf and dkim, as well as dmarc anyway.
- You must send from a email address that matches the domain name of your authentication. subdomains are fine as long as the main domains match. so ‘something.example.com’ would match ‘example.com’
- you need to send the emails from a static address. (ie [email protected] )
- You should already have inbox actions implemented before your request 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 are a postmark customer, many of these guidelines are handled for you automatically.
If you meet all these requirements, then you are in the right place. if you don’t meet the requirements, you’ll want to take a step back and make sure you can do all of this before going through the process of setting up your 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 only need a url, tag, and description. but the other actions require multiple endpoints in your application to process the various requests initiated by the actions. We’ll go into the details of each action type later, but let’s start with a quick overview of how actions work in general.
writing action marks #
The gmail documentation covers inbox actions in great detail, but there are a few points worth noting here. There are two options for writing the code that gmail uses to parse the inbox actions of your emails. the first is json-ld (javascript object notation for linked data) and the second is microdata, which is verbose html with a number of specialized attributes. An important caveat to remember is that Google expects all dates and times to be in ISO 8601 format.
The microdata version of an access action would look like this:
If you’re using postmark templates, you’ll need to use the microdata approach, as postmark removes the script tags from the templates. the json-ld version of a go-to action would look like this:
Because postmark removes script tags from templates and does not allow json-ld markup, the rest of our examples will focus on microdata. that way, the examples will work for both postmark templates and any template within your own code base. If you need to easily switch your action markup between json-ld or microdata, this handy rdf translator can save you some time.
For things like reservations, events, and order tracking, you can write json-ld or microdata markup, 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 quicker and easier, as well as help you recognize potential data that could be added to your notifications.
publisher data number
In addition to the basic action information, you can also add editor information to your markup. this information will be used for metadata for specific types of interactions and will provide additional useful information to recipients.
for example, in the review menu below, you will see “via wildbit” and “post to wildbit”. this information comes from the post data included in the inbox action markup.
here’s a look at the associated markup:
Looking at the markup, you can see how gmail uses the publisher’s name for the additional information about the inbox action. if you have a google+ profile you can also link to it and gmail can display additional information.
testing action markup #
Once you’ve written the markup for your actions, you’ll want to test them to make sure everything is accurate. Since testing emails can be tedious, Gmail has an email markup tester that will check your action code to make sure it’s spelled correctly. the good thing is that it even goes one step further and ensures that all the necessary elements for the type of action you are using are included.
Once you know your markup is valid, you can test it by sending emails to yourself. so as long as the source and destination addresses are the same address on gmail.com, you can see the actions in your gmail inbox to test them. You should test from a gmail.com address because setting up domains with google apps won’t show inbox actions until the sending address has been whitelisted by google. another drawback is that gmail won’t show rsvp actions for past dates. so if you’re testing rsvp actions and they don’t show 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 an excellent article on using app scripts to send test emails to each other.
actions that expire #
By default, gmail is smart enough not to render actions on events and travel bookings if the date is past, but you can also explicitly add expiration dates to actions. For example, if you have a limited-time coupon or a certain page linked to the action will be out of date a week after submission, you can set your own start and end times for the action to be valid. just don’t forget to use iso 8601 format for your dates and times.
protect action requests #
While some actions are just glorified hyperlinks, others change the state of data in your system. those that change state are considered “online actions” and should be protected, and have more detailed requirements on how they should be handled and processed in 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 recommends the use of server logic to help keep action endpoints secure. while gmail offers some basic tips and tricks 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 inline actions should use access tokens to prevent replay attacks. this ensures that inline actions can only be interacted with once and that subsequent 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 basic documentation on how to implement these security features, but that code will ultimately live inside your app to check and handle these requests.
The third technique is to validate the user agent to further verify that the request originated from google. while this technique can help mitigate accidental use, user agents can be easily manipulated, so this should not be relied upon as the only method of verification.
The user agent for action requests is:
so what can you do with inbox actions? #
Now that you understand Gmail’s requirements for enabling inbox actions for your sending addresses, let’s go over the types of actions and see how powerful they can be. Gmail currently supports four types of inbox actions: one-click actions, rsvp actions, review actions, and access actions. Even if you’re running an app that doesn’t fit the obvious use cases, chances are there are creative and meaningful ways you can use inbox actions to help your customers.
go to actions #
Access actions are the simplest of all available actions and are 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 is useful to know about access actions is that they will also automatically mark the email as read once someone interacts with the action.
within access actions, link to an informational page, or you can use anchors to link deep to a form or a specific piece of content on a page. a great example of this would be password reset emails. with a login action configured, your users don’t even need to open the email. they can simply go directly to the password reset form and be on their way.
From a technical point of view, access actions are the simplest. since they are essentially a hyperlink, you only need a url (the “target”), the button text (the “name”), and the alt text (the “description”).
here’s a quick example of an access action with editor data included:
another benefit of login actions is mobile deep linking. A web url is required for the target attribute in access actions, but you can 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 has 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 return to the web url.
here’s a quick example of how to include additional destination options from the gmail documentation:
and here it is in the context of the full action:
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 your queue, signing up for a reservation, confirming a newsletter subscription, and much more.
The only limitations with one-click actions are that they can only be interacted with once. thus, while an access action is little more than a link that can be visited repeatedly without any change of state within your application, one-click actions are one-time. when you think about what they’re doing, this makes sense. you won’t need to confirm a subscription or register more than once.
There are two types of one-click actions: a commit action and a save action. while quite similar, the idea is that a commit would be used to change the state of something and a save action would add an item to the list. Because they involve unique interactions, their layout in the inbox is slightly different from the login actions. once used, these actions will display a check mark 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</li
- add to list
- add to cart
The biggest structural difference in the code for the one-click actions is the inclusion of a controller instead of a target. this is the url that will fire when the user interacts with the action button.
here is an example of the microdata markup for a click action:
rsvp actions #
rsvp actions are where things get a bit more complex, as they allow the user to have a higher level of interaction within gmail. the recipient can activate a menu that offers the options to RSVP online.
with rsvp actions, you will include information about start and end dates, location, and rsvp options. the options are yes, no, and maybe, but you’ll need to specify a url for each answer option. due to the more complex nature of rsvp, you can also expand them to include additional guest information.
here is an example of the microdata markup for an rsvp action:
review actions #
The last type of action we’ll cover is reviews that can be used for things like restaurants, albums, movies, hotel stays, or just about any basic product or service. the review action prompts users for a one to five star review and also a space for a review text that can be required or optional.
Like the one-click and RSVP actions, the review actions involve more code and properties to accommodate the grades, the item being reviewed, and the metadata for the grade and text inputs being reviewed. passed to the revision handler in your service.
While targeted at consumer goods and services, review actions can also be a handy way to increase the convenience of allowing your customers to provide feedback. you could include the review option on every receipt you send to your customers.
here is an example of the microdata markup for a review action:
what’s next? #
once you’re ready to get started, you can submit your registration form to gmail. you’ll need to send it once for each type of email and action you plan to offer. this can take a bit of time, so be sure to plan ahead. We also strongly recommend that you read the registration form ahead of time so you know what to expect. that way you can avoid 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 usually takes about a week, but you should definitely plan on more time just to be safe.
While not trivial to implement, adding gmail inbox actions to your transactional emails can be a significant improvement for a large portion of your customers. however, before delving too deeply into the process, you’ll probably want to determine what proportion of your user base uses gmail to ensure that enough customers benefit from the feature. And just as importantly, you’ll want to double- and triple-check Gmail’s requirements to approve a sender to be whitelisted and show inbox actions.