Adding actions to Gmail using Schemas

Recently, Google introduced Schemas in Gmail messages to allow developers to deliver a more interactive email experience integrated with their web app. 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, essentialy allowing them to tie their web app with Gmail for a more integrative experience.

A sample Gmail screenshot that displays a ‘Verify email’ button in the subject line is shown below.

gmail-action

By adding schema.org markup to the emails you send your users, you can make that information available across various Google products, and make it easy for users to take immediate action. Schema.org is a markup vocabulary that is standardized and managed as a collaboration of Google and other companies.

Actions in Gmail

Actions enable users to interact with your product or service right inside Gmail. For instance, when a user receives a subscription confirmation request she could directly confirm the request from the email subject line without opening the email.

Gmail uses schema.org markup for user actions and to highlight the most important information users need from an email.

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

One click actions allow users to perform one-click operations directly from withing Gmail without having to visit your website. One Click actions are performed by declaring an HttpActionHandler along with your service URL.

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

A example HTML email along with the schema declaration using the Microdata format is shown below.

<html>
<header>
<span itemscope itemtype="http://schema.org/EmailMessage">  
   <meta itemprop="description" content="Email address verification"/>  
   <span itemprop="action" itemscope itemtype="http://schema.org/ConfirmAction">    
      <meta itemprop="name" content="Verify email"/>    
        <span itemprop="handler" itemscope itemtype="http://schema.org/HttpActionHandler">      
            <link itemprop="url" href="http://www.myurl.com:80/verify.php?id=FDFD5FG"/>    
        </span>  
  </span>
</span>
</header>
<body>
<div>EMAIL CONTENT GOES HERE</div>
</body>
</html>

If you send the above HTML email to the user he will see a ‘Verify email’ button in the subject line, as shown in the screenshot above. When the user clicks on the button, Gmail sends a POST request to the url specified in the action handler. Your application 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).

For quick testing to see if your email button works you could create a test PHP file and send a ‘200 OK’ header. For example in the above HTML we have the file ‘verify.php’ handle the POST requests. We could simply add the following header code to the file to see if your button works.

<?php
 
header('HTTP/1.1 200 OK');
 
?>

Gmail actions can be used for anything that requires a single click – subscription confirmation, email verification, user login etc.

Testing with Google app scripts

You can use Google App Scripts to quickly test your HTML emails. Login to your Gmail account and then go to app scripts and create a blank project. You will be presented with a default ‘Code.gs’ file with the following code.

function myFunction() {
 
}

Replace that with the following.

function testSchemas() {
  var htmlBody = HtmlService.createHtmlOutputFromFile('mail_template').getContent();
 
  MailApp.sendEmail({
    to: Session.getActiveUser().getEmail(),
    subject: 'Testing Gmail action Schemas :',
    htmlBody: htmlBody,
  });
}

Also add a new HTML file from the ‘File’ menu and save it with the name ‘mail_template.html’. Insert the following HTML markup (same as given above).

<html>
<header>
<span itemscope itemtype="http://schema.org/EmailMessage">  
   <meta itemprop="description" content="Email address verification"/>  
   <span itemprop="action" itemscope itemtype="http://schema.org/ConfirmAction">    
      <meta itemprop="name" content="Verify email"/>    
        <span itemprop="handler" itemscope itemtype="http://schema.org/HttpActionHandler">      
            <link itemprop="url" href="http://www.myurl.com:80/verify.php?id=FDFD5FG"/>    
        </span>  
  </span>
</span>
</header>
<body>
<div>EMAIL CONTENT GOES HERE</div>
</body>
</html>

Save the project and then select the ‘Code.gs’ tab. Click on the ‘Run’ icon in the menu which will then execute the code in ‘Code.gs’, essentially sending an email to your account with the HTML content.

Note that to use Gmail action in your emails you will need to first register with Google for your particular domain. Only then will it be possible to send action enabled email to Gmail. More information can be found here.



8 thoughts on “Adding actions to Gmail using Schemas

  1. Hey Sameer,

    thank you very much for this interesting article…

    I want to try your script, but it doesn’t work. Do you know if this feature is just possible in the us now? Because I’m from germany…!?

  2. Hello Chris,
    Try using Google app script to test the above content. I’ve updated the blog post on how you can test the schemas using App Scripts.

  3. Nice little write-up. Thanks. But as an email marketeer, I’d like to test this straight from our broadcasting software to the seed list.
    Sadly your example code above is not showing the action button when test-sent to a gmail account…

    What are we doing wrong?

  4. nice concept. I’ve been trying to test my own schema in gmail for hours. It’s working when sending the email through the google script, but schema is not recognized when sending the mail through postfix and sendmail with gmail SMTP registered. I think it might be a problem of DKIM signing, but google says it’s supposed to work when used from x@gmail.com to x@gmail.com (https://developers.google.com/gmail/actions/testing-your-schema)
    Any suggestion?
    cheers

  5. Hi There,

    We also tried using the method published above but it throws an error : Unable to send rating to gmail.com. Click on the stars again to retry.

    Can you please let us know how to fix this ?

    Also, is there any document to understand the Schema ?

    We did the test through the Google Apps.

Comments are closed.