Personalization

In many cases, when you trigger an event there may be some custom data you want to use in your notification. For example, when an Entry is saved you might want to know who the author was and where you can view the entry, when a form is submitted you may want to include the data from the Form submission in your notification, and when a product is purchased you might want to know which product and by whom.

Sprout Email allows you to personalize your email in several places including:

  • Subject line
  • From Name
  • From Email (you probably don't want to use this)
  • Reply To Email
  • Recipients
  • Custom Fields
  • Templates (HTML and Text)

You can personalize your Notification Email with data from an event's object variable which is uniquely defined by each Notification Event.

The Object Variable

To understand what values are available to use for personalization you will need to understand which Object variable is available when a Notification Email is triggered. The available Object variable will depend on the Notification Event, however, it will always be accessed in a similar way.

We use the variable name object because we want a single variable name for all Notification Events, even though it may refer to many different types of data. When an Entry Notification Event is triggered, the object variable may refer to the Entry Element. When a Commerce Product Notification Event is triggered, the object variable may refer to the Product Element.

As we use the object variable in our settings, we can think of each of our settings like a mini Twig template that only has our object variable available to it.

TemplateVariablesOutput
Subject Line (Notification Email)objectSubject Line (Message)
From Name (Notification Email)objectFrom Name (Message)
From Email (Notification Email)objectFrom Email (Message)
Reply To (Notification Email)objectReply To Email (Message)
Recipients (Notification Email)objectRecipients (Message)
Custom Fields (Notification Email)objectCustom Fields (Message Body)
Email Templates (Email Templates)email, objectEmail HTML & Text (Message Body)

TIP

If the idea of an object variable doesn't make sense yet, read more about Object Syntax.

Object Variables

The table below outlines the default Notification Events and the value you can expect when interacting with the Notification Event's object variable.

EventCraft 3Craft 2
When a new entry is createdEntryEntryModel
When an existing entry is updatedEntryEntryModel
When a new user is createdUserUserModel
When a existing user is updatedUserUserModel
When a user is activatedUserUserModel
When a user is deletedUserUserModel
When a user logs inUserUserModel
When a Craft Commerce order is completedCommerce_OrderModel
When a Craft Commerce transaction is savedCommerce_TransactionModel
When a Craft Commerce order status is changedCommerce_OrderModel, Commerce_OrderHistoryModel
When a Sprout Form Entry is submittedFormSproutForms_FormModel

Craft Commerce Order Status Event

The When a Craft Commerce order status is changed event provides two objects, so the syntax is slightly different.

Example variable syntax for the Commerce_OrderModel

  • {order.number}
  • {{ object.order.number }}

Example variable syntax for the Commerce_OrderHistoryModel

  • {orderHistory.newStatus.name}
  • {orderHistory.prevStatus.name}
  • {{ object.orderHistory.newStatus.name }}
  • {{ object.orderHistory.prevStatus.name }}

Templating

In your notification templates you can use any Twig code that you would use elsewhere in your templates. Additionally, Sprout Email Notifications give you access to the Notification Email Element (email) and any Notification Event Object variable (object):

{# Notification Default Fields #} {{ email.subjectLine }}<br/> {{ email.slug }}<br/> {{ email.status }}<br/> {{ email.fromName }}<br/> {{ email.fromEmail }}<br/> {{ email.replyTo }}<br/>  {# Notification Custom Fields     These examples may not work in your project. You will need to    update these examples to reference custom fields you are using. ------------------------------------------------------------ #} {{ email.emailBody }} {{ email.emailBanner.first().getUrl() }} {{ email.emailFooter }}  {# Dynamic Data    These examples may not work in your project. The available dynamic    values depend on the event you have triggered. ------------------------------------------------------------ #} {{ object.title }} {{ object.applicantEmail }} 

Processing Order

Using shorthand syntax in your Custom Fields and the Control Panel reduces the chance for errors. Some fields, such as the Rich Text field may add spaces between your tags using object syntax (i.e. {{ object.email }}) and cause errors during processing. Also, adding more complex Object Syntax in Twig code can create trickier situations to debug when sending email.

The order that your fields are processed is as follows:

  1. Subject, From Name, From Email, and Reply To fields are processed for Object variables.
  2. Templates are rendered. All Twig markup and Object variables in your templates are processed. Any Object variables in custom fields get treated as placeholders.
  3. Templates are processed once more to render Object variables within custom fields.

WARNING

While most of the time the order will not matter, if you need to use Twig syntax anywhere in your custom fields you can run into situations where it causes conflicts as you output it to the templates. For example, if you have a custom field with Twig code and output that field using a Twig filter in your templates, you will trigger an error. Keep it simple. Stick to the rules of thumb above. Test your emails. And check your logs for more details if you run into any issues.