ResourcesKnowledge Base

Filters and functions

Filters enable different behaviors in e-mail templates depending on the data entered. Functions are used for content transformation, for example images.

Filters Functions

Plug-ins can be used for other advanced features in the templates.

Filters

dont_send

This filter allows recipients to be skipped when sending. It can be inserted in the template like this: [% recipient.EMAIL | dont_send -%].

For example if you would like to send an email only to women, the condition would be:

[% IF recipient.GENDER !== 'F' -%]
    [% recipient.EMAIL | dont_send -%]
[% END -%]

Another example of use is the case where in the data source, which is processed in the template and the value for each recipient is to be added from it, there is no value for a specific recipient and therefore an email should not be sent to this recipient.

[% benefit = "" -%]
[% FOREACH zaznam IN data.DS_XML_BENEFIT.prijemce -%]
    [% IF zaznam.email == recipient.EMAIL -%]
		[% benefit = zaznam.benefit -%]
	[% END -%]
[% END -%]
[% IF benefit -%]
	Benefit: [% benefit -%]
[% ELSE -%]
	[% recipient.EMAIL | dont_send -%]
[% END -%]

In this case, an XML data source with recipients (with their email address and type of benefit) is attached to the template. If the recipient does not have a benefit, the email will not be sent.

set_subject

You can use this filter to set the subject of the message from the template. It is used like: [% 'subject text' | set_subject -%]. If you'd like to use the subject "Good Morning!" in your campaign and you want to take into account the city saved in the recipient's detail, the entry would look like this:

[% IF recipient.CITY == 'NY' -%]
    [% 'Good Morning New York!' | set_subject -%]
[% ELSIF recipient.CITY == 'LA' -%]
    [% 'Good Morning Los Angeles!' | set_subject -%]
[% ELSE %]
    [% 'Good Morning!' | set_subject -%]
[% END -%]

Then all those recipients who have NY or LA stored in the list of recipients in the field “city” will receive a message with the subject “Good Morning New York!”/“Good Morning Los Angeles!”. Other recipients (who have another city stored in, or have the field "city" empty), will receive a message with the subject "Good Morning!".

uri

This filter can be used when the URL contains non-standard characters which have to be transformed into code, like for the use in the img_cache function. It is used like this:

[% 'https://www.yourdomain.com/images/soufflé.jpg' | uri -%]

The resulting URL will be:
​​​​​​​https%3A%2F%2Fwww.yourdomain.com%2Fimages%2Fsouffl%C3%A9.jpg

MD5

Sometimes it is necessary to transfer data that should not be transfered in the usual form (e.g. e-mail address or other personal data). A typical example might be a situation where you want to find out on your page who clicked on a link in an email, so you add a parameter with the email address to the link URL. In Mailkit you can hash data using MD5 as follows:
 

EMAIL_MD5 variable

In this case, the recipient's email address does not need to use a filter, as Mailkit offers the variable EMAIL_MD5, which is located in the recipient's data structure. Use in a template would look like this:

<a href="https://www.yourdomain.com/page?recipient=[% recipient.EMAIL_MD5 -%]>LINK</a>

Kdyby byla e-mailová adresa příjemce např. jirinovak@mailkit.eu, výsledná URL by byla:
https://www.yourdomain.com/page?recipient=a3248c6295d90147cd61b3d84db03f5d
 

md5_hex

If data other than the email address needs to be hashed, the | md5_hex filter can be used . In case it would be necessary to hash, for example, the content of the CUSTOM1 field from the recipient's detail and use it in the URL, this can be done as follows:

[% USE Digest.MD5 -%]
<a href="https://www.yourdomain.com/page?content=[% recipient.CUSTOM1 | md5_hex -%]>LINK</a>

Functions

img_cache

If you’d like to use images which are too large, on a slow server, or your server just isn’t prepared for an anticipated load, you can use the img_cache function. This function enables image size manipulation, and caches the image on our servers.

It is used as a URL, which takes three parameters (all of which are mandatory):

  • Width in pixels
  • Height in pixels
  • Image URL which has to be URI encoded


Example: If you’d have an 1000×500 px image at https://www.yourdomain.com/images/soufflé.jpg you can transform it into 600×300 px image placed on our servers this way (in this case the URL is already URI encoded):

https://u.mailkit.eu/action,img_cache/width,600/height,300/img_url,https%3A%2F%2Fwww.yourdomain.com%2Fimages%2F
souffl%C3%A9.jpg

Black part is the function, red is width parameter, green is height parameter, and blue part is the parameter of image URL.

Image URL always has to be URI encoded, which means that all the “non-standard” characters are transformed into code. When coding an email template, it’s possible to use​​​​​​​ | uri filter, which will encode the URL:

<img src="https://u.mailkit.eu/action,img_cache/width,600/height,300/img_url,
[% 'https://www.yourdomain.com/images/soufflé.jpg' | uri -%]" />

Image dimensions are changed proportionally (so the image is not deformed), and the dimensions are changed according to the height parameter. So if the 1000×500 px image was scaled down by using width,600/height,100/, the result would be a 200×100 px image.