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

Rendering completes before this endpoint responds, so requests can take time. For asynchronous uploads of 1–500 recipients, use Create bulk HTML recipients.

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

Billing and status

HTML recipients are billed differently depending on the account setup.

For non-subscription accounts, Scribeless creates or reuses a hidden one-time HTML campaign for the selected product and automatically adds it to the active cart. Use GET /api/carts/active, then POST /api/recipients/checkout with cartId.

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 256,000 characters. Inline base64 image data counts towards this limit; this is not a total request-body byte limit.

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 generated documents in the response confirm that rendering succeeded.

Subscription-backed accounts return a ready recipient:

{
  "recipient": {
    "id": "RECIPIENT_ID",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "status": "ready",
    "variables": {
      "externalId": "order_12345",
      "offerCode": "SPRING-25",
      "html": {
        "front": {
          "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"
    }
  ]
}

Non-subscription accounts return a rendered but unpaid pending recipient:

{
  "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"
    }
  ]
}

Use the returned documents to preview the rendered mail piece. For pending recipients, complete recipient checkout before expecting fulfilment to start.

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.

Artwork size and bleed

For an edge-to-edge design, use html.front.styles.backgroundImage or backgroundColor. Use html.back.styles for the back. Keep the HTML layout at the finished product size; images placed inside the HTML body are limited to that size.

Background images

Prepare your image with 1.5 mm of extra artwork on each edge: add 3 mm to both the finished width and height. This extra artwork is the bleed.

Set these properties on the side's styles:

• backgroundImage: your image URL, using url('https://…').
• backgroundSize: the image's width and height including bleed, in mm.
• backgroundPosition: center.
• backgroundRepeat: no-repeat.
• backgroundColor: #ffffff.

For a landscape 4x6 postcard, the finished size is 152.4 × 101.6 mm (6 × 4 in). Prepare an image at 155.4 × 104.6 mm, or at least 1836 × 1236 pixels at 300 ppi. Centering handles the 1.5 mm extension on each edge; no negative offset is needed.

Include this fragment in your request with the recipient data:

{
  "product_key": "4x6_postcard",
  "orientation": "landscape",
  "html": {
    "front": {
      "html": "",
      "styles": {
        "backgroundImage": "url('https://example.com/front.png')",
        "backgroundSize": "155.4mm 104.6mm",
        "backgroundPosition": "center",
        "backgroundRepeat": "no-repeat",
        "backgroundColor": "#ffffff"
      }
    }
  }
}

An empty html string creates an image-only side. Add any text or other content to that string. Keep the single quotes around the image URL as shown, and follow the HTML image guidance.

Background colors

For a solid color that reaches every edge, set the side's backgroundColor. No image or bleed dimensions are needed:

{
  "html": {
    "front": {
      "html": "",
      "styles": {
        "backgroundColor": "#0f766e"
      }
    }
  }
}

Image dimensions at 300 ppi

Use the following dimensions for flat formats. Width is the shorter edge; swap width and height for landscape. The image dimensions include 1.5 mm of bleed on each edge.

Use the image size in millimeters for backgroundSize. To calculate raster dimensions for another size, multiply each image dimension in millimeters by 300 / 25.4 and round up to a whole pixel. Set the physical size in CSS even if your image has DPI metadata.

Choose a supported product key or a key supplied by Scribeless for your account. This sizing table excludes folded formats and envelopes.

Keep text, logos, QR codes, and other important details inside the finished edges, with space around them. Bleed is for the background artwork. Review the returned preview before using your design.

Errors