WSS
Web Specification Studio Home
On this page
AutomationOptionalUpdated

Schema.org Email Markup & Gmail Actions

Embed structured Schema.org JSON-LD markup in transactional emails to render interactive One-Click Actions, order summaries, and flight/event cards in Gmail and Apple Mail.

What it is

Schema.org email markup is the practice of embedding structured JSON-LD data inside the <head> of an HTML email to describe entities (Order, FlightReservation, Event, Invoice) and user actions (ViewAction, ConfirmAction, SaveAction).

When supported mailbox providers (such as Gmail, Google Workspace, and Apple Mail) detect valid structured markup, they render interactive summary cards, action buttons in the inbox list view, and direct Google Calendar/Wallet integrations without requiring the user to read the full email body.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Order",
  "merchant": {
    "@type": "Organization",
    "name": "Web Specification Studio"
  },
  "orderNumber": "WSS-98234",
  "priceCurrency": "USD",
  "price": "49.00",
  "orderStatus": "https://schema.org/OrderProcessing",
  "potentialAction": {
    "@type": "ViewAction",
    "name": "View Receipt & Order Status",
    "target": "https://webspecification.com/orders/WSS-98234?token=f81d4fae",
    "url": "https://webspecification.com/orders/WSS-98234?token=f81d4fae"
  }
}
</script>

Why it matters

  • Interactive Inbox Actions: Senders can surface direct “View Order”, “Track Package”, or “Check In” buttons directly in the user’s inbox list view, increasing engagement and reducing support queries.
  • Automated Assistant Integration: Google Assistant, Apple Siri, and Google Calendar parse structured Schema.org data to automatically add flight reminders, reservation alerts, and package tracking updates to the user’s operating system notifications.
  • Progressive Enhancement: Clients that do not support Schema.org email markup simply ignore the <script type="application/ld+json"> tag, rendering the standard HTML body without side effects.

How to implement

1. Meet Google Sender Requirements for Email Markup: Before Google will render interactive actions to end users in Gmail, your sending domain must meet strict criteria:

  1. SPF and DKIM Alignment: Outbound emails must pass SPF and DKIM authentication with a DMARC policy.
  2. Dedicated Sending IP/Domain History: Consistent sending history of at least 100+ transactional messages daily with a near-zero spam complaint rate (<0.10%).
  3. Register with Google: Submit sample emails via the Google Email Markup Registration portal for whitelist approval.

2. Embed Valid Schema.org JSON-LD in the HTML <head>: Use standard Schema.org vocabulary:

  • ViewAction (Deep-link to authenticated web portal):

    {
  "@context": "https://schema.org",
  "@type": "EmailMessage",
  "potentialAction": {
    "@type": "ViewAction",
    "target": "https://example.com/invoices/inv_123",
    "name": "View Invoice"
  },
  "description": "Invoice #inv_123 from Web Specification Studio"
}

  • ParcelDelivery (Shipment Tracking):

    {
  "@context": "https://schema.org",
  "@type": "ParcelDelivery",
  "trackingNumber": "1Z9999999999999999",
  "carrier": "UPS",
  "trackingUrl": "https://www.ups.com/track?tracknum=1Z9999999999999999"
}

3. Ensure Exact Parity Between Markup and Body Content: Every entity, price, order number, and destination URL declared in the JSON-LD markup must match the visible text rendered in the HTML body. Mismatched data will fail Google verification audits.

4. Protect Deep-Link URLs: Never embed unencrypted account credentials in the target URL. Use cryptographically signed, short-lived tokens or link to authenticated dashboard routes.

Common mistakes

  • Using Schema Markup for Promotional Newsletters: Attempting to inject ViewAction buttons on bulk promotional sales. Google strictly restricts Email Markup to purely transactional messages (receipts, bookings, deliveries, authentications).
  • Embedding Markup without DKIM Alignment: Sending JSON-LD from an unaligned third-party domain, which causes Gmail to silently discard the markup.
  • Syntax Errors in JSON-LD: Unescaped quotes or trailing commas in the JSON payload that break the JSON parser.
  • Omitting the Standard HTML Fallback: Relying entirely on structured markup without providing complete, human-readable order details in the HTML table layout.

Verification

1. Validate JSON-LD with Google Email Markup Tester: Paste the generated HTML into the Google Email Markup Validator (developers.google.com/gmail/markup/reference/testing-tools) to confirm zero syntax errors.

2. Send test message to Google Test Account: Send an email from your staging server to a Google-authorized test account ([email protected]) and confirm that the action button and summary card render in Gmail Web and Gmail Mobile.

Related topics

Sources & further reading