Declare Actions

An Action in schema.org represents a verb or activity that can be performed on a piece of structured data. Multiple types of actions are supported and they can all be defined with similar structured data.

Go-To Actions

Go-To actions are easy to declare. Once you have markup your content with schema.org entities, you may add go-to actions for them. For instance, to make an Event entity have a RsvpAction Go-To link, you just need to populate the event's potentialAction property, as in the following example:

JSON-LD

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Event",
  "name": "John's Birthday Party",
  ... information about the event ...
  "potentialAction": {
    "@type": "RsvpAction",
    "target": "http://events-organizer.com/rsvp?eventId=123",
  }
}
</script>

Microdata

<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"/>
  </div>
</div>

The action's target property determines the Go-To url that Gmail will send the user to.

Example of what the user will see in Gmail:

A GoTo link in Gmail

Note that the markup above is automatically ignored by other email clients that do not support Schemas in Emails.

Mobile Deep Linking

Go-To actions can also link directly to content in native mobile apps on Android and iOS. To deep link to an app, include additional target URLs encoded with the android-app:// and ios-app:// schemes as shown below:

JSON-LD

target: [ 
  “<web url>”,  
  “android-app://<android package name>/<scheme>/<host>/<path+query>”, 
  “ios-app://<App store ID>/<scheme>/<host><path+query>" 
]

Microdata

<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>"/>

Extending the previous Event example:

JSON-LD

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Event",
  "name": "John's Birthday Party",
  ... information about the event ...
  "potentialAction": {
    "@type": "RsvpAction",
    "target": [
      "http://events-organizer.com/rsvp?eventId=123",
      "android-app://com.eventsorganizer.app/http/events-organizer.com/rsvp?eventId=123",
      "ios-app://12345/eventorg/events-organizer.com/rsvp?eventId=123"
    ]
  }
}
</script>

Microdata

<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>

If the user does not have your app, or is using Inbox on the web, the action will take the user to the web URL you provide.

In-App Actions

In-App Actions are handled in-place, inside Gmail, without sending the user to any other website. In-App Actions are declared like Go-To Actions, but contain extra information that makes it easy for user-agents (such as Gmail) to handle the action inline.

Instead of declaring an action with a target, one has to declare an HttpActionHandler for the action with the proper configuration:

JSON-LD

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Event",
  "name": "John's Birthday Party",
  ... information about the event ...
  "potentialAction": {
    "@type": "RsvpAction",
    "actionHandler": {
      "@type": "HttpActionHandler",
      "url": "https://events-organizer.com/rsvp?eventId=123",
      "method": "POST",
      "requiredProperty": "rsvpStatus",
    }
  }
}
</script>

Microdata

<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">
    <div itemprop="actionHandler" itemscope itemtype="http://schema.org/HttpActionHandler">
      <meta itemprop="url" content="https://events-organizer.com/rsvp?eventId=123"/>
      <link itemprop="method" href="http://schema.org/HttpRequestMethod/POST"/>
      <div itemprop="requiredProperty" itemscope itemtype="http://schema.org/Property">
        <meta itemprop="name" content="rsvpStatus"/>
      </div>
    </div>
  </div>
</div>

Upon encountering such markup, Gmail will present a dialog to the user similar to the following:

RSVP in Gmail

Once the user clicks on any of the yes/no/maybe options, Gmail will perform communicate the RsvpAction information back to events-organizer.com, by issuing an HTTPS POST request to the destination declared in the HttpActionHandler's url.

The HTTP request will look like this:

POST /rsvp?eventId=123 HTTP/1.1
Host: events-organizer.com
Authorization: Bearer AbCdEf123456
Content-Type: application/x-www-form-urlencoded

rsvpStatus=YES

The request's body contains the user's answer in a url-encoded string. The service processing this request should return an HTTP code 200 (OK) to indicate that it received the request, or an error code otherwise.

Expiring Actions

In many cases actions are only relevant for a limited period of time. Actions associated to entities with known dates such as events and travel reservations will automatically expire. Gmail and Inbox will not display the action after the event or trip has passed.

Expirations can be explicitly added to actions as as well. An action to clip a coupon or save an offer code may only be valid for a limited time. To set the time window for when an action is displayed, set the startTime and endTime properties of the action:

JSON-LD

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "EmailMessage",
  "potentialAction": {
    "@type": "ConfirmAction",
    "name": "Save coupon",
    "handler":  {
       "@type": "HttpActionHandler",
       "url": "https://my-coupons.com/approve?couponId=abc123"
    },
    "startTime": "2015-06-01T12:00:00Z",
    "endTime": "2015-06-05T12:00:00Z"
  }
}
</script>

Microdata

<div itemscope itemtype="http://schema.org/EmailMessage">
  <div itemprop="potentialAction" itemscope itemtype="http://schema.org/ConfirmAction">
    <meta itemprop="name" content="Save coupon"/>
    <div itemprop="handler" itemscope itemtype="http://schema.org/HttpActionHandler">
      <link itemprop="url" href="https://my-coupons.com/approve?couponId=abc123"/>
    </div>
    <meta itemprop="startTime" content="2015-06-01T12:00:00Z" />
    <meta itemprop="endTime" content="2015-06-05T12:00:00Z" />
  </div>
</div>

Further Reading

For more details about Actions, see:

Send feedback about...

Email Markup
Email Markup