Getting HTML into Envoke

View as Markdown

Your HTML reaches Envoke through one of the three APIs or the Edit HTML page in the drag-and-drop editor. None of them checks or cleans the HTML; this page lists what each one does accept, limit, and change.

Ways In

Way in	Size limit	Changes made on the way in	Editor the HTML opens in
Templates API: create or update a template	200 KB	None: stored exactly as sent	Drag-and-drop if the HTML contains the `TEMPLATE_VERSION` meta tag (see Moving Between Editors)
Messages API: create or update a draft message	200 KB, checked before `replace`	`replace` values substituted once, when the message is saved	As for the Templates API
Send API	200 KB	None; per-recipient `replace` values are substituted when each email is delivered	As for the Templates API
Edit HTML page	None	None: stored exactly as typed	Unchanged
Copying with `template_id` (any API)	Not checked	None	The same editor as the source

The 200 KB limit is 204,800 bytes of HTML. Over it, the API returns The field 'html' may not be longer than 200kB. Emails much smaller than that are still clipped by Gmail; see Size and Clipping.

Templates API

A template created with html is stored exactly as you sent it. Templates can then be chosen as the starting point for new messages in Envoke, or copied into a message with the Messages or Send API’s template_id.

curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d @template.json \
  "https://e1.envoke.com/v2/templates"

where template.json holds {"name": "Monthly newsletter", "html": "<!DOCTYPE html ...>"} with the HTML as a JSON string. See Authentication for the API ID and API Key.

Messages API

A message created with html is stored as sent, after any replace values have been substituted. Only draft messages can be updated.

replace is for content that is the same for every recipient, such as a show title or this week’s listings. Use merge tags for content that differs per contact. Every placeholder you put in the HTML for replace must be replaced: a placeholder made of letters, numbers, and underscores in single braces, such as {SHOW_TITLE}, is treated as a contact field when the email is sent and is removed from the email if it is still there (see When a Tag Is Wrong).

Send API

The Send API stores the HTML once and personalises it for each recipient when the email is delivered: each recipient’s replace values first, then merge tags. Merge tags are off by default; see Send API Messages for what is filled in with enable_merge_fields off and on, and Send API Differences for the other ways a Send API email differs from a campaign.

Edit HTML Page

In the drag-and-drop editor, users whose role allows editing HTML have an Edit HTML button, which opens the whole document as source code. This is the way to make changes the editor’s dialogs cannot, such as fixing markup that is not editable.

What you save is stored exactly as typed. There is no size limit and nothing is checked.
The button is shown only for messages and templates that open in the drag-and-drop editor, and saving does not change which editor they open in.
The next time the message is opened and saved in the drag-and-drop editor, it goes through the same changes as any other HTML (see What the Editor Adds and Changes).

Copying a Template

template_id on the Templates, Messages, and Send APIs copies the HTML of an existing template or message, together with which editor it opens in. The copy is not checked against the 200 KB limit and is not changed.

Moving Between Editors

When the APIs receive html, they look for the exact text <meta name="TEMPLATE_VERSION" (see Two Editors).

Request	HTML has the meta tag	HTML does not
Create	Opens in the drag-and-drop editor	Opens in the HTML editor
Update	Opens in the drag-and-drop editor from now on	Keeps the editor it already had

A template or message that opens in the drag-and-drop editor keeps opening there even if you replace its HTML with HTML that has no meta tag, and the editor will then find nothing it can edit (see HTML Without Sections or Rows). Keep the meta tag in every version of HTML meant for the drag-and-drop editor.

Full reference, OpenAPI description, and Postman collection: developers.envoke.com.