Structured Receipts

Send order and shipping confirmations that carry machine-readable schema.org markup — the same data Gmail uses to show rich order cards and package-tracking headers. Pass structured data; Quolle generates the annotated email for you.

Why use it

A normal transactional email is just HTML. A structured receipt embeds a <script type="application/ld+json"> block describing the order or shipment. Mail clients that understand it — Gmail most notably — render a rich card at the top of the inbox. You send the same request either way; Quolle builds both the machine-readable markup and a clean fallback card that renders in every client.

About Gmail rendering. Gmail only shows the rich card for senders it has approved through its Email Markup registration program. The markup Quolle generates is always valid; whether Gmail displays a card depends on Google approving your sending domain. The fallback card always renders, so a structured receipt is never worse than a normal email.

POST /v1/emails/receipt

Same authentication, sending limits, suppression, and idempotency as /v1/emails/send. The body carries a receipt object whose type is "order" or "shipping".

Order confirmation

curl -X POST https://api.quolle.com/v1/emails/receipt \
  -H "Authorization: Bearer qle_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "receipt": {
      "type": "order",
      "orderNumber": "ORD-8821",
      "merchantName": "Acme Stores",
      "customerName": "Ada",
      "items": [
        { "name": "Blue Widget", "quantity": 2, "priceNaira": 5000 },
        { "name": "Gadget",      "quantity": 1, "priceNaira": 2500 }
      ],
      "totalNaira": 12500,
      "orderUrl": "https://acme.com/orders/8821"
    }
  }'

Field	Type	Required	Description
`type`	string	required	`"order"`
`orderNumber`	string	required	Your order reference
`merchantName`	string	required	Store / brand name
`customerName`	string	optional	Greets the recipient by name
`items`	array	required	1–100 items: `name`, optional `quantity`, `priceNaira`, `url`
`totalNaira`	number	required	Order total in Naira
`currency`	string	optional	ISO 4217; defaults to `NGN`
`orderUrl`	string	optional	"View order" link
`orderDate`	string	optional	ISO 8601; defaults to now

Shipping notification

curl -X POST https://api.quolle.com/v1/emails/receipt \
  -H "Authorization: Bearer qle_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "receipt": {
      "type": "shipping",
      "orderNumber": "ORD-8821",
      "merchantName": "Acme Stores",
      "carrier": "GIG Logistics",
      "trackingNumber": "GIG-123456",
      "trackingUrl": "https://track.giglogistics.com/GIG-123456",
      "expectedDelivery": "2026-07-20T00:00:00.000Z",
      "deliveryAddress": "12 Marina, Lagos"
    }
  }'

Field	Type	Required	Description
`type`	string	required	`"shipping"`
`orderNumber`	string	required	Order this shipment belongs to
`merchantName`	string	required	Store / brand name
`carrier`	string	optional	Shipping company
`trackingNumber`	string	optional	Tracking reference
`trackingUrl`	string	optional	"Track package" link
`expectedDelivery`	string	optional	ISO 8601 date
`deliveryAddress`	string	optional	Destination address

Envelope fields

Alongside receipt, the request accepts the usual envelope: from (required, verified domain), to (string or up to 50), optional subject (overrides the auto-generated one), replyTo, scheduledAt, and metadata.

// Response 200
{
  "id": "a1b2c3d4-...",
  "message": "Receipt queued successfully"
}

The subject defaults to "Order #ORD-8821 confirmed" or "Your order #ORD-8821 has shipped". Pass subject to override it.