openemail templates

Returns one page of the workspace's templates, ordered by updatedAt descending. Each row carries the published version's subject, engine, slots and props, so you can see what a send needs without fetching every template. A template with nothing published omits those four fields and reports publishedVersion as null.

Paging is keyset on updatedAt, and the cursor is opaque: it holds the sort and where the last template on the page sat in it, so a template deleted while you page never breaks the walk. Editing a template moves it to the front, so a template changed while you page can show up twice.

--status narrows to one template status. draft is the status of a template created without publish and never published or activated since. It does not mean "has unpublished edits": check latestVersion against publishedVersion for that.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.

Fetches one template by tpl_ id or by slug. Every templates method accepts either, and the two cannot collide because ids carry the tpl_ prefix while a slug has no underscores. Pin the slug in code: it is derived once at creation and never changes when the template is renamed.

latest is the head version, meaning the current draft, or the published version when nothing has been edited since. This is the only read that returns the body: document for the blocks engine, and html for the html engine exactly as submitted, before sanitising. The top level subject, engine, slots and props describe the published version, which is what a send uses, so they differ from latest while somebody has unpublished edits.

When nothing has been published yet, publishedVersion is null and the top level subject, engine, slots and props are absent. Read the draft from latest instead. Use list or listVersions to find out whether a template can actually be sent.

Creates the template together with version 1. Without publish: true that version is a draft, and a draft cannot be sent: send answers 422 template_not_published until somebody calls publish. With publish: true the body is compiled straight away and the template starts active, so a body that fails to render is refused here instead of later.

The engine follows what you send. Posting html selects the html engine, anything else is blocks. A blocks template stores a document whose body is a tree of @react-email/components nodes (Section, Row, Column, Container, Text, Heading, Button, Link, Img, Hr, Markdown, CodeBlock and CodeInline), validated on the way in with a ceiling of 500 nodes nested 8 deep. An html template stores markup you rendered yourself, for example with @react-email/render in your own build, and it is sanitised when the version is compiled.

{{key}} placeholders are filled from declared slots and props. A slot has a default and belongs to whoever edits the template. A prop is supplied by the sender and can be required. Keys start with a letter and continue with letters, digits or underscores, and one key cannot be both. In a blocks template an undeclared placeholder is a 422 invalid_template naming its path. In html markup, any placeholder used inside an attribute such as href or src must be declared with kind url or image, or compiling fails.

Changes a template in place. name, description and status are metadata and never create a version. Sending any of subject, document, html, slots, props or engine is a body edit: if the head version is still a draft it is overwritten, and if the head is published a new draft numbered one higher is minted. Body fields you leave out keep the head's values, so a patch carrying only subject keeps the existing document and declarations, while slots or props replace the whole list.

Nothing here changes what a live send resolves to. Sends keep using the published version until you call publish, which is what makes it safe to edit a template in production. The response's latest is the version this call wrote into.

Pass --expected-version with the latestVersion you read before editing. If another writer has moved the head since, the call fails with 409 version_conflict instead of overwriting their change. Without it the last write wins. Setting status: 'archived' is the reversible alternative to delete, but it does not block sends: an archived template with a published version still sends.

Creates a new template from the HEAD version of an existing one: the same subject, body, slots and props, and the source's description. The copy starts at version 1 as a DRAFT, whatever the source had published, so a copy is never sendable by accident. Publish it when you mean to.

The copy is a separate template with its own id and slug. Nothing links it back to the source, so editing either one afterwards leaves the other alone. This is the safe way to try a redesign of a template that is sending in production.

name is optional. Left out, the source name is reused, and because a name is unique per workspace the server appends a number until one is free, up to twenty attempts. Sending a name that is already taken behaves the same way, so a script that copies nightly keeps working.

Replaces the whole body of a template with a starter design or with another template's body, keeping the template's own identity: its id, slug, name, description and status do not move, and neither does what a live send resolves to.

The write lands exactly where an update to the body lands. A draft head is overwritten in place; a published head mints version N+1 as a draft. Sends keep resolving the published version until you publish, so this is safe to call on a template that is sending.

Name exactly one source. starter takes a slug from listStarters; --from-template-id takes another template in the same workspace, whose published version is copied when it has one and whose draft is copied otherwise. Sending both, neither, or the target itself is a 422. A source in another workspace is a 404, like everything else here.

This discards the body it replaces. A version that was published is still in the version list and can be restored, but an unpublished draft body is gone.

Permanently removes the template and all of its versions. There is no undo. Mail already accepted is unaffected, because each send stores the body it rendered, but any integration still sending against this id or slug starts receiving 404s.

If you might need the template again, archive it with update(idOrSlug, { status: 'archived' }) instead. The response is a tombstone rather than an empty body, so a log line can record exactly what was removed.

Returns one page of a template's versions, newest first. At most one version is a draft and it is always the highest number. Every version below it has been published, and the highest published version is the one unpinned sends resolve to.

Bodies are left out, so document and html are absent on every row. What each version declares (subject, slots and props) is present, which makes this the call for checking what pinning a version on send would commit you to.

Pages are keyset on the version number, so a version deleted while you walk never breaks the walk: the next page starts at the first version below the cursor.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.

One frozen revision with its body. document carries the block tree for the blocks engine and html carries the submitted markup for the html engine, alongside the subject, slots and props that were declared at the time.

This is what listVersions leaves out. It is the only way to read an old version without changing anything: restoreVersion also shows you the body, but it moves the head to get there, so reading version 3 used to cost you your draft.

Reach for it to diff a regression against the revision that worked, to lift a block out of a design you have since replaced, or to record what a campaign actually said.

Freezes the head version and makes it the one unpinned sends resolve to. Compiling happens here: a blocks tree is rendered through react-email and html markup is sanitised, so a body that does not render fails with 422 invalid_template for the person publishing rather than for a recipient. Nothing is published when that happens.

The call is idempotent. If the head is already the published version it comes back unchanged, so a deploy script can publish on every run. Publishing also sets the template's status to active, which reactivates an archived template.

Only the head can be published, and there is no call to republish an older version. To keep production on an earlier version while a new one is prepared, pin that version on send. The response is the published version with the updated parent attached as template.

Copies an older version's subject, body, slots and props forward into the head, which is how you undo a design you regret. Nothing is rolled back in place: the old version stays where it is in the list and the restored copy becomes the current draft.

Where it lands follows the usual rule. A published head mints version N+1 as a draft; a draft head is overwritten, so restoring twice does not pile up versions. Live sends do not move until you publish, so a restore is reversible until then: restore something else, or publish to commit.

Restoring the head itself is a 422, because there is nothing to bring back. An unknown version is a 404. --expected-version makes the call safe against a concurrent editor, the same as on update.

Removes a single revision and leaves the template itself alone. It is for tidying a long version list, not for changing what sends.

Three versions cannot be deleted, and each refusal is a 422 rather than a silent success: the LIVE version, because sends resolve it; the HEAD, because that is the one being edited, and restoring an older version first is how you move off it; and the only version a template has, because a template with no versions could not be read at all, so delete the template instead.

Everything else is fair game. Mail already sent from a deleted version is untouched, since a send stores the body it rendered, but a send that pins a deleted version starts failing with template_version_not_found.

The starter designs the web editor offers, as a plain array. A starter is a ready-made block document with a subject and its declared slots and props, and it is the same catalogue the console shows, so an integration and a person building a template by hand start from the same place.

Bodies are left out here. slug is the handle to pass as starter to create or replaceContent, and getStarter returns one in full with its block tree and a rendered preview.

Starters are static: they are part of the product rather than workspace data, so this answer is the same for every key and changes only when a release adds one.

One starter in full: everything the list carries, plus document, the block tree itself, and preview, the starter rendered to HTML with each undefaulted prop left visible as {{key}}.

The preview is what the console shows in its starter picker, so a client can display the same thing without rendering anything itself. The document is there so you can seed a template from a starter and edit the tree before creating it, rather than creating from the starter and patching afterwards.

An unknown slug is a 404. Pass the slug exactly as listStarters reports it.

Every web font a template may load, as a plain array, in the order the web editor offers them. Each row names a family, the full CSS stack to write, the fallback a mail client shows when it cannot load the font, the weight range the file covers, and the url the file is served from.

The list is closed on purpose. A font file is fetched by the reader's mail client the moment the message is opened, so a font loaded from anywhere else would tell whoever runs that host when the message was read, whatever the workspace has open tracking set to. A template whose webFont.url is not the one listed here for its family is refused with 422 invalid_template.

Fonts are static: they are part of the product rather than workspace data, so this answer is the same for every key and changes only when a release adds one.

Compiles and renders content you pass in, without creating a template or touching one. This is what the web editor calls while somebody types, and it is the call for checking a design in CI before it becomes a template.

Everything create accepts as content is accepted here: document for the blocks engine, html for the html engine, plus subject, slots and props. values.props and values.slots fill the placeholders; anything left unfilled is rendered blank and reported in warnings, exactly as preview does for a stored template.

mark: true leaves every placeholder visible as {{key}} instead of substituting it, which is how an editor shows an author what is a variable.

Renders a version with the values you pass and returns the subject, HTML and plain text a send with the same values would produce. Nothing is sent or recorded. Point CI at it so a broken template is caught by a test rather than by a customer.

It renders the published version unless version names another one, and unlike send it can render a draft, which is compiled on the fly. A template with nothing published needs an explicit version, otherwise the call is a 422 template_not_published. Required props are relaxed here: a missing one renders its default or an empty string, and every placeholder that ends up blank is listed in warnings as unfilled_placeholder.

The other value checks still apply. A key the version does not declare is a 422 unknown_template_prop or unknown_template_slot, and a value that is not a string, number or boolean is a 422 invalid_template_prop. Values of kind url or image are parsed, and anything outside http, https, mailto, tel and cid renders as #.

The engagement report the console shows on a template: how many messages it rendered in the window, how many of those were tracked, how many were opened and clicked, and the same numbers broken down by day, by source and by version.

Rates are computed against what was TRACKED, not against everything sent, because a message sent with tracking off can never report an open and counting it would quietly lower every rate. trackedForOpens and trackedForClicks are the denominators, and they are in the response so you can recompute anything yourself.

lifetime ignores the window: it is every live send this template has ever made, the test sends counted separately, and the first and last time it sent. recent previews the twelve newest sends in the window with their own open and click counts, which is the fastest way to see whether a template that was just published is behaving. It is a preview, not the list: listSends returns every send in the window, a page at a time.

Only live sends are in the windowed figures. A message sent with a test key counts in lifetime.testSends and nowhere else.

One row per message this template rendered, newest first, with the subject as it went out, who it went to, and whether it was opened or clicked. It is the list behind the numbers getAnalytics reports, and the place to answer "did this person get it".

Paging here is by page number rather than by cursor, because the console shows a table with a total, and total is the count matching the filters rather than the size of the page. Pages are 25 rows by default and at most 100.

The filters narrow by window (days or minutes), by version, by source, and by engagement: opened, clicked and tracked each take a boolean. search matches the subject and the recipient addresses. A row whose message carried no tracking reports matched: false and zero counts, which is not the same as nobody opening it.

Resolves the published version, or the one version pins, fills its placeholders from props and slots, and queues the message. Values are checked strictly here. An undeclared key is a 422 unknown_template_prop or unknown_template_slot, a missing required prop is a 422 missing_template_prop, and a value that is not a string, number or boolean is a 422 invalid_template_prop, each with param set to template.props.<key>. A template with nothing published, or a pinned version that is still a draft, is a 422 template_not_published. No mail leaves when any of these fail.

Pin version in production code. Without it every send resolves whatever is published at that moment, which changes the morning somebody publishes a rewrite. subject replaces the version's subject for this message only and is used exactly as written, with no placeholder filling. --scheduled-at takes a Date, an ISO 8601 instant or an ISO 8601 duration such as PT30M, up to 365 days out, and cannot be combined with a non zero --cancellable-for-seconds.

The SDK attaches an Idempotency-Key generated once per call and reuses it on that call's retries, so a retry replays the original message instead of sending a second one. Pass --idempotency-key to deduplicate across processes and restarts, and derive it from what caused the send, never from a clock. A replay resolves with replayed: true and the original message, while reusing a key with a different body is a 422 idempotency_key_reuse.

Resolves one page of the images uploaded for templates, newest first: the library the template editor offers when you add an image.

Template images belong to the workspace: every template in it can use them, and they stay at their address after the template that first used them is deleted.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.

Sends the image bytes as the request body and resolves with its public url, ready to put in a template. It is the upload of the template editor.

PNG, JPEG, WebP, GIF or SVG, up to 5 MB, fitted into 1200 by 1800 pixels and stored in a form every mail client shows. The type is read from --content-type, or from a Blob's own type when that is left out, and without either the server refuses the bytes with 422 invalid_image.

Template images belong to the workspace: every template in it can use them, and they stay at their address after the template that first used them is deleted.

A designer builds a new block template from a written brief, the way the assistant in the app does, and saves it, as a draft unless publish is true. It uses every block the editor has, with a palette, type and spacing, and the result opens in the visual editor fully editable.

Put everything the design must hold in brief: what it is for, the sections in order, the words, the colours and fonts, and which values change per recipient. starter builds on a starter design, and --image-file-ids places up to ten uploaded or received images. It spends one AI action and can take up to a minute.

A designer applies written instructions to a block template and leaves everything else alone: restyle it, change colours, fonts or spacing, rewrite or translate its copy, add, move or remove sections, swap an image. The change lands in the draft, so live sends keep the published version until you publish.

A raw HTML template cannot be redesigned and is refused with 422 invalid_template. It spends one AI action.