---
title: Preparing email widgets
related:
  - https://docs.kentico.com/13/on-line-marketing-features/configuring-and-customizing-your-on-line-marketing-features/configuring-email-marketing/preparing-email-templates.md
  - https://docs.kentico.com/13/on-line-marketing-features/managing-your-on-line-marketing-features/email-marketing/composing-marketing-emails.md
  - https://docs.kentico.com/13/on-line-marketing-features/configuring-and-customizing-your-on-line-marketing-features/configuring-email-marketing/reference-email-marketing-macro-expressions.md
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

Email widgets in Xperience represent reusable pieces of code that can be easily manipulated by business users. This allows for greater flexibility when [composing marketing emails](https://docs.kentico.com/13/on-line-marketing-features/managing-your-on-line-marketing-features/email-marketing/composing-marketing-emails.md). Email widgets need to be placed in [email widget zones](https://docs.kentico.com/13/on-line-marketing-features/configuring-and-customizing-your-on-line-marketing-features/configuring-email-marketing/preparing-email-templates.md#preparingemailtemplates-adding_email_widget_zones), defined in individual [email templates](https://docs.kentico.com/13/on-line-marketing-features/configuring-and-customizing-your-on-line-marketing-features/configuring-email-marketing/preparing-email-templates.md).

You can manage email widgets in the **Email marketing** application on the **Email widgets** tab.

![](https://docs.kentico.com/docsassets/13/preparing-email-widgets/marketing_email_widgets.png)

## Creating email widgets

To create a new email widget for use in marketing emails:

1. Open the**Email marketing** application and switch to the **Email widgets** tab.
2. Click **New email widget**.
3. Specify the display name.
4. (Optional) Set the email widget thumbnail (a custom image or a [font icon](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/working-with-font-icons.md)).
   - Thumbnails are used to represent individual email widgets when listed on an email's **Email builder** tab.
5. Click **Save**.
   - The system creates the email widget and opens its **Widget editor** tab.
6. Write the code of the email widget in the code editor.

   - You can see the macros specifically available for email marketingin the [email marketing macro reference](https://docs.kentico.com/13/on-line-marketing-features/configuring-and-customizing-your-on-line-marketing-features/configuring-email-marketing/reference-email-marketing-macro-expressions.md).
   - To protect macros from [XSS](https://docs.kentico.com/13/securing-websites/developing-secure-websites/cross-site-scripting-xss.md), you need to [properly encode](https://docs.kentico.com/13/securing-websites/developing-secure-websites/macros-and-security.md#output-encoding-of-macros) all properties and input values that are processed.
7. Click **Save**.
8. (Optional) Define [email widget properties](#defining-email-widget-properties) on the **Properties** tab for greater customization options.

Now that you have created the email widget, you need to [assign it to the email template](#assigning-email-widgets-to-email-templates) you are going to use when [composing marketing emails](https://docs.kentico.com/13/on-line-marketing-features/managing-your-on-line-marketing-features/email-marketing/composing-marketing-emails.md). For an example demonstrating the email widget creation process, see the [example below](#example-creating-a-custom-email-widget).

### Defining email widget properties

Widget properties are parameters that can be defined for individual email widgets. Users can set the values of the email widget properties when [composing marketing emails](https://docs.kentico.com/13/on-line-marketing-features/managing-your-on-line-marketing-features/email-marketing/composing-marketing-emails.md), allowing for greater customization and reusability of each email widget. Email widget properties can be accessed through the macro engine and manipulated via [macro syntax](https://docs.kentico.com/13/macro-expressions/macro-syntax.md).

To define email widget properties:

1. On the **Email widgets** tab, **edit** () an email widget or [create a new one](#creating-email-widgets).
2. Switch to the **Properties** tab.
3. Define email widget properties via the [field editor](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/developing-form-controls/reference-field-editor.md).

You can now manipulate defined email widget properties in the code editor on the widget's **Widget editor**tab.

> **Note:** **Note**: If using macro expressions to set the **Default value** of an email widget property, accessing the values of the widget's other properties is NOT supported (via macros such as _{% Fields.FieldName %}_ or _{% FieldName.Value %}_).

> **Info:** To correctly display the [editor](https://docs.kentico.com/13/configuring-xperience/configuring-the-environment-for-content-editors/configuring-the-editor-for-rich-text-fields.md) toolbar for widget property fields using the **Rich text editor** form control, we recommend the following configuration of the fields (under the **Editing control settings (Advanced)** category):
>
> - **Width**: 100
> - **Width unit type**: %
> - **Toolbar set**: EmailWidgets
>
> The _EmailWidgets_ toolbar set is recommended for use in email widgets, since some of the default toolbar set features are not supported in the email builder. For more information about personalization of the editor toolbar, see [Personalizing the editor for rich text fields](https://docs.kentico.com/13/configuring-xperience/configuring-the-environment-for-content-editors/configuring-the-editor-for-rich-text-fields/personalizing-the-editor-for-rich-text-fields.md).

### Assigning email widgets to email templates

To be able to work with email widgets when creating marketing emails, you first need to assign the widgets to the [email templates](https://docs.kentico.com/13/on-line-marketing-features/configuring-and-customizing-your-on-line-marketing-features/configuring-email-marketing/preparing-email-templates.md) you are going to use for your marketing emails.

You can assign widgets to email templates either via the widget's **Assigned to email templates** tab, or the email template's **Available widgets** tab.

### Assigning email widgets via the Assigned to email templates tab

1. Open the **Email marketing**application and switch to the **Email widgets** tab.
2. **Edit**() the email widget you want to assign to a template.
3. Switch to the **Assigned to email templates** tab.
4. Click **Add templates**.
5. Select the email templates you need to assign and click **Select**.

### Assigning email widgets via the Available widgets tab

1. Open the **Email marketing** application and switch to the **Email templates** tab.
2. **Edit** () the template of the _Email_ type that you want to assign the widgets to.
3. Switch to the **Available widgets** tab.
4. Click **Add widgets**.
5. Select the widgets you need to assign and click **Select**.

Now that you have assigned the widgets to the email templates, you can use them when [composing marketing emails](https://docs.kentico.com/13/on-line-marketing-features/managing-your-on-line-marketing-features/email-marketing/composing-marketing-emails.md) on an email's **Email builder** tab.

## Personalizing email widgets

You can personalize emails by defining which users (recipients) are able to see specific email widgets. We recommend defining the visibility of email widgets based on recipient [personas](https://docs.kentico.com/13/on-line-marketing-features/managing-your-on-line-marketing-features/personas.md).

### Personalizing email widgets based on Personas

1. Open the **Email marketing** application and switch to the **Email widgets** tab.
2. **Edit**() the email widget you want to personalize.
3. Switch to the **Properties** tab.
4. Click **New field** and create a field with the following settings:
   - **Field name**: Personas
   - **Data type**: Text
   - **Field caption**: Personas
   - **Form control**: Uni selector (select via the _(more items...)_ option)
   - **Object type**: Personas.Persona
   - **Return column name**: PersonaGUID
   - **Selection mode**: Multiple
5. Click **Save**.
6. On the **Widget editor** tab, wrap the widget's existing code into a condition that checks the value of the **Personas** property:

   ```csharp title="Example"

   {% if(Recipient.IsInPersona(Personas)) { %}

       // Main widget code
       ...
   {% } #%}

   ```
7. Click **Save**.

When [composing marketing emails](https://docs.kentico.com/13/on-line-marketing-features/managing-your-on-line-marketing-features/email-marketing/composing-marketing-emails.md) on an email's **Email builder** tab, you can now select multiple **Personas** for the widget. The widget's content will then be visible only for recipients who belong to one of the given personas.

## Example – Creating a custom email widget

This example demonstrates how to create a new email widget acting as a link. Users will be able to modify the target URL and the displayed text when editing a marketing email and placing the widget in an email widget zone.

1. Open the **Email marketing** application and switch to the **Email widgets** tab.
2. Click **New email widget**.
3. Type _Customizable link button_ as the **Display name**.
   - The system automatically generates a **Code name** based on the _Display name_.
4. Click **Save**.
   - The system creates the email widget and opens its **Widget editor** tab.
5. Switch to the **Properties** tab and create the following fields:

   - **Field name**: TargetUrl
   - **Data type**: Long text
   - **Required**: Selected
   - **Field caption**: Target URL
   - **Field description**: Enter a target URL.
   - **Field name**: DisplayText
   - **Data type**: Text
   - **Default value**: Click me!
   - **Field caption**: Display text
   - **Field description**: Enter a display text.
6. On the **Widget editor**tab, copy the following code to the editor:

   ```css title="Custom email widget markup"

   <a href="{% HTMLAttributeEncode(TargetUrl) %}" class="button">{% HTMLEncode(DisplayText) %}</a>

   ```

   > **Note:** **Note**
   >
   > All necessary CSS and JavaScript markup needs to be included as part of the [email template](https://docs.kentico.com/13/on-line-marketing-features/configuring-and-customizing-your-on-line-marketing-features/configuring-email-marketing/preparing-email-templates.md) the email widget is assigned to.
7. Click **Save**.

The _Customizable link button_ email widget is now ready. Users can modify the target link and the displayed text when [composing a marketing email](https://docs.kentico.com/13/on-line-marketing-features/managing-your-on-line-marketing-features/email-marketing/composing-marketing-emails.md) and working with the widget on the email's **Email builder** tab.