Templates

Email templates on the active connection: a stored subject and body that a send fills in and reuses. Newest change first unless you sort otherwise. Reports whether each has a published version, which is what a send resolves to. A draft cannot be sent. Use search rather than listing everything and reading the names yourself: it matches the name, the slug, the description and the published subject. Use getTemplate for one in detail, including which version number is the published one.

One template in detail, by id (tpl_…) or by slug: its subject, its engine, every prop and slot it declares, and its versions. Read this before sending. The props it lists are exactly the keys sendWithTemplate will accept, and it accepts no others: an unknown key is refused and a missing required one is refused, rather than sent as a blank.

Create a template and, by default, publish it so it can be sent. Give it ONE of: html (markup you rendered yourself, which is sanitised once, when published); document (the whole block design the visual editor uses, with every block kind, Section/Row/Column layout, styles, fonts and preview text, checked as it goes in, with every problem listed at once); or blocks (a quick flat list of Heading/Text/Button/Link/Img/Hr with no styling). Declare a prop for every value that changes per message and write {{key}} where it goes, in the subject or the body; a required prop missing at send time is refused rather than sent blank. Slots are the same mechanism for values the AUTHOR fills, with a default that renders when nobody overrides it. Start from a design rather than from nothing where you can: listTemplateStarters names the ones that ship with the product, and passing one as starter seeds the subject and the body. updateTemplate edits a template afterwards, publishTemplate makes an edit live, and deleteTemplate removes one.

Render a template without sending it, so you can check your work first. Returns the subject and the body AS TEXT. The HTML a recipient would receive is a whole email document and is not readable here; the REST preview endpoint returns it if you need it. Lenient where a send is strict: a prop you left out is rendered blank and reported back, rather than refusing. Anything reported as unfilled WILL be refused by sendWithTemplate, so this is the cheap way to find out.

Send a message built from a stored template. THIS SENDS IMMEDIATELY. There is no confirmation step and no approval prompt on this server. Nothing asks the person before the mail leaves, exactly as sendEmail here does not. Call previewTemplate first and read what it renders; that is the only check there is. It is also not idempotent: calling it twice sends twice, because deduplication is keyed to an API key and an MCP session has none. Omit version to send whatever is published now, or pin one. Props must match exactly what getTemplate lists. An unknown key or a missing required one is refused rather than sent as a blank. Name from: there is no default sender, so a send without one is refused; listWorkspaceMembers names the addresses and whole domains you reach. Set cancellableForSeconds to hold the message briefly; cancelEmail can stop it until that time runs out.

One version of a template WITH ITS BODY, named by template id or slug and the version number getTemplate lists. This is the only way to read what an older version holds without changing anything. restoreTemplateVersion also reveals a body, but it moves the draft to do it, so reading version 3 that way costs you whatever you were editing. Read it here first, compare it with the draft, and restore only if you meant to. An html template comes back as the markup that was submitted, before the publish-time sanitiser; a blocks template comes back as its block tree. A long body is cut off at the end and says so.

Edit a template that already exists. Two kinds of field, and they behave differently. name, slug, description and status are metadata: they change in place and create no version. subject, html, blocks, props and slots are the BODY: the edit lands in the draft, and when the template has nothing left to edit (its head is published) a new draft numbered one higher is minted. Either way nothing a live send resolves moves until publishTemplate is called, which is what makes it safe to edit a template that is sending right now. Give one of html, document (the whole block design, every block kind and style, as getTemplateVersion returns it) or blocks (a flat list with no styling), never several. A field you leave out keeps what the head already had, so an edit to the subject alone keeps the body; props and slots, when sent, replace the whole list. Sending blocks replaces the block list and nothing else: the page settings the editor holds alongside it (preview text, web fonts, the Tailwind switch and the page style) are carried over from the version you are editing, so a template designed in the app does not lose its look to an edit made here. Read getTemplate first: the props it lists are what sends already pass, and dropping one makes those sends fail.

Publish a template's draft, which is what makes an edit reach the next message sent. Until this runs, sends keep resolving whatever was published before, so an edit nobody publishes changes nothing a recipient sees. Compiling happens here: a body that does not render is refused now, for you, rather than later for somebody reading their mail, and nothing is published when that happens. Publishing also sets the template back to active, so it reactivates an archived one. Calling it when the draft is already the published version returns it unchanged. Call previewTemplate first and read what it renders, and pass the version you read as expectedVersion so a draft somebody saved since is refused rather than published.

Copy a template into a new one: the same subject, body, props and slots, as a separate template with its own id and slug. The copy starts as a DRAFT whatever the source had published, so it cannot send until somebody publishes it, and nothing links the two afterwards. This is the safe way to try a redesign of a template that is sending in production: copy it, edit the copy, and leave the live one alone. It copies the HEAD, which is the unpublished draft when there is one. Leave name out and the source name is reused with a number appended.

Throw away a template's design and put a starter design, or another template's design, in its place. The template keeps its id, slug, name, description and status, and live sends keep resolving the published version until somebody publishes, but the body it replaces is GONE unless that body had been published, in which case it is still in the version list. Name exactly one source: starter (a slug from listTemplateStarters) or fromTemplateId (another template here, whose published design is copied). The new design brings its own props and slots and replaces the declarations wholesale, so sends passing the old props can start being refused. Read the result before publishing. Over MCP this runs as soon as you call it, with nothing to confirm it.

Bring an older version's body back as the current draft, which is how an edit somebody regrets is undone. The old version stays where it is in the list; its subject, body, props and slots are copied forward. A published head mints the next version, a draft head is overwritten, and nothing live moves until publishTemplate runs, so the restore is itself reversible until then. getTemplate lists the version numbers. Restoring the version that is already the head is refused, because it would do nothing.

Delete one version of a template and leave the template itself alone. It is for tidying a long version history, not for changing what sends. Three versions are refused: the live one, because sends resolve it; the head, because that is the draft being edited (restore an older version first and the old head becomes deletable); and the only version a template has, where deleteTemplate is the tool. Mail already sent is untouched, since a send keeps what it rendered, but anything pinning this version number starts failing and the number is never reused. There is no undo. Over MCP it runs as soon as you call it.

Delete a template and every version of it, permanently. There is no undo and no trash. Mail already sent from it is unaffected, because each send stores the body it rendered, but anything still sending against this id or slug starts failing. When you are not certain nobody points at it, use updateTemplate with status archived instead: that takes it out of the way and is reversible. Over MCP this runs as soon as you call it, with nothing to confirm it.

The starter designs that ship with the product: ready-made bodies with a subject and their own props and slots. These are the same designs the web editor offers, not workspace data, so the list is the same for everybody. Pass a slug from here as starter to createTemplate to begin from one, or to replaceTemplateContent to re-skin a template that exists. Reach for one before writing a body by hand: a starter is a designed email, and blocks you invent are not.

One starter design in full, by the slug listTemplateStarters reports: its subject, its props and slots, and the whole document it would seed, page settings and web fonts included. Passing the slug as starter to createTemplate or replaceTemplateContent does the same seeding in one call and is the shorter route. Read it here when you want to change the design BEFORE it becomes a template, or to see what a starter actually looks like rather than guessing from its name. A long document is cut off at the end and says so.

How a template has actually performed: how many messages it sent in the window, how many of those were tracked at all, and how many were opened and clicked, with the same figures per version so a redesign can be compared with what it replaced. Rates are over what was TRACKED, never over everything sent, because a message sent with tracking off can never report an open and counting it would make every rate look worse than it is. The gap between sends and tracked is that mail, not missing data. Lifetime figures ignore the window.

The individual messages a template sent, newest first, rather than the totals getTemplateAnalytics reports. Each row names its recipients, the version that rendered it, where it was sent from, and whether it was opened or clicked. This is the tool for "who got the October one" and for finding the send behind a complaint. Filter by version to compare a redesign against what it replaced, or by opened and clicked to pull out the people worth following up. A message sent with tracking off reports no opens and no clicks; that is absent data, not a zero, and each row says which it is.

The images uploaded for templates in this workspace, newest first, each with the public url to put in a template. Pass the cursor from the last line to read the next page.

Upload an image for templates, the way the template editor does, and get the public url to use in a template. Pass the picture in base64 as image, with its type: image/png, image/jpeg, image/webp, image/gif, image/svg+xml, up to 5 MB. It is fitted into 1200 by 1800 pixels and stored in a form every mail client shows.

The versions of one template, newest first, a page at a time, as the version history of the template editor lists them: each one’s number, whether it is a draft or published, its engine, its subject and when it was published. Name the template by id (tpl_…) or slug. Says which version sends resolve to and which is the draft being edited. getTemplateVersion reads the body of one of them.

Render a template design that is not saved, as the preview of the template editor does, without saving or sending anything. Give ONE of html (markup) or document (the whole block design), the subject, the props and slots it declares, and values to fill them with. Every {{key}} the subject or body uses has to be declared, as a save requires. Returns the subject and the body AS TEXT, and names every declared key left without a value. Use it to check a design before createTemplate or updateTemplate saves it. previewTemplate renders a saved template instead.

Design a new email template and save it. Use this whenever the user asks you to create, make, build or design a template or an email design, whatever it is for: a newsletter, a launch, a welcome series, a receipt, an event invite. A designer builds it from every block the editor has (sections, rows and columns, headings, text, rich text, buttons, images, dividers, code), with a full palette, type and spacing, and it opens in the visual editor fully editable. Put everything the user asked for in the brief. It takes up to a minute. It is saved as a draft unless the user asked for it to go live, and a draft cannot be sent until publishTemplate. Never write template blocks yourself for this; describe what you want in the brief.

Change the design or content of an existing template: restyle it, change colours, fonts or spacing, rewrite or translate its copy, add, move or remove sections, swap an image, fix a link, or redesign it completely. A designer applies the change to the real block tree and leaves everything else alone. Use it for every change to what a template looks like or says, from one word to a redesign. The change lands in the draft: live sends keep using the published version until publishTemplate. It takes up to a minute.