Create bulk HTML recipients

Create 1-500 postcards, notes, or letters with individual front/back HTML. Rendering runs in the background.

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

Scribeless creates or reuses the campaign automatically. You do not need to supply a campaign or template ID.

Headers

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

Request body

Each HTML side accepts an html string and optional styles. Each string is limited to 256,000 characters, including inline base64 images.

Return address

For products that include an envelope, add an optional top-level return_address to print the sender address on the envelope PDF and preview. The recipient address is unchanged. Omit return_address to keep the existing behavior with no sender address. Products without an envelope do not print a return address.

{
  "return_address": {
    "type": "return",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "company": "Example Co",
    "address1": "1 Example Street",
    "city": "London",
    "state": "London",
    "postal_code": "SW1A 1AA",
    "country": "GB"
  }
}

type must be return. first_name, address1, city, state, postal_code, and a two-letter country code are required. last_name, company, address2, address3, and region are optional. Invalid return addresses are rejected during request validation. Use a return address from the region supported by the selected product: UK/Europe for ISO products or North America for US products.

The top-level address applies to every valid recipient in the batch. Per-item return addresses are not supported; use separate requests for different senders.

Each request with a return address uses a separate campaign, so a later request cannot change the sender address of recipients already created.

Example request

curl --request POST 'https://platform.scribeless.co/api/recipients/html/bulk' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data '
{
  "product_key": "a6_postcard",
  "orientation": "landscape",
  "data": [
    {
      "data": {
        "first_name": "Jane",
        "address": {
          "address1": "123 Example Street",
          "city": "Amsterdam",
          "postal_code": "1011 AB",
          "country": "NL"
        },
        "variables": { "externalId": "customer-123" }
      },
      "html": {
        "front": { "html": "<p>Approved postcard for Jane</p>" },
        "back": { "html": "<div data-sqr data-sqr-id=\"offer\" data-sqr-destination=\"https://example.com/jane\"></div>" }
      }
    }
  ]
}
'

Response

Successful requests return campaign_id and a recipients array with one result per input, in input order. Valid items contain their ID and status; invalid items contain an error message and are not created.

{
  "campaign_id": "CAMPAIGN_ID",
  "recipients": [
    { "index": 0, "recipient_id": "RECIPIENT_ID", "status": "pending" },
    { "index": 1, "error": "Recipient validation error" }
  ]
}

index identifies the zero-based input position. If no campaign can be resolved, campaign_id is null. The upload does not wait for rendering or return document URLs.

Payment

Campaign checkout includes earlier unpaid uploads to the same campaign.

HTML and images

Smart QR, HTTPS images, and inline base64 images follow the HTML recipient guidance. External images must use HTTPS, resolve to public IPs, return image/*, and must not redirect.

For edge-to-edge backgrounds, use each side's styles.backgroundImage or backgroundColor. See artwork size and bleed for image dimensions, positioning, and 300 ppi sizes.

Payload limits

The entire request body is limited to 32 MB.

All recipient data, HTML, and embedded images count towards this limit. If you receive 413 Payload Too Large, reduce the batch size or use HTTPS image URLs.

Status codes