About the Email Design Themes API

An email design theme is a reusable definition of an email's look and feel, such as its colors, fonts, and spacing. Email design themes are used by emails composed in the Wix email editor, including Wix Email Marketing campaigns and automated emails: a site owner picks a theme in the editor, and the editor applies it to the email they're composing. Themes are stored per site, so a site's emails can share a consistent visual identity without repeating styling decisions in every email.

With the Email Design Themes API, you can:

Create, retrieve, update, and delete a site's email design themes.
Query a site's email design themes by ID, title, creation date, update date, or tags.
Assign and unassign tags on one or many email design themes.
React to theme changes through the created, updated, deleted, and tags-modified domain events.

How themes reach an email

The Wix email editor applies a theme by copying the theme's body into the email at compose time. It doesn't keep a reference to the theme, which has two consequences worth designing around:

Editing a theme doesn't change emails that were already composed with it, including emails that haven't been sent yet.
Deleting a theme doesn't affect emails that were composed with it.

Themes your app creates are visible in Wix. A theme created through this API appears in the theme picker wherever the Wix email editor is used, such as when composing an Email Marketing campaign or an automated email. There, it can be selected and applied to the email being composed, exactly like a theme saved from the editor. Deleting a theme through this API removes it from the picker everywhere.

The theme body

A theme's body is a free-form JSON object whose structure is defined by the Wix email editor. It holds a palette of colors, a body object with page-level settings such as background color and width, and a classes object mapping named styles, such as heading-text, section, and primary-button, to the properties applied when the theme is rendered. Some themes also carry an elements object holding defaults for built-in email elements.

Treat body as the editor's, not as a schema to build against. The set the editor writes can change without a version bump to this API, so code that reads body should tolerate keys it doesn't recognize. The method and event samples in this reference show an abbreviated body with 3 representative classes. The Email Design Theme object sample shows a complete one.

The API doesn't validate the structure of body. It accepts any JSON object up to 256 KB (262,144 bytes), so a theme that saves successfully may still fail to render. The Wix email editor doesn't render styling that doesn't follow its structure. Validating the structure, and handling themes written by an earlier version of your app, is the responsibility of the app that renders the theme.

A body doesn't need to define every style class. When a theme doesn't define a class, the Wix email editor uses its default styling for that class. When a theme doesn't include a palette, its color palette in the editor is empty.

Theme allowance

The number of email design themes a site can hold depends on its Wix Email Marketing plan. To read the cap, call Get Account Details and read package.featureAllowances.designThemes.limit. A limit of -1 means unlimited, and a limit of 0 means the plan doesn't include email design themes.

Create Email Design Theme fails with OUT_OF_QUOTA when the site is at its cap. Deleting a theme frees a slot, and upgrading the site's plan raises the cap. If a site downgrades to a plan with a lower cap, its existing themes are kept and can still be retrieved, updated, and deleted. Creating themes fails until the site has fewer themes than the new cap.

Before you begin

It's important to note the following points before starting to code:

There's no public API for applying a theme to an email or a campaign. Themes are a styling store: your app reads a theme with Get Email Design Theme and applies its body on its own side.
Email design themes are scoped to a site. A theme created for one site isn't visible to another.
A new site has no email design themes. Themes exist only once a site owner saves one from the Wix email editor or your app creates one, subject to the site's theme allowance.
Uninstalling the Wix Email Marketing app from a site doesn't delete the site's email design themes.
Only id, title, createdDate, updatedDate, and tags are queryable. You can't filter or sort by anything inside body.

Use cases

Terminology

Email design theme: A named, reusable definition of an email's look and feel.
Body: The theme's styling definition, as a free-form JSON object. Its shape is defined by the Wix email editor.
Style class: A named entry in a theme's classes object, such as heading-text or primary-button, holding the styling the editor applies wherever that class is used.
Palette: The list of colors a theme defines, stored in the palette array of its body.