The replace property in the Messages API allows you to dynamically inject text or HTML into your emails at the time of sending. This provides a highly flexible way to reuse templates while customizing the exact content delivered to your recipients.
Data structure and allowed key values
The replace property is a simple JSON object where you define the target keys to be replaced and the values to replace them with.
Values must be a string.
Keys must be delimited by curly brace characters. For example,
{DATE_REPORTED}or{BODY_CONTENT_HTML}are valid key values.
Important Note on System Preferences: You cannot replace Envoke preferences page merge patterns. Attempting to use keys such as {@pref-0}, {@consent-url}, etc., will return an error.
(Note: There is a similar "replace" feature for the Send API, which supports providing unique replace values for each recipient of the message. See examples for that API here.)
Use Case 1: Populating specific template variables
A common workflow is to design your complete email layout inside Envoke's drag-and-drop builder, leaving custom merge fields as placeholders (e.g., {DATE_REPORTED}, {ACCOUNT_STATUS}). When you trigger the API, you simply pass the specific text values to fill in those blanks.
JSON Payload:
{
"subject": "Your Weekly Performance Report",
"recipient_tag": "Report Subscribers",
"template_id": "123456",
"replace": {
"{DATE_REPORTED}": "October 24, 2023",
"{REPORT_NAME}": "Q3 Marketing Analytics",
"{TOTAL_CLICKS}": "1,432"
}
}
cURL Example:
curl -X POST -u API_ID:API_KEY \
-d '{"subject":"Your Weekly Performance Report","recipient_tag":"Report Subscribers","template_id":"123456","replace":{"{DATE_REPORTED}":"October 24, 2023","{REPORT_NAME}":"Q3 Marketing Analytics","{TOTAL_CLICKS}":"1,432"}}' \
"https://e1.envoke.com/v2/messages"
Use Case 2: The "Master Template" approach (Dynamic HTML Injection)
If you want maximum control over your email content from within your own application, you can use Envoke to host a "Master Template."
In this approach, you build a single template in Envoke that contains your standard brand header, styling, and footer. In the middle of the template, you place a single replace tag, such as {BODY_CONTENT_HTML}.
When calling the API, you pass the entire HTML body content as the replacement value. This is a highly powerful and flexible option because it drastically reduces the need to build and maintain dozens of different templates inside Envoke.
JSON Payload:
{
"subject": "System Alert: Maintenance Required",
"recipient_tag": "IT Alerts",
"template_id": "987654",
"replace": {
"{BODY_CONTENT_HTML}": "<h2>Critical Alert</h2><p>The server <strong>app-prod-01</strong> requires a reboot.</p><br><a href=\"https://status.yourdomain.com\" style=\"padding:10px; background:#007BFF; color:white;\">View Status Dashboard</a>"
}
}
cURL Example:
curl -X POST -u API_ID:API_KEY \
-d '{"subject":"System Alert: Maintenance Required","recipient_tag":"IT Alerts","template_id":"987654","replace":{"{BODY_CONTENT_HTML}":"<h2>Critical Alert</h2><p>The server <strong>app-prod-01</strong> requires a reboot.</p><br><a href=\"https://status.yourdomain.com\" style=\"padding:10px; background:#007BFF; color:white;\">View Status Dashboard</a>"}}' \
"https://e1.envoke.com/v2/messages"
Use Case 3: Using inline HTML (No existing template)
Instead of using a pre-built template in Envoke via template_id, you can provide the exact HTML markup directly using the html field, and use the replace object to inject variables into it on the fly.
JSON Payload:
{
"subject": "Inline HTML API example",
"recipient_tag": "Example list",
"replace": {
"{headline_text}": "Hello world!",
"{body_text}": "Content line 1<br><br>Content line 2"
},
"html": "<h1>{headline_text}</h1><p>{body_text}</p><p><a href=\"https://test.com\">Here is a link</a></p>"
}
cURL Example:
curl -X POST -u API_ID:API_KEY \
-d '{"subject":"Inline HTML API example","recipient_tag":"Example list","replace":{"{headline_text}":"Hello world!","{body_text}":"Content line 1<br><br>Content line 2"},"html":"<h1>{headline_text}</h1><p>{body_text}</p><p><a href=\"https://test.com\">Here is a link</a></p>"}' \
"https://e1.envoke.com/v2/messages"