Creating email templates

An email template is a document that works with a notification to send an email, for example as a result of a positive detection in a detection rule. Jinja template fields allow the email template to have dynamic values that change based on variables such as events involved in a positive detection. (After you learn about creating email templates, learn how to use Jinja template fields.)

The email template provides the text that the recipient sees when they get an email from the notification. You can find email templates in your Library in the Templates folder.

When you write an email template to go with a notification, make sure that the template fields in each item match.

How do the notification and email template work together?

TeskaLabs ASAB Iris is a message-sending microservice that pairs the notification and the email template to send emails with populated placeholder fields.

Creating an email template

Create a new blank email template

1. In the Library, click Templates, then click Email.
2. To the right, click Create new item in Email.
3. Name your template, choose the file type, and click Create. If the new item doesn't appear immediately, refresh the page.
4. Now, you can write the template.

Copy an existing email template

1. In the Library, click Templates, then click Email.
2. Click on the existing template you'd like to copy. The copy you create will be placed in the same folder as the original.
3. Click the icon at the top of the screen, and click Copy.
4. Rename the file, choose the file type, and click Copy. If the new item doesn't appear immediately, refresh the page.
5. Click Edit to make changes, and click Save to save your changes.

To exit editing mode, save by clicking Save or cancel by clicking Cancel.

Writing an email template

You can write email templates in Markdown or in HTML. Markdown is less complex, but HTML gives you more formatting options.

When you write the text, make sure to tell the recipient:

• Who the email is from
• Why they are receiving this email
• What the email/alert means
• How to investigate or follow up on the problem - include all of the relevant and useful information, such as log IDs or direct links to view selected logs

Simple template example using Markdown:

SUBJECT: {{ name }}

TeskaLabs LogMan.io has identified a noteworthy event in your IT infrastructure which might require your immediate attention.
Please review following summary of the event:

Event: {{name}}

Event description: {{description}}

This notification has been created based on the original log/logs:  

{% for event in events %}
- {{event}}
{% endfor %}

The notification was generated for this address: {{address}}

We encourage you to review this incident promptly to determine the next appropriate course of action.

Remember, the effectiveness of any security program lies in a swift response.
Thank you for your attention to this matter.

Stay safe,

TeskaLabs LogMan.io

Made with <3 by [TeskaLabs](https://teskalabs.com)

The words in double braces (such as {{address}}) are template fields, or placeholders. These are the Jinja template fields that pull information from the notification section in a detection rule. Learn about Jinja templates here.

Testing an email template

You can test an email template using the Test template feature. Testing an email template means sending a real email to see if the format and fields are displaying correctly. This test does not interact with the detection rule at all.

Fill out the From, To, CC, BCC, and Subject fields the same way you would for any email (but it's best practice to send the email to yourself). You must always fill in, at minimum, the From and To fields.

Test parameters

You can populate the Jinja template fields for testing purposes using the Parameters tool. Write the parameters in JSON. JSON uses keys-value pairs. Keys are the fields in the template, and values are what populate the fields.

In this example, the keys and values are highlighted to show that the keys in Parameters need to match the fields in the template, and the values will populate the fields in the resulting email:

Parameters has two editing modes: the text editor and the clickable JSON editor. To switch between modes, click the <···> or icon beside Parameters. You can switch between modes without losing your work.

Clickable editor

To switch to the clickable JSON editor, click the <···> icon beside Parameters. The clickable editor formats your parameters for you and tells you the value type for each item.

How to use the clickable editor:

In the clickable editor, edit, delete, and add icons appear when you hover over lines and items.

1. Add a key: When you hover over the top line (it says the number of keys you have, for example 0 items), a icon appears. To add a parameter, click the icon. It prompts you for the key name. Type the key name (the field name you want to test) and click the to save. Don't use quotation marks - the editor adds the quotation marks for you. The key name appears with the value NULL beside it.

2. Add a value: To edit the value, click the icon that appears when you hover beside NULL. Type the value (what you want to appear in place of the field/placeholder in the email you send), and save by clicking the icon.

3. To add more key-value pairs, click on the that appears when you hover over the top line.

4. To delete an item, click the that appears when you hover over the item. To edit an item, click the that appears when you hover over the item.

Text editor

To switch to the text editor, click the icon beside Parameters.

Example of parameter formatting:

{
    "name":"Detection rule 1",
    "description":"Description of Detection rule 1",
    "events":["log-ID-1", "log-ID-2", "log-ID-3"],
    "address":"Example address"
}

Quick JSON tips

• Begin and end the parameters with braces (curly brackets) {}
• Write every item, both keys and values, in quotation marks ""
• Link keys to their values with a colon : (for example: "key":"value")
• Separate key-value pairs with commas ,. You can also use spaces and line breaks for your own readability - they'll be ignored in terms of function.
• Type arrays in brackets [] and separate items with commas (the key events might have multiple values, as the Jinja for expression allows for, so here it's written as an array)

The testing box tells you if the parameters are not in a valid JSON format.

Switching modes

You can switch modes and continue editing your parameters. The Parameters tool will automatically convert your work for the new mode.

Note about arrays

An array is a list of multiple values. To edit an array value in the clickable editor, you need to type at least two values manually in the text editor in the correct array format (see Quick JSON tips above). Then, you can switch to the clickable editor and add more items to the array.

Sending the test email

When you're ready to test the email, click Send. You should receive the email in the inbox of addressee in the To: field, where you can check the formatting of the template. If you don't see the email, check your spam folder.