Emails with Customized Merge Data

Overview

Data from virtually any query can be merged into a Composer email, provided that Composer is launched from a query result (not started via a group, in which case only recipient merge fields are available). Utilizing this feature is straightforward:

1. Create, craft, and run a query that includes the desired recipients and fields.
2. Select “Send an Email” from the Action menu. Select the option, “Include for mail merge?”
3. In the “Write Email” portion of the email, all fields in the query are available to use as merge fields.

Please read more about using Composer for general questions about its overall functionality. This article details this particular mail merge feature within Composer, system logic to be aware of when doing so, how several steps in the Composer process are different when using data merge fields, and recommendations on best practices.

Besides using the flexible, platform-based approach described in this article (where using the query builder can give you access to any queryable field in Axiom for email merge), there is also a narrower set of about 50-60 hard-coded merge variables that can be used for the recipient of the email. Depending on the message you’re writing, those “simpler” merge variables might be what you need. Read more about those “standard” merge variable options here.

Create the Query and Launch Composer

To use data merge fields in a Composer email, Composer must be launched from a query result (not started from a group).

1. Create and design a query that includes:
   • all of the desired recipients
   • the Person ID field (a normal requirement for launching Composer)
   • all of the desired fields displayed
     • hidden fields will not be  available as merge fields in Composer
     • spaces in field names will be replaced with the underscore (_) character in the merge fields
2. In the query results grid, click the Action menu and select “Send an email.”
3. Choose the “QUERY RESULTS” option, click “Continue,” then launch Composer.

The data merge fields are based on the person ID field in the query.

• The data in a Find Student query is based on the students. Though parents can then be targeted in the “Select Recipients” phase of the Composer email, doing so does not add in parent data.

The data fields are “frozen” when Composer is launched, so updates made to underlying data after Composer is launched will not be reflected.

• Example: Your student query includes the “Homeroom” field and you launch Composer but do not send the email. Subsequently, you update the “Homeroom” field for several students included in the query. Those homeroom updates are not reflected in the data used in the merge fields. To use the latest data, re-run the query and launch Composer from the fresh query results.

Recipient merge fields ({vc:nick_name}, etc.) remain available in all Composer emails, regardless of the choice made when launching Composer.

Using the Merge Fields

In the “Write Content” phase of a Composer email, the list of available merge fields are available in the bottom right pane. Click the “Available Merge Fields” header to expand it:

All fields from the query are available as merge fields in both the subject the body of Composer emails.

• Use the Default tab to view “default” merge fields that are always available.
• Use Query Results to view the list of custom fields drawn from the query.

Both types of fields can be used throughout the body of the email (including headers).

• Default merge fields use the prefix “vc:”
  • examples: {vc:first_name}, {vc:phone_mobile}
• Data merge fields use the prefix “data:” and the field names are drawn from the query, replacing spaces in field names with the underscore (_) character
  • Examples: {data:current_grade_description}, {data:enrollment_status_description}
  • The names of data merge fields depend on the underlying query data.

Video: Adding Merge Fields to an Email

Merge Fields in a Published Draft: Fields are not merged for news articles, but do display in messages shown to users in portals.

Select Recipients

Recipients are based on the underlying people in the query. The recipient list is calculated when Composer is launched; it is not updated. In order to use the merge fields, at least one person in the target recipients must have a populated Email 1 or Email 2 field. If not, they are only able to use the default merge fields.

Example: You create an email based on a query of ninth graders, but do not yet send it. When you return to the email, three new ninth graders have been added. Those three will *not* receive the email.

Target Recipients

1. Click the icon to navigate directly to person records in Axiom.
2. Click "Preview" to preview the email with that person's information supplying any merge fields.

The most important recommendation: Preview your email before sending to ensure that the right recipients see the right data.

Target Parents/Guardians

Targeting parents using data merge fields is very useful if you want to send parents information about their children.

Example use case: Email parents information about their children's homeroom, advisor, and enrollment status. To do this, start with a Find Students query, add the Homeroom, Advisor, and Enrollment Status fields, then launch the query, use the custom fields, and target parents/guardians.

Targeting parents/guardians does not change the underlying data in the query, so if the query was started from a "Find Students" query, the data merge fields are still based on the student data, not the parent data. To use default merge data for parents, start with a "Find Parents" query.

Tip: If you are not sure who the merge data is based on, look at the Person ID field in the underlying data. Whoever that refers to (parents, students, etc.) is who the data in the data merge fields are based on.

Default merge fields, e.g., {vc:first_name} change to the target recipients.

Example: If you pull in the student's first_name field into a student query that then targets parents/guardians:

• {vc:first_name} = parent/guardian's first name
• {data:first_name} = student's first name

Parents/Guardians Tab

On the "Parents/Guardians" tab, select contacts with legal custody, etc. from the drop-down (same as a regular Composer email), and the same sorting, etc. abilities are available here as they are for targeting recipients.

• Exclude parent/guardian recipients by unchecking the "Include" field.
• Click "Preview" to see the email as it would look sent to the particular parent/guardian with the merge fields populated.
• Click "Open Record" (icon) on the far right to view the parent/guardian's record in Axiom.

Recipients Tab

On the "Recipients" tab of the "Target Parents/Guardians" option, you have the ability to include and exclude based on who the children are. Click the ellipsis (...) on the Include field to view the related parents/guardians. This option is helpful if you are not sure who the parents are, e.g., they might have different last names.

Duplicate Emails When Targeting Parents/Guardians

In "normal" Composer emails without data merge fields, targeted parents/guardians receive only one email, even if they have several children in the underlying query. Using data merge fields modifies this system logic:

• If a parent has more than one child and merge data about the children are being used, a separate email is generated for each child and the parent will get one email per student.
• When this happens, the parent/guardian is duplicated in the list of recipients because the duplication is intentional, reflecting the underlying query data.
• If no merge data is available for a particular student, there are no duplicates.

Most important tip of all: Preview the email before sending. Previewing specific recipients of the email can ensure that you are sending the data you expect to your recipients.

Preview & Test

View a preview of merge fields — and the whole email — on the "Preview & Test" phase of the Composer email. Scroll through the recipients with the left/right arrows.

• Click the ellipsis (...) icon to view the user in Axiom or exclude the recipient.
• Send a test email using the merge data currently being viewed.

Confirm and Send

In the "Content" section, text confirms that merge fields are available in the email (regardless of whether they were actually used). Nothing is displayed if merge fields were not pulled into the underlying query.