Customers raised an important issue with the product's system emails (e.g., user welcome, password reset, etc.) Though administrators could add minimal branding, their end users were confused by emails and often reported them as phishing. Users did not have name recognition of JumpCloud and would ignore emails for password resets or device lockouts. To solve this issue of end user trust, my team built tools to customize the content of key system emails, allowing administrators to customize the message and look so end users could better identify emails and trust the content.
I collaborated with a designer on the UX and built the UI, while my teammates built a new endpoint and updated the email build process to accommodate custom emails.
Design & Constraints
We conducted research with customers to get feedback on three design concepts including:
- separate inputs for each piece of customizable part of the email
- a rich text editor to write the whole email
- an advanced editor that allowed writing custom HTML code
Customers liked the flexibility of the rich text editor, but also appreciated the simplicity of individual fields. Customers agreed that hand editing HTML was a lot to expect, especially without a good way to test emails.
We discovered that sending a sample email on demand was not feasible with our email backend service. As an alternative, I suggested a live preview that would give a sense of how the email would look. Though the preview couldn't leverage the production CSS or email templates, we could align it as closely as possible.
Because the existing email templates required specific pieces of content in partials or styled elements, a rich text editor solution was unfeasible. For example, there are elements like call to action buttons that are partials that the user cannot customize. Given cross email client rendering issues rich text editing seemed risky absent an on-demand preview email. Finally, requiring IT administrators to debug cross email client issues is not user friendly. We solved these issues by separating the email into sections that the administrator can customize via inputs in the UI.
The existing system emails used variables, including organizational information like administrator contact email, as well as email specific data like the expiration date of a user's password. These were important pieces of information for end users and could not be sacrificed.
Solution
The interface has two panes. In the left editing pane, administrators choose a template. The form inputs are dynamically generated from the fields available in the template. The right panel updates to display a preview of the email in real time.
To solve for variables in emails, we developed a set of tokens. Tokens are entered in the format #{expiration_day} and highlighted in the preview with a dotted underline. Invalid tokens display as plain text.
The administrator can preview tokens via a toggle switch. Tokens that are organization specific, like organization name or administrator contact email, are real data. Email or user specific tokens, like a password expiration date or username, are previewed with mock data. Each token has a description in a tooltip to provide context while editing.
The token preview and tooltip posed a technical challenge. For the preview styling and tooltip, I had to render a custom Vue component in place of the token text. I wrote a function that deconstructed the text into an array, using regex to split the string at tokens. Tokens are validated against a list of possible tokens provided by the API, so only valid tokens are rendered with the preview style. Finally the component renders plain text in spans and valid tokens render as a Vue component.
During development, internal users struggled to fully understand tokens. It seemed reasonable that administrators would have similar issues. Providing documentation in a knowledge base article was too removed from the task, so I designed and implemented a documentation tool that lives at the bottom of the page. The tool includes a list of tokens with a description and a preview value for each. The preview is important for tokens that don't render as simple text. For example, #{admin_email_link} renders a mailto: link with the administrator name as the text. Where relevant, the tool also provides a link to the setting where the token value can be updated.
