Implementing simplified email threading for email applications

Note: If your account was created on or after June 15, 2022, you already have simplified email threading in your account.

Zendesk introduced simplified email threading on June 15, 2022 to make conversations in modern email applications such as Gmail easier to follow and more productive for both end users and agents. To learn more about the change, see Understanding simplified email threading.

If your account was created before June 15, 2022, you can still implement the simplified threading experience in your account to try it out. If you decide you prefer the original experience, you can switch back to it.

This article describes how to implement simplified email threading in your account. It contains the following topics:

• Planning
• Listing the triggers and automations to update
• Updating the triggers and automations
• Updating the email templates
• Restoring the original email experience

Planning

In Zendesk, emails are created using a combination of triggers, automations, and email templates. To implement the enhanced email experience in your account, you need to identify and update any active triggers and automations that send email to users or groups. You also need to update the email templates.

Because of the potential for duplicate emails and an inconsistent email experience while you're in the process of making the changes, choose a time when you get a low volume of support requests to make the changes.

To minimize the time it takes to implement the changes, prepare ahead of time with the following steps:

1. Create a list of triggers and automations to update.
2. Clone the triggers and automations on your update list and deactivate them.
3. Make the necessary changes to the deactivated clones.

When you're ready to implement simplified email threading in your account, you can quickly activate the clones and deactivate the originals. You can also update the email templates at the same time.

Listing the triggers and automations to update

The first task is to create a list of all the triggers and automations that need to be updated to support simplified email threading.

Triggers and automations are rules that specify actions to take when certain conditions are met. Dozens of possible actions are available. Two of them, “Email user” and “Email group,” send email to users and groups when certain conditions are met.

You need to update any trigger or automation that meets all of the following criteria:

• The trigger or automation is active
• The trigger or automation has an “Email user” or an “Email group” action
• The email body of the action contains one or more of the original comment placeholders listed in Original comment placeholders to replace

Example trigger to add to the update list:

Zendesk has a number of default triggers and automations that meet these criteria. See Default triggers and automations to update. Add any active ones to your update list.

Your account may also have custom triggers and automations. You should review them for any that meet the criteria.

Note: If your triggers use dynamic content with placeholders, simplified email threads will display differently. Outgoing email notifications generated by those triggers will only show the latest comment instead of all comments in the ticket thread.

You can use Admin Center to find the triggers and automations to update. You can also use the Zendesk API. See Using the API to find triggers and automations to update.

To find the triggers and automations to update

1. Review Default triggers and automations to update and add any active ones to your update list.
2. Open the Triggers or Automations page in Admin Center.
   • Triggers: In Admin Center, click Objects and rules in the sidebar, then select Business rules > Triggers.
   • Automations: In Admin Center, click Objects and rules in the sidebar, then select Business rules > Automations.
3. Ignore any inactive trigger or automation.
4. Ignore any default trigger or automation you added to your update list in step 1.
5. Open each remaining trigger or automation and look for an “Email user” or an “Email group” action. If it doesn't have one, skip to the next trigger or automation.
6. If one of the actions is present, check whether the action's email body contains one or more of the comment placeholders listed in Original comment placeholders to replace. If it has one, add the trigger or automation to your update list.

Using the API to find triggers and automations to update

You can use the List Active Triggers and List Active Automations endpoints to get all the active triggers and automations in your account. You can then filter the list for the ones that match all the update criteria.

The equivalent update criteria for the API responses are as follows:

Admin Center criteria	Equivalent criteria for the API
The trigger or automation is active	The active property of the trigger or automation is true
The trigger or automation has an “Email user” or an “Email group” action	The field property of an action object is "notification_user" or "notification_group"
The email body of the action contains one or more of the original comment placeholders	The third element of the value array in the action object contains one or more of the placeholders listed in Original comment placeholders to replace

Example trigger:

Original comment placeholders to replace

If the email body of an “Email user” or an “Email group” action contains any of the following placeholders, add the trigger or automation to your update list.

• {{ticket.comments}}
• {{ticket.latest_comment}}
• {{ticket.comments_formatted}}
• {{ticket.latest_comment_formatted}}
• {{ticket.latest_comment_rich}}
• {{ticket.public_comments}}
• {{ticket.latest_public_comment}}
• {{ticket.public_comments_formatted}}
• {{ticket.latest_public_comment_formatted}}
• {{ticket.latest_public_comment_rich}}

Default triggers and automations to update

This section lists the triggers and automations that might need to be updated to support simplified email threading. They might not all be active in your account. You only need to update the active ones. If you decide to activate a deactivated trigger or automation on this list later, remember to also update it for simplified email threading as described in Updating the triggers and automations.

The following default triggers meet the criteria to be updated:

• Notify requester and CCs of comment update: Sends the requester and CCs an updated email message when a public comment is added to the ticket.
• Notify assignee of comment update: Sends the agent assigned to a ticket an email notification when a comment is added to the ticket.
• Notify assignee of assignment: Sends an agent an email notification when the agent is assigned a ticket.
• Notify assignee of reopened ticket: Sends the agent assigned to a ticket an email notification when the ticket is reopened.
• Notify all agents of received request: Sends all agents an email notification when the ticket is received.
• Notify group of assignment: Sends all agents in a group an email notification when a ticket is assigned to the group.
• Notify requester of new proactive ticket: Sends the requester an email notification when a proactive ticket is created by an agent on behalf of the requester.

The following default automations meet the criteria to be updated:

• Pending notification 24 hours: Sends the requester an email message that their request has been pending for 24 hours and awaits their feedback.
• Pending notification 5 days: Sends the requester an email message that their request has been pending for 5 days and awaits their feedback.

Updating the triggers and automations

Updating the triggers and automations consists of replacing all the content of the action's email body with one of the following placeholders for simplified threading:

• {{ticket.latest_comment_html}}

• {{ticket.latest_public_comment_html}}

To determine which one, see Simplified threading placeholder map.

Zendesk recommends updating all the triggers and automations that contain any of the original comment placeholders. Updating only some of them may give unexpected results in email applications.

Before you start, make sure you create a list of triggers and automations that need to be updated. See Listing the triggers and automations to update.

To update a trigger or automation

1. Open the Triggers or Automations page in Admin Center.
   • Triggers: In Admin Center, click Objects and rules in the sidebar, then select Business rules > Triggers.
   • Automations: In Admin Center, click Objects and rules in the sidebar, then select Business rules > Automations.
2. Clone the first trigger or automation on your update list.

   

   The clone is not created yet. You can edit it before creating it.

3. In the cloned trigger or automation, replace "(copy)" in the name with "(simplified)" or something else that makes sense to your use case.
4. In the "Email user" or "Email group" action in the Actions section of the clone, replace all the content in the email body, including any original comment placeholder, with the simplified threading placeholder specified in the Simplified threading placeholder map.

   In the following example, the email body of the "Email user" action contains some text and the original {{ticket.comments_formatted}} placeholder:

   

   The Simplified threading placeholder map specifies that the simplified threading placeholder for {{ticket.comments_formatted}} is {{ticket.latest_comment_html}}. Make the change in the email body by replacing all the content in the body with the single placeholder:

   

5. After making the changes, click Create to create the clone.

   Clones are activated by default.

6. Immediately deactivate the cloned trigger or automation to prevent duplicate emails.

   Click the options menu icon () and select Deactivate.

   

7. Make the same changes to the next trigger or automation on your update list.

Simplified threading placeholder map

Replace each comment-rendering placeholder with either the {{ticket.latest_comment_html}} or {{ticket.latest_public_comment_html}} placeholder depending on the existing placeholder. Use the following map to determine the correct simplified threading placeholder:

Existing placeholder	Simplified threading placeholder
{{ticket.comments}}	{{ticket.latest_comment_html}}
{{ticket.latest_comment}}
{{ticket.comments_formatted}}
{{ticket.latest_comment_formatted}}
{{ticket.latest_comment_rich}}
{{ticket.public_comments}}	{{ticket.latest_public_comment_html}}
{{ticket.latest_public_comment}}
{{ticket.public_comments_formatted}}
{{ticket.latest_public_comment_formatted}}
{{ticket.latest_public_comment_rich}}

The simplified threading placeholders work as follows:

• {{ticket.latest_comment_html}}: For agents, the placeholder renders only the last comment (public or private). For end users, it renders only the last public comment. The comment includes attachments.
• {{ticket.latest_public_comment_html}}: For both agents and end users, the placeholder renders the latest public comment. The comment also includes attachments.

Updating the email templates

To implement the enhanced email experience in your account, you also need to update the following two email templates used to create messages for email applications:

• The follower template or the CC template, depending on your account settings
• The account-level HTML and plain-text email templates

Back up your email templates by pasting them in text files and saving the files. If you later decide to go back to the original email experience, you can restore the original templates from the backup files.

Updating the follower template or the CC template

Updating the follower or CC template consists of replacing original comment placeholders in the template with one of the two simplified threading placeholders listed in the Simplified threading placeholder map.

You have either the follower template or the CC template depending on your account settings. If the CCs & Followers experience is enabled in your account, you have the follower template. Otherwise, you have the CC template.

To update either the follower template or the CC template

1. In Admin Center, click Objects and rules in the sidebar, then select Tickets > Settings.
2. Scroll to either the "CCs and Followers" or the "CC" settings.
3. Copy the content of either the Follower email template or CC email text field and paste it in a separate text file and save it.

   

   You can use this backup file to restore the template later.

4. In either the Follower email template or CC email text field, replace any original comment placeholder in the content with the corresponding simplified threading placeholder in the Simplified threading placeholder map.

   

5. Click Save tab.

Replacing the account-level email templates

The last step is to replace the two account-level email templates. One template is for displaying email content in HTML and the other is for displaying the content in plain text. The new HTML template introduces font changes and removes unnecessary padding.

To replace the account-level email templates

1. In Admin Center, click Channels in the sidebar, then select Talk and email > Email.
2. Scroll down to the Email templates section.
3. Replace the HTML content of the HTML template field with the content below.

   The content below doesn't include an email delimiter placeholder (the delimiter is disabled by default). If you enabled email delimiters in your Zendesk account, you must add the delimiter placeholder to the email template.

   <!DOCTYPE html>
   <html dir="auto">
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
     <style type="text/css">
       table td {
         border-collapse: collapse;
       }
       {{styles}}
     </style>
   </head>
   <body {{attributes}} style="width: 100%!important; margin: 0; padding: 0;">
     <div style="font-family: 'system-ui','-apple-system','BlinkMacSystemFont','Segoe UI','Roboto','Oxygen-Sans','Ubuntu','Cantarell','Helvetica Neue','Arial','sans-serif'; font-size: 14px; line-height: 1.5; color:#444444;">
       {{content}}
     </div><br/>
     <div style="font-family: 'system-ui','-apple-system','BlinkMacSystemFont','Segoe UI','Roboto','Oxygen-Sans','Ubuntu','Cantarell','Helvetica Neue','Arial','sans-serif'; font-size: 12px; line-height: 1.5; color: #aaaaaa; margin: 10px 0 14px 0; padding-top: 10px;">
       {{footer}} {{footer_link}}
     </div><br/>
     {{quoted_content}}
   </body>
   </html>

4. Customize the template as desired.

   For details, see Customizing your templates for email notifications.

   The replacement template is HTML5 compliant. To learn more about supported HTML5 elements, see the HTML5 Elements Reference on www.w3docs.com.
5. Scroll down to Text template, copy the content into your backup file, and replace the content with the following placeholders:

   {{content}}
   
   {{footer}}
   
   {{quoted_content}}

   See Understanding the system placeholders.

6. Click Save.

Restoring the original email experience

This section assumes you created clones of the original triggers and automations, and backups of the original templates.

To restore the original email experience

1. Restore the original email triggers and automations by activating the originals and deactivating the clones.
2. Restore the original follower or original CC template from the backup file.
3. Restore the original account-level email templates from the backup file.

   Avoid using the Revert to default link for each template. This will revert the template to the one used for simplified email threading.