Introducing Actions in the Inbox, powered by schemas

Wednesday, May 15, 2013 | 2:32 PM


Search engines have been using structured data for years to understand the information on web pages and provide richer search results. Today, we are introducing schemas in emails to make messages more interactive and allow developers to deliver a slice of their apps to users’ inboxes.

Schemas in emails can be used to represent various types of entities and actions. Email clients that understand schemas, such as Gmail, can render entities and actions defined in the messages with a consistent user interface. In the case of Gmail, this means that the emails can display quick action buttons that let users take actions directly from their inboxes, as in the following screenshot:

Using schemas to add quick action buttons to the emails you send is easy. All it takes is adding some markup to your HTML emails, together with your regular content, in one of the supported formats - Microdata and JSON-LD.

As an example, the following JSON-LD markup can be used to define a movie and the corresponding one-click action to add the movie to your queue:

<script type="application/ld+json">
  "@context": "",
  "@type": "Movie",
  "name": "The Internship",
  ... information about the movie ...
  "action": {
    "@type": "ConfirmAction",
    "name": "Add to queue",
    "actionHandler": {
      "@type": "HttpActionHandler",
      "url": "",
      "method": "POST",

Gmail renders the markup above with a button labelled “Add to queue” next to the email subject line. When the user clicks on the button, Gmail sends a POST request to the url specified in the action handler. Your app has to handle these requests and respond to the email client with an appropriate HTTP response code (200 for successful requests, 400 for invalid requests, etc.).

Schemas in emails currently support four different types of actions - rate/review, RSVP, one-click action and goto link - and we plan to add more types moving forward. We are collaborating with a number of partners who will launch their integrations in the coming weeks, making the messages they send more useful and interactive for Gmail users. For example, Esna is using this to inform users of missed calls and provide them with a one-click button to be called again, while Seamless is implementing the rate/review action to collect feedback about restaurants.

Other partners who are already implementing schemas in email today include both Billguard, Concur Technologies, Docusign, HelloSign,, Mailchimp, myERP, Netflix, OpenTable, Orangescape, Paperless Post, Spotify, SugarCRM, and Tripit.

To learn more about all supported entities and actions and to find out how to get started with schemas in email, visit

Claudio Cherubino   profile | twitter | blog

Claudio is an engineer in the Google Drive Developer Relations team. Prior to Google, he worked as software developer, technology evangelist, community manager, consultant, technical translator and has contributed to many open-source projects. His current interests include Google APIs, new technologies and coffee.


Nick Kusters said...

The validator says the types shouldn't have the propery action and when I e-mail it to myself in the head section of a html email, it doesn't work either...

Liam Proven said...

The plural of "schema" is "schemata".

Claudio Cherubino said...

@Nick: the validator is still in alpha and not all the new things we introduced are already supported. Please bear with us a little more while we add them.

How are you sending those emails? Emails have to be signed (DKIM or SPF) so that Gmail is sure you are the real sender. If you are using Gmail SMTP, Apps Script or App Engine, they will take care of that for you.

Ach said...

It would be nice and more effective to allow more than one action.

Aaron Severs said...

This is awesome... however, I tried the exact sample code for ReviewAction here:

and sent it through Gmail SMTP with myself as the from address, but still was not able to get it to work. There is a notice on that page that this is an API preview. Has it not been rolled out yet for testing? Thanks!

Claudio Cherubino said...

We are rolling out the new features starting from now and over the next few weeks. Some actions (for instance ReviewAction) are not publicly available yet.

Yang Lau said...

How do gmail handle ajax cross domain issue with this POST?

Claudio Cherubino said...

Requests are not client-side calls, instead Gmail sends server-to-server RPC requests to the third-parties, so there's not cross domain issue

erjjones said...

Does the script tags have to go in the header or can we put them in the body?

Claudio Cherubino said...

Anywhere in the body will also work

yp said...

This is very cool. Can Gmail support feedback within the email after the actions are executed? e.g. Show "Thanks for rating!", "Sorry, please try again." depending on whether the action was successful.

Alexander Y. said...

Do you support contexts other than

E.g. my app needs actions that are not available from What do I do?

Alexander Y. said...


What is a good place to post questions on Schemas in Gmail?

I could not find directions from the Overview page ( Please instruct.

Claudio Cherubino said...

@yp: we currently only use the HTTP response code and show the corresponding generic message, but we are also considering your feature request. As usual, it is really important to us to provide the best user experience and showing whatever message comes from a third-party might not always the best approach.

@Alexander: we plan to add more actions but they will eventually have to be part of Happy to hear about the use cases you have in mind.

Talking about that, the best place to ask technical questions about this technology is Stack Overflow:

Alexander Y. said...

@Claudio: Examples of actions we need:
- Send only text (without rating as in Review Action) back to the app. Have custom app-specific title for the action.
- TwoClick Action :) - display drop-down allowing to select an item and send the selection back to the server. E.g. "Assign to: John Doe, Jane Smith, Mary Jane"

Claudio Cherubino said...

You can configure the fields you need in a Review Action and make the text comment required and exclude the rating. The action title is not configurable for Review Actions in order to provide a consistent UX.

We are definitely considering more complex actions such as the two-click action you describe or a multiple answers question. It is too early to make any promises but we hear you.
Thanks so much for your feedback!

syawalisme said...


Cyril said...

@Claudio Cherubino: The documentation about GMail ( also mention "Reservations" but I can't make it work. It looks like only the "Actions" are currently working. Can you please confirm these features are enabled and can be tested exactly as "Actions" are? Thank you very much.

Claudio Cherubino said...

The only structured data type that currently has support in Gmail with a specific card is Flight. Other types (and actions) will be added in the future and Reservation is part of our plans.

Cyril said...

@Claudio Cherubino: Thank you for the blazingly fast response. I also tried "Flight" by simply "copying/pasting" the example in the documentation but can't make it work. I'm sure the email is signed and sent to myself as "Actions" are correctly working. Does the flight need to be an existing flight?

Claudio Cherubino said...

We perform some checks on the flight data, but even with real data I can't get the flight card to show up with the sample markup in the docs. I'll investigate the issue and let you know.

swifty said...

Thanks for your quick answers claudio, an additionnal one: will te rollout of this feature available in all gmail distribution (for example the french one)

And even a dummier question: can I keep and feed gmail with marked email from the web or apps interface (just by pasting in the message instead of using SMTP or IMAP)

Claudio Cherubino said...

The new features are being rolled out to all Gmail and Google Apps users.

You can't use the Gmail interface to send emails with markup. Probably, the easiest way to do so is to use Apps Script, I'm writing a small guide showing how to do that and I hope to publish it soon.

Cyril said...

I've tested the FlightReservation and Go-To schema again and it looks like they are not working yet. Any plan on activating these features?

Claudio Cherubino said...

Both FlightReservation and Go-To actions have rolled out completely. How are you testing them? The easiest way to get a Go-To action working is by following our Apps Script tutorial:

Alexander Y. said...

@Claudio, the example here gives @context without protocol, while the AppScript sample referenced in your comment does this:

"@context": ""

Which one is correct? Both?

Claudio Cherubino said...

The correct one is "", but we currently support both. Please use the one with protocol when possible

Isaac said...


Is there a way to test the hotel reservation schema.


Claudio Cherubino said...

You can test hotel reservations by sending emails with markup to yourself and then searching for them on Google Search. There's no Gmail-specific card for the moment.