Message Template Merge

Overview

Nothing here is sent and nothing is connected to: you get the rendered text back and what you do with it is entirely your business. Two properties are the reason to use this rather than a string replace of your own, and both are tested rather than promised. The first is that substitution happens once. A value is written into the output and never looked at again, so a value containing {{other}} lands in the text literally instead of being expanded — which is what stops a small template and a small set of values from rendering into something enormous, and stops whoever supplied a value from introducing a placeholder the template's author never wrote. The second is that nothing is escaped. The result is plain text: no HTML escaping, no URL encoding, no quoting and no spreadsheet neutralisation, because the destination is unknown here and a half-applied escape is more dangerous than none since it looks safe. Escape at the boundary you are actually writing to, and there are skills for that. Four placeholder styles are understood, a value can be a string, a number or a true or false, and you decide what happens when a placeholder has no value: refuse the whole render, leave a blank, leave the placeholder as it was, or put your own text there. The rendered length is worked out before a single character is built, so a render that would pass your ceiling is refused rather than assembled and then thrown away.

Everybody writes their own merge, and everybody writes the same two bugs into it. The first is substituting in a loop until nothing changes, which feels thorough and means a value someone else supplied can introduce a placeholder your template never had, or expand until you run out of memory. The second is escaping helpfully — HTML-escaping a value on the way in, so the text is wrong in an SMS and still unsafe in a page because half the job was done in the wrong place. We do neither: one pass, no escaping, and both are held down by tests rather than by intent. Around that sit the boring things worth having — a policy for absent values instead of a silent blank, a length worked out before the string is built, and the same placeholder scanner our validation skill uses, so a template that passed review renders with exactly the placeholders you were told about.

When to use it

Scope

Non-goals

• Does not send, queue or deliver the rendered text, and opens no connection of any kind
• Does not escape anything for HTML — web.sanitize_html is what makes text safe to place in a page
• Does not URL-encode a value going into a link; web.url_encode owns that
• Does not neutralise a leading equals sign or plus for a spreadsheet; data.csv_escape_formula owns that
• Does not re-scan what it substituted, so a value containing a placeholder is never expanded
• Does not evaluate a section, a loop, a conditional or a filter
• Does not check whether a placeholder is permitted; communication.template_validate answers that

Properties

Capabilities

Cost & billing

Flat rate per invocation

File handling

How we handle your data

Input schema

Output schema

API contract

curl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"communication.template_merge","input":{"template":"Hi {{first_name}}, order {{order_id}} is on its way.","variables":{"first_name":"Alice","order_id":"4417"},"syntax":"MUSTACHE"}}'

import { Squillify } from "@squillify/sdk";

const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });

const { output } = await sq.execute("communication.template_merge", {"syntax":"MUSTACHE","variables":{"first_name":"Alice","order_id":"4417","item_count":3,"tracking_url":"https://track.example/4417"},"template":"Hi {{first_name}}, order {{order_id}} is on its way with {{item_count}} items. Track it at {{tracking_url}}. — the {{order_id}} team"});

Errors

Other limits

Limitations

• Does not send, queue or deliver the rendered text, and opens no connection of any kind
• Does not escape anything for HTML — web.sanitize_html is what makes text safe to place in a page
• Does not URL-encode a value going into a link; web.url_encode owns that
• Does not neutralise a leading equals sign or plus for a spreadsheet; data.csv_escape_formula owns that
• Does not re-scan what it substituted, so a value containing a placeholder is never expanded
• Does not evaluate a section, a loop, a conditional or a filter
• Does not check whether a placeholder is permitted; communication.template_validate answers that
• Producing HTML from untrusted values without sanitising afterwards
• Templates that need conditionals, loops or filters evaluated
• Anything expecting the substituted values to be scanned again for further placeholders

How to call

POST /v1/execute (requires authentication)

{
  "skillKey": "communication.template_merge",
  "input": {
    "syntax": "MUSTACHE",
    "variables": {
      "first_name": "Alice",
      "order_id": "4417",
      "item_count": 3,
      "tracking_url": "https://track.example/4417"
    },
    "template": "Hi {{first_name}}, order {{order_id}} is on its way with {{item_count}} items. Track it at {{tracking_url}}. — the {{order_id}} team"
  }
}

Examples

{
  "syntax": "MUSTACHE",
  "variables": {
    "first_name": "Alice",
    "order_id": "4417",
    "item_count": 3,
    "tracking_url": "https://track.example/4417"
  },
  "template": "Hi {{first_name}}, order {{order_id}} is on its way with {{item_count}} items. Track it at {{tracking_url}}. — the {{order_id}} team"
}

{
  "text": "Hi Alice, order 4417 is on its way with 3 items. Track it at https://track.example/4417. — the 4417 team",
  "missing": [],
  "summary": {
    "outputChars": 104,
    "placeholderCount": 5,
    "syntax": "MUSTACHE",
    "templateChars": 132,
    "substitutedCount": 4,
    "missingCount": 0,
    "missingPolicy": "FAIL"
  },
  "substituted": [
    {
      "occurrences": 1,
      "name": "first_name"
    },
    {
      "occurrences": 2,
      "name": "order_id"
    },
    {
      "occurrences": 1,
      "name": "item_count"
    },
    {
      "occurrences": 1,
      "name": "tracking_url"
    }
  ]
}

{
  "variables": {
    "comment": "<script>alert(1)</script> and a literal {{order_id}}",
    "order_id": "4417"
  },
  "missingPolicy": "KEEP_PLACEHOLDER",
  "template": "Order {{order_id}} note: {{comment}} (ref {{ref_code}})",
  "syntax": "MUSTACHE"
}

{
  "text": "Order 4417 note: <script>alert(1)</script> and a literal {{order_id}} (ref {{ref_code}})",
  "missing": [
    "ref_code"
  ],
  "summary": {
    "outputChars": 88,
    "placeholderCount": 3,
    "syntax": "MUSTACHE",
    "templateChars": 55,
    "substitutedCount": 2,
    "missingCount": 1,
    "missingPolicy": "KEEP_PLACEHOLDER"
  },
  "substituted": [
    {
      "occurrences": 1,
      "name": "order_id"
    },
    {
      "occurrences": 1,
      "name": "comment"
    }
  ]
}

Recommended use cases

• Render a transactional message from a reviewed template and per-recipient values
• Fill the stable parts of a template now and leave the rest in place with KEEP_PLACEHOLDER for a later stage to complete
• Produce a subject line or an SMS body whose length you then check with communication.sms_segments
• Refuse a render outright when a required value is absent, rather than sending a message with a blank where a name should be

Avoid for

• Producing HTML from untrusted values without sanitising afterwards
• Templates that need conditionals, loops or filters evaluated
• Anything expecting the substituted values to be scanned again for further placeholders

Related skills

Composable with

Safety & privacy

• Runs without calling any external service.
• Your payloads are never stored permanently.
• Telemetry captures metadata only — never your payload contents.
• We never train models on your payloads.
• No human reviews your payloads.

Tags