Email Design Themes API: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

Let a site owner pick a theme when composing an email

To let a site owner choose how an email looks without restyling it from scratch each time, your app can offer a theme picker backed by the site's saved themes.

Note that applying a theme happens entirely on your side. There's no API that attaches a theme to an email, so your app reads the theme and applies its body to the email it's composing.

To offer a theme picker:

1. Call Query Email Design Themes with an empty filter, sorting by title in ascending order, to list the site's themes. Show the returned title values in your picker, along with updatedDate so the site owner can tell apart themes that share a title.

2. Call Query Email Design Themes again with cursorPaging.cursor set to the returned pagingMetadata.cursors.next, and repeat until pagingMetadata.hasNext is false. Each page holds up to 100 themes.

3. When the site owner selects a theme, call Get Email Design Theme with its id to retrieve its latest body.

4. Apply the returned body to the email you're composing, and save the composed email with the styling already applied.

   Copy the styling into the email rather than storing the theme id and reading it again at send time. This matches how the Wix email editor behaves: a theme is a starting point, so later edits to the theme don't change emails that were already composed.

Let a site owner edit a theme without losing concurrent changes

Because a theme can be open in more than one place at a time, edits need to be applied against a known version.

To edit a theme safely:

1. Call Get Email Design Theme to load the theme the site owner wants to edit. Keep the returned revision.

2. When the site owner saves their changes, call Update Email Design Theme with the modified fields and the revision from step 1.

3. If the call fails with INVALID_REVISION, call Get Email Design Theme again to reload the theme, show the site owner what changed, and let them reapply their edit.

   Emails already composed with this theme keep the styling they were composed with. Editing a theme only affects emails composed after the edit.

Back up a site's themes to an external system

To keep an external copy of a site's themes, export them once in full and then export only what's changed since the last run. A theme's updatedDate is set when it's created and changes every time it's updated, so filtering by updatedDate picks up both new and edited themes.

To back up a site's themes:

1. For the first export, call Query Email Design Themes with an empty filter, sorting by updatedDate in ascending order.

2. Call Query Email Design Themes again with cursorPaging.cursor set to the returned pagingMetadata.cursors.next, and repeat until pagingMetadata.hasNext is false. Each page holds up to 100 themes.

3. Upload the returned themes to your external system, and save the latest updatedDate among them.

4. For each subsequent export, call Query Email Design Themes filtered to themes updated since the saved updatedDate:

   Copy

5. Repeat steps 2 to 4 for each subsequent export.

   To remove deleted themes from your backup, subscribe to the Email Design Theme Deleted domain event.