# Getting HTML into Envoke

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](https://envoke-developers.pages.dev/v2/templates/insert/) or [update](https://envoke-developers.pages.dev/v2/templates/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](#moving-between-editors)) |
| Messages API: [create or update](https://envoke-developers.pages.dev/v2/messages/fields/#html-template_id-and-replace) a draft message | 200 KB, checked before `replace` | `replace` values substituted once, when the message is saved | As for the Templates API |
| [Send API](https://envoke-developers.pages.dev/v1/send/fields/#html-template_id-and-replace) | 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](https://envoke-developers.pages.dev/email-html/testing-and-accessibility/#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`.

```bash
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](https://envoke-developers.pages.dev/guides/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](https://envoke-developers.pages.dev/email-html/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](https://envoke-developers.pages.dev/email-html/merge-tags/#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](https://envoke-developers.pages.dev/email-html/merge-tags/#send-api-messages) for what is filled in with `enable_merge_fields` off and on, and [Send API Differences](https://envoke-developers.pages.dev/email-html/what-happens-at-send/#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](https://envoke-developers.pages.dev/email-html/editable-templates/#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](https://envoke-developers.pages.dev/email-html/overview/#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](https://envoke-developers.pages.dev/email-html/editable-templates/#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](https://developers.envoke.com).*