Main Page

Display of Orders in Seznam Email

The Orders tab in Seznam.cz email inboxes contains a list of orders and their statuses extracted from structured data in incoming transactional emails. For each order, all related email messages are also available in the list. Processing structured data does not affect email delivery or folder placement.

Email Processing

When an email is received, the mail server scans the HTML MIME part for structured order data according to the evolving structured email standard, using the schema.org vocabulary. The expected structure and placement of this order data are described below. If a valid order description is found, the server either creates a new order record or updates an existing one based on matching key parameters.

Embedding Data in Emails

Machine-readable order data in emails is based on an existing specification used by major global email providers. Each structured email must contain exactly one order, provided in one of the following supported formats:

JSON-LD example:

Subject: Order confirmation #1234
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: 8bit 

<!DOCTYPE html>
<html>
  <head>
    <title>Order confirmation #1234</title>
  </head>
  <body>
    <h1>Order confirmation #1234</h1>
    <p>Your order has been received and is currently being processed.</p>
    <script type="application/ld+json">
      <!-- JSON-LD data -->
    </script>
  </body>
</html>

Microdata example:

Subject: Order confirmation #1234
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: 8bit

<!DOCTYPE html>
<html>
  <head>
    <title>Order confirmation #1234</title>
  </head>
  <body>
    <h1>Order confirmation #1234</h1>
    <p>Your order has been received and is currently being processed.</p>
    <div itemscope itemtype="https://schema.org/Order">
      <!-- Additional Microdata -->
    </div>
  </body>
</html>

When using JSON-LD, only a single top-level object is allowed. Incorrectly placed or invalid structured data is ignored. Email delivery is not affected.

Data Structure

Order data is based on the schema.org Order type with the following expected properties:

All URLs must use https://. Any unsupported or unknown fields are ignored.

(*) In the acceptedOffer property, you can provide either the total price (preferred) or prices of individual order items as multiple price entries. In the latter case, the values are summed and the resulting total amount is displayed. Multiple units can be specified using the eligibleQuantity parameter. If this parameter is present, the value of the price parameter is treated as a unit price and multiplied by the specified quantity. The price parameter is also accepted at the top level. A price provided at this level is always considered the total price. If it is present, this price is displayed and any items defined within the acceptedOffer structure are ignored.

The order data structure must correctly specify its type using rdf:type with a value representing https://schema.org/Order. This specific type is used to identify a valid order data structure.

In JSON-LD, it is expressed as follows:

{
  "@context": "https://schema.org",
  "@type": "Order",

  // additional data
}

In Microdata, it is expressed as follows:

<div itemscope itemtype="https://schema.org/Order">
  <!-- additional data -->
</div>

If this specific type appears more than once in an email, an incorrect data structure may be selected and processed.

If any required fields are missing, or if the order data structure does not specify the correct type, the order data will not be processed or stored. This does not affect email delivery.

Order Creation and Status Updates

To create a new order record, all listed fields are required except those within the orderDelivery structure. A successfully created record is displayed in the email inbox interface.

The order status is updated when a new email is received that contains structured order data with a new status and/or additional delivery information. To successfully update an order, each subsequent email must include seller.name, orderNumber, and url with values matching those in the previous message. Otherwise, the email cannot be processed as an update to an existing order.

All other fields will be added or updated based on the data in the new message. For fields that are not present in a subsequent message, the values stored from previous messages will be used when displaying the order. For smooth processing, we nevertheless recommend providing as much known information as possible in each message. To remove a previously stored value, the relevant parameter must be included with an empty string as its value.

If order delivery is handled by a shipping carrier, successful processing of delivery updates requires that emails from the carrier include the corresponding merchant name in the seller.name parameter and at least one of the parameters orderNumber or url with values matching those in the previous message from the seller.

Data Examples

Basic JSON-LD example for an order:

{
  "@context": "https://schema.org",
  "@type": "Order",

  "orderDate": "2024-01-01T00:00:00+01:00",
  "orderNumber": "1234",
  "orderStatus": "https://schema.org/OrderProcessing",
  "url": "https://example.com/orders/1234",

  "seller": {
    "@type": "Organization",
    "name": "Example.com",
    "url": "https://example.com",
    "logo": "https://example.com/logo.png"
  },

  "acceptedOffer": {
    "@type": "Offer",
    "price": "100.00",
    "priceCurrency": "CZK"
  }
}

If the delivery method and carrier are already known at the time the order is created, they can be included in the data:

{
  "@context": "https://schema.org",
  "@type": "Order",

  // same as above

  "orderDelivery": {
    "@type": "ParcelDelivery",
    "trackingNumber": "4321",
    "trackingUrl": "https://example.com/tracking/4321",
    "expectedArrivalFrom": "2024-01-01T00:00:00+01:00",
    "expectedArrivalUntil": "2024-01-02T00:00:00+01:00",
    "hasDeliveryMethod": "https://schema.org/ParcelService",
    "provider": {
      "@type": "Organization",
      "name": "Ponny Express",
      "url": "https://ponnyexpress.com",
      "logo": "https://ponnyexpress.com/logo.png"
    }
  }
}

A validator for verifying the correctness of the data structures is available at https://fbl.seznam.cz/orders

Order Status Changes

The goal of this functionality is to provide users with an overview of their orders and the current stage of their fulfillment. Therefore, the key information in each update email should be the actual processing status of the order. The current status will be displayed in the order overview within the inbox interface, and users will be able to sort or filter orders based on it.

The order processing status is specified in the orderStatus data field. The following order processing statuses are distinguished according to the list of supported values.

Example of a status change in JSON-LD:

{
  "@context": "https://schema.org",
  "@type": "Order",

  // same as above

  "orderStatus": "https://schema.org/OrderInTransit"
}

Additional Information

If you have any questions about the structured data and how your store can benefit from the Orders feature, please contact dotazy@schema.seznam.cz.

All user data is processed and stored in accordance with the Email.cz service terms and conditions.