Create HTML recipient

Use this endpoint when your workflow generates the mail-piece HTML and you want Scribeless to create the recipient, render the documents, and return signed document URLs. It supports postcards, flat cards or notes, and letters.

POST https://platform.scribeless.co/api/recipients/html

This endpoint uses product keys rather than an existing campaign ID. Scribeless resolves the product and rendering resources needed to create the recipient.

Headers

Content-Type: application/json
X-API-Key: YOUR_API_KEY

Request body

Each side accepts an html string and optional styles. Each side's HTML is capped at 250 KB.

Product keys

The HTML endpoint resolves product_key against the Scribeless product catalog. These public product keys are currently supported for HTML rendering:

Folded product keys are not supported by the HTML endpoint yet. If Scribeless enables a team-specific product for you, use the product key provided by Scribeless.

Example request

curl --request POST 'https://platform.scribeless.co/api/recipients/html' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data '{
    "product_key": "a6_postcard",
    "orientation": "landscape",
    "include_envelope": false,
    "data": {
      "first_name": "Ada",
      "last_name": "Lovelace",
      "company": "Example Co",
      "address": {
        "address1": "1 Example Street",
        "city": "London",
        "state": "London",
        "postal_code": "SW1A 1AA",
        "country": "GB"
      },
      "variables": {
        "externalId": "order_12345",
        "offerCode": "SPRING-25"
      }
    },
    "html": {
      "front": {
        "html": "<main style=\"padding:24px;font-size:18px\"><h1>Thanks, Ada</h1><p>Your offer code is SPRING-25.</p></main>",
        "styles": {
          "backgroundColor": "#ffffff"
        }
      },
      "back": {
        "html": "<main style=\"padding:24px;font-size:16px\"><p>Scan to redeem your offer.</p><div data-sqr data-sqr-id=\"spring-offer\" data-sqr-destination=\"https://example.com/offers/SPRING-25\" data-sqr-size=\"24mm\" data-sqr-ecl=\"H\" data-sqr-dots-color=\"#0f766e\" data-sqr-dots-type=\"extra-rounded\" data-sqr-background-color=\"#ffffff\" data-sqr-corner-square-type=\"extra-rounded\" data-sqr-corner-dot-type=\"dot\" style=\"width:24mm;height:24mm\"></div></main>"
      }
    }
  }'

Smart QR placeholders

Use Smart QR placeholders when you want Scribeless to generate a tracked QR code inside your HTML during rendering. Add an empty div with the data-sqr marker and Scribeless will replace the placeholder contents with a QR image while keeping the div in place as the layout anchor.

<div
  data-sqr
  data-sqr-id="spring-offer"
  data-sqr-destination="https://example.com/offers/SPRING-25"
  data-sqr-size="24mm"
  data-sqr-ecl="H"
  data-sqr-dots-color="#0f766e"
  data-sqr-dots-type="extra-rounded"
  data-sqr-background-color="#ffffff"
  data-sqr-corner-square-type="extra-rounded"
  data-sqr-corner-dot-type="dot"
  style="width:24mm;height:24mm"
></div>

The placeholder must be an explicitly closed div; do not use self-closing syntax. It should not contain child elements.

data-sqr-size controls the generated QR image size. CSS width and height are optional layout styles, but they are recommended so your HTML reserves the right amount of space before Scribeless replaces the placeholder with the QR image. If you add padding or borders around the placeholder, account for that in your CSS layout.

You can include SQR placeholders on the front, back, or both sides. Multiple placeholders are allowed on the same side as long as each has a unique data-sqr-id. The same data-sqr-id can be used once on the front and once on the back.

data-sqr-id is a stable identifier for the QR slot in your HTML, not a globally unique analytics ID. Use a descriptive value such as spring-offer, booking-link, or renewal-cta. Reuse the same ID across recipients when it represents the same QR placement, and use a different ID when you have multiple QR placeholders on the same side.

To receive a server-side event when a generated Smart QR code is scanned, create a qr_code.scanned webhook subscription.

Response

Successful requests return the created recipient and signed document URLs. The recipient can remain pending; the generated documents in the response confirm that rendering succeeded.

{
  "recipient": {
    "id": "RECIPIENT_ID",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "status": "pending",
    "variables": {
      "externalId": "order_12345",
      "offerCode": "SPRING-25",
      "html": {
        "front": {
          "html": "<main>...</main>",
          "styles": {}
        },
        "back": {
          "html": "<main>...</main>",
          "styles": {}
        }
      }
    }
  },
  "documents": [
    {
      "id": "DOCUMENT_ID",
      "format": "pdf",
      "type": "postcard",
      "src": "DOCUMENT_STORAGE_PATH",
      "signed_url": "SIGNED_DOCUMENT_URL"
    },
    {
      "id": "PREVIEW_ID",
      "format": "preview",
      "type": "postcard",
      "src": "PREVIEW_STORAGE_PATH",
      "signed_url": "SIGNED_PREVIEW_URL"
    },
    {
      "id": "PREVIEW_ID_2",
      "format": "preview",
      "type": "postcard",
      "src": "PREVIEW_STORAGE_PATH_2",
      "signed_url": "SIGNED_PREVIEW_URL_2"
    }
  ]
}

HTML guidance

• Send complete HTML fragments for the side you want to render. Keep CSS inline or side-level.
• Use HTTPS URLs for externally hosted images and fonts.
• Keep images small enough to render reliably for print.
• Do not rely on client-side JavaScript for printed output.
• Do not use external CSS, scripts, fetch/XHR, iframes, or form actions.
• Inline data:image/* URLs are allowed.
• Send the final text you want printed inside the HTML. Recipient variables are stored with the recipient, but the HTML endpoint should not be treated as a general-purpose HTML templating engine.
• Test with one non-sensitive recipient before sending production traffic.

Errors