As described in [Declare actions](https://developers.google.com/workspace/gmail/markup/actions/declaring-actions), when a user interacts with
an in-app action, Google sends an HTTP request to a URL declared in the action.

The following example adds a `ConfirmAction` button to an email about an expense
report:

### JSON-LD

    <script type="application/ld+json">
    {
      "@context": "http://schema.org",
      "@type": "EmailMessage",
      "potentialAction": {
        "@type": "ConfirmAction",
        "name": "Approve Expense",
        "handler": {
          "@type": "HttpActionHandler",
          "url": "https://myexpenses.com/approve?expenseId=abc123"
        }
      },
      "description": "Approval request for John's $10.13 expense for office supplies"
    }
    </script>

### Microdata

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

When the user clicks the button, Google sends an HTTP request to your service,
recording the confirmation. Your service receives the following HTTP request
from Google:

    POST /approve?expenseId=abc123 HTTP/1.1
    Host: your-domain.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)

    confirmed=Approved

The rest of this page describes what the service at
`https://your-domain.com/approve?expenseId=abc123` needs to do to handle the
action properly. This includes:

- Verifying the request
- Processing the payload
- Returning a response code

## Step 1: Verify the request

We recommend that the service at
`https://your-domain.com/approve?expenseId=abc123` verify the following:

- [Limited-use access tokens](https://developers.google.com/workspace/gmail/markup/actions/limited-use-access-tokens): Protect against replay attacks.
- [User agent](https://en.wikipedia.org/wiki/User_agent): Ensure that the request comes from Google.
- [Bearer tokens](https://developers.google.com/workspace/gmail/markup/actions/verifying-bearer-tokens): Ensure that the request from Google is intended for the service.

The User Agent for all action requests is `Mozilla/5.0 (X11; Linux x86_64)
AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions)`.

If all checks pass, the service can proceed to the next step.

## Step 2: Process the action

The service should process the action as specified in the URL parameters as well
as additional information collected from the user.

Additional information from the user resides in the request body and is encoded
using the
[x-www-form-urlencoded](https://en.wikipedia.org/wiki/Percent-encoding#The_application.2Fx-www-form-urlencoded_type)
format. The information is set in properties whose names correspond with the
properties of the action. For example,
[ConfirmAction](https://developers.google.com/workspace/gmail/markup/reference/types/ConfirmAction) has the
property `confirmed`.

## Step 3: Return a response code

After the service processes and records the action successfully, return
response code `200 (OK)`. You can use the following response codes in error
situations:

| Response Code | Treatment |
|---|---|
| 400 (Bad Request) | Google marks the action as failed. |
| 401 (Unauthorized) | Google marks the action as failed. |
| 404 (Not Found) | Google marks the action as failed. |
| 408 (Request Timeout) | Google retries later. |

For permanent failures, Google informs the user that the action failed and that
they should follow alternative instructions inside the email.

## Further reading

- [Secure actions](https://developers.google.com/workspace/gmail/markup/actions/securing-actions)

> [!NOTE]
> **Note:** Some schemas that Google uses are still going through the standardization process of [Schema.org](https://schema.org) and might change in the future. For more information, see [Schema.org proposals](https://developers.google.com/workspace/gmail/markup/reference/schema-org-proposals).