Pro features are power functions which are an incentive for users to regularly support
the SmartTemplates project through an annual contribution, called SmartTemplates Pro / SmartTemplates Standard license.
My aim is that instead of very few people trying to carry the project with sometimes large
donations to try involving more supporters. It is a lot of work to keep the project
going and up to date with all the latest code changes which happen every four(!) weeks on the Mozilla code base.
Staying in sync with the complex Thunderbird application and to support
multiple OS platforms (Windows, Linux and Mac) and 19 languages,
writing support emails and fixing bugs is actually a big amount of work.
I would rather actually spend more time on this than just burning away my weekends, but for this it
needs to be financially viable.
SmartTemplates is completely funded by its users, mainly through the various licenses available
at fastspring.com - to find out our current prices click one of the links below:
What Pro Features exist?
Here is a list of Pro features that are unrestricted to licensed users.
For non-licensed users, the Pro features can be restricted and, when used, will show a notification bar
in order to promote buying a license. I feel this is the best way as it gives you a chance to try them out and
get an idea on what other great future functionality will be funded by supporters:
Feature Comparison
Insert Snippets in Composer
While writing emails, use the insert Snippet button to inject a section of html at the cursor position.
In the Pro version of SmartTemplates this menu has no restrictions and can be subdivided in as many categories as you like:
SmartTempaltes Pro only: You can use the placeholder text *selection*
to insert
the currently highlighted text in the Email. This can be used to wrap / decorate text or build other
HTML containers around information you have already inserted in the Email.
Text Manipulation
%deleteText("text")%
= Remove some text from the Quote Header, such as deleteText("via Paypal")- "John via Paypal wrote" => "John wrote"
%replaceText("find","replace")%
= Replace some text with something else (similar to deleteText).
%replaceText(regularExpression,clipboard)%
= (new in v3.12) overwrite placeholder text in template from clipboard
%matchTextFromBody("Regular Expression",MatchGroup)%
=
Finds a pattern in quoted Email and insert at function location.
E.g. %matchTextFromBody("Delivery from ([-'a-zA-Z\u00C0-\u024F]*\s[-'a-zA-Z\u00C0-\u024F]*)",1)%
will retrieve 'John Doe' from the line 'Delivery from John Doe' - (included unicode characters for diacritics)
%matchTextFromSubject("Regular Expression",MatchGroup)%
=
Finds a pattern in subject and insert at function location.
E.g. %matchTextFromSubject("\b[a-zA-Z0-9._+-]+@[a-z0-9.-]+\.[a-z]{2,4}\b",0)%
will retrieve an Email address from the Subject line
Note: the new %matchTextFromBody%
and %matchTextFromSubject%
functions
use regular expressions - these are powerful keys for finding text patterns.
The first parameter must be the regular expression within double quotes. The second parameter is a number which denotes the "match group".
Match groups are usually designated with round parentheses (). Use 0 to match the complete expression, 1 for the first group etc.
To learn about regular expressions, please visit: www.regular-expressions.info.
For testing your patterns, I recommend this online tester: regex101.com
Quote Modification
[issue 31]
From SmartTemplates 2.8: New variables to remove text / tags from quoted parts
and save space.
-
%deleteQuotedText("searchText",quoteLevel)%
Deletes quoted Text
%replaceQuotedText("searchText","replacementHTML",quoteLevel)%
Replaces quoted text
%replaceQuotedText(regularExpression,clipboard)%
(new in v3.12) replace text patterns in the quoted part with clipboard contents.
%deleteQuotedTags("selector",quoteLevel,minSize)%
Deletes tags from the quote.
%replaceQuotedTags("selector","replacementHTML",quoteLevel,minSize)%
Deletes tags from the quote
searchText - must be in double quotes - the searchText argument must be a regular expression.
Note that whitespace can be best represented as \s because it can also contain line breaks.
Double quote characters cannot be used.
replacementHTML - must be in double quotes - text or a html tag which will be inserted in page.
To use a Comma within the string parameter, prefix it with a
backslash like this: \,
- see
[issue 280]
quoteLevel - optional, (number) which minimal quote level to start from
selector - what you would use to address the tag in css. simplest case "img", or "p" but attribute selectors
can be added as long as double quotes can be avoided.
minSize - (optional, numeric) - number of kByte, minimum size for removing the tag. This way you can
keep smaller images like icons / emojis while discarding large images.
A note on quoteLevel, for images I would recommend 2 if you want to
remove images to retain some context in your replies. This will dramatically decrease email
sizes in long threads which contain a lot of images (e.g. screenshots).
Update - from version 3.11 of SmartTemplates the above commands can also be used to remove text from the
forwarded email (as long as it is forwarded inline). Use quoteLevel = 0 for this to work:
%deleteQuotedText("searchText",0)%
.
Forwarded Mail Content
The command %deleteForwardedBody%
removes the content of the original email when
forwarding it inline (not as attachment). This feature can be used to first process information from automated
mails (with text manipulation and header
functions of the type %header.*.matchFromBody%
) while removing the original information.
[issue 236]
Advanced Date Functions
%dateformat%
function for inserting / updating current time.
[Bug 26588]
The format variables are taken from the regular formats such as %Y% for 4-digit
Years, with the % symbols stripped. Use as follows:
%dateformat(formatString)%
Supported Formats:
Y, y, n, m, e, d, k, H, l, I, M, S, tz_name, B, b, A, a, p1, p2, p
Examples:
%dateformat(A, e/n/Y, H:M)%
creates: Wednesday, 23/02/2018, 14:23
%X:=calculated()%
Switch for modifying date & time displayed. [Bug 26307]
%X:=calculated(d,h:mm)%
where d = is the number of days to add. h = number of hours and mm number of minutes.
Note this needs to be reset using
%X:=calculated(0)%
to reset it for the rest of the Email.
Wrap the format strings in double quotes, and add the parameter toclipboard to force copying
the date to clipboard instead of inserting it into the email. Use the additional
parameter current to always enforce current time (without that, it will
interpret it as the timestamp of the replied to / forwarded original mail) - easier
than having to insert the cumbersome %x:=today%
at the start of the line.
%dateformat("A, e/n/Y H:M",toclipboard)%
%dateformat("A, e/n/Y H:M",current,toclipboard)%
Clipboard Support
Copy Text Data to Clipboard
%toclipboard("some text")%
Copies the literal text within the quotation marks to clipboard.
You can use the clipboard as a placeholder variable to hold data for
the commands following below.
Imporant - to include commas, they need to be escaped with a backslash like this:
\,
.
Insert Data from Clipboard
%clipboard%
Use this simple command to insert clipboard contents directly into the template.
SmartTemplates Pro now supports using "clipboard" as argument for text and header manipulation functions:
header manipulation - examples
%header.set(to,clipboard)%
- set the final recipient from the clipboard
%header.append(to,clipboard)%
- add a recipient from clipboard
%header.prefix(subject,clipboard)%
- add some subject prefix from clipboard
Template text and Quote replacements
%replaceText(regularExpression,clipboard)%
- overwrite placeholder text in template from clipboard
%replaceQuotedText(regularExpression,clipboard)%
- replace text in the quoted part
Copy Variable Results to Clipboard
[issue 187]
SmartTemplates Pro: Support transferring headers / variable results to clipboard
Use the parameter toclipboard to transfer header contents such as email addresses to
the clipboard: %from(mail,toclipboard)%
Use it when replying or forwarding messages to extract text from the original message
body or subject to the clipboard, for example:
%matchTextFromBody("Please reply until (.*)",1,toclipboard)%
%matchTextFromSubject("\[Support\] (.*)",1,toclipboard)%
You can use it for copying the date with dateformat as well:
Wrap the format strings in double quotes, and add the parameter toclipboard to force copying
the date to clipboard instead of inserting it into the email. Use the additional
parameter current to always enforce current time (without that, it will
interpret it as the timestamp of the replied to / forwarded original mail) - easier
than having to insert the cumbersome %x:=today%
at the start of the line.
Examples:
%dateformat("A, e/n/Y H:M",toclipboard)%
%dateformat("A, e/n/Y H:M",current,toclipboard)%
A valid SmartTemplates Pro License is required for this feature to work.
CardBook Support
This uses data from the CardBook address book for all address fields.
You need to install
Cardbook 84.6 or higher to retrieve the addresses from it.
Enable this feature on the advanced settings page:
I also added platform switches to chatname, which select a specific
chat name based on the what it is for, such as %from(chatname.skype)%
You can find all currently supported switches on the variables page under
the section 'Address Book Fields' and can be combined with all address-related
variables such as %to%
, %from%
, %cc%
, %recipient%
or %identity%
.
Mail Header Manipulation
%header.set(hdr,"text")%
= Set the header hdr (eg. to, from, subject) with the text.
%header.set(subject,"text")%
= Replace complete subject with the text
%header.set(to,clipboard)%
= (new in v3.12) set the final recipient from the clipboard.
%header.prefix(subject,"text")%
= Prefix subject with the text
%header.append(subject,"text")%
= Append text to subject
%header.delete(subject,"text")%
= Delete text from subject
The following functions are using Regular Expressions (search patterns) - these are for
advanced users only but can give you great rewards in automating emails. More info below.
%header.set.matchFromSubject(hdr,regex,group)%
= Set the header if a matching regular expression is found in subject line.
%header.append.matchFromSubject(hdr,regex,group)%
= Append text to header / recipient if a matching regular expression is found in subject line.
%header.prefix.matchFromSubject(hdr,regex,group)%
= Prefix text to header if a matching regular expression is found in subject line.
%header.set.matchFromBody(hdr,regex,group)%
= Set the header if a matching regular expression is found in quoted email.
%header.append.matchFromBody(hdr,regex,group)%
= Append text to header / recipient if a matching regular expression is found in quoted email.
%header.prefix.matchFromBody(hdr,regex,group)%
= Prefix text to header if a matching regular expression is found in quoted email.
The hdr parameter represents a mail header that has textual content, such as (to, from, subject).
This cannot be used for headers containing dates such as the sent time.
The regex parameter is a search pattern in the form of a regular expression;
for more documentation, please check the site
Regular-expressions.info.
There is also a useful regular expressions tester
for trying out your search patterns. For best results, make sure to switch the "Flavor"
field to ECMAScript (JavaScript).
The group parameter is the number of the matched expression, for an explanation
see here.
Usually setting this to 1 will do what is needed most of the time
(replaces first found expression with first match).
Additionally, you can now use the matchFromSubject and matchFromBody functions in the following way:
%header.set.matchFromBody(hdr,regex,"replacement text")%
The main difference is that match group is a number - which will insert / set / append
The matched text found during the search, whereas replacement text is a text that is used
instead if the search pattern is found. For usage simply add the double quotation marks around the 3rd parameter.
Examples
To learn about regular expressions, please visit: www.regular-expressions.info.
For testing your patterns, I recommend this online tester: regex101.com
%header.set(to,"abc@de.com")%
= Replace recipient with email address
%header.append(to,"abc@de.com")%
= Add email to recipient list
%header.set.matchFromSubject(to,"Donation from .* \((\b[a-zA-Z0-9._+-]+@[a-z0-9.-]+\.[a-z]{2,4}\b)\)",1)%
Looks for a pattern "Donation from Name (email)" and extracts email address to set the recipient (to) header.
.* is a group of any arbitrary character(s) in order to omit the Name portion of the email address
\( and \) match the parentheses,
\b means the result of the match group (...) starts at the beginning of the email address and ends before the closing parenthesis.
[a-zA-Z0-9._+-]+@[a-z0-9.-]+\.[a-z]{2,4} is a standard email matching expression.
1 - means the result from the first match group (...) is used for setting the header.
Files and Images
-
%file(filePath,encoding)%
= Include HTML or plain text file. When omitting the encoding
parameter, SmartTemplates will assume UTF-8. If the file contains more SmartTemplates
variables such as %from%
, these will be resolved.
-
%file(imagePath,altText)%
= Inserts an image file (png,jpg,gif,bmp,svg).
The optional altText is displayed if the image can't be found.
For the correct file path syntax, click the
%file%
label in the Variables tab in the SmartTemplates settings window.
This will open a standard file prompt and then insert the correct code into the template.
Filter for automatic Forwarding / Replying
Auto-Forward / Auto-Replying Emails with smart template - this requires the Add-on FiltaQuilla
version 3.4 or later.
To enable this feature, you must first open FiltaQuilla settings on the Actions tab:
Next you can create new message filters, activate either Forward or Reply with Smart Template.
Then create a new message filter from the tools menu; in action select "Forward with SmartTemplate"
and push the open file button to select an external template file:
When forwarding files, you can use %header.set(to)%
and %header.append(to)%
to populate
the recipients (address book groups should also work) or %header.set(bcc)%
for undisclosed recipients.
The command %suppressQuoteHeaders%
will now remove all quote headers - the ones inserted
by Thunderbird automatically and the ones that may be configured in SmartTemplates account settings.
You can also use %sig(none)%
to suppress inserting any signatures.
Preview texts for mobile Email clients
This feature was added in SmartTemplates Pro 4.4.
Added %preheader()%
variable for injecting preview text for mobile email clients.
See also [issue 274]
You can add a short text only sentence that describes the content of your email.
If you need to add commas within the "text", you have to escape them with a preceding
backwards slash, like this:
%preheader("I love vanilla ice cream\, but my brother prefers chocolate.")%
You can also insert the contents of the clipboard within the text
Usage:
%preheader("text content")%
%preheader("text content",className)%
%preheader("text content","inline rules")%
%preheader("text content",className,"inline rules")%
%preheader("Some text - *clipboard*")%
%preheader(clipboard)%
Insert Mail Tags
The SmartTemplates Pro variable %tags%
can insert the mail tags of the replied /
forwarded mail into the email text. Please note that tags are specific
to the mail client and cannot be "sent" to another recipient.
To try out, get the Latest version: [issue 320]
Usage
%tags%
%tags(optional parameters)%
Optional parameters
A comma delimited list of parameters can be added to change the behavior:
color - a preset with a colorful label
(using the color of the label for font and border)
color-filled - another preset with a colored label
(using the color of the label for background, with white font)
filled - tags with white font, filled with dark color
dark-filled - tags with black font, filled with white color
- useful for dark backgrounds.
size=fontSizeValue - font size, fontSizeValue is either a
simple decimal numeric value such as 0.8, 1.0, 1.2 etc. and will be multiplied with the
standard size unit of 1em, or a full value of number+unit, eg 100px, 0.6em, 14pt etc.
delimiter="delimitString" - delimitString
= what to put in between the tags. Commas within here need to be prefixed with a backslash like this: \,.
If this is not given as parameters it defaults to , (a single comma followed by a single space)
format="formatString" custom html snippet to format every tag.
toclipboard copies the result to the clipboard instead of inserting it
uppercase - converts label texts to uppercase
lowercase - convert label texts to lowercase
capitalize - capitalizes all label texts to (first letter of each word
in uppercase, the rest in lowercase)
camelcase - only converts the first letter to lowercase,
leaves any internal mixed case intact.
Examples
Similar to address fields, %tags%
also supports using the double square bracket Syntax:
This will hide the contents of the complete contents of the line if no tags are retrieved from the email.
[[ %tags% <br>]]
[[ %tags(color)% <br>]]
[[ %tags(color-filled,uppercase,delimiter=" ",size=1.1)% <br>]]
[[ %tags(filled,lowercase,delimiter=" - ")% <br>]]
formatString
This is designed as either plain text or html snippet and can contain single
or multiple instances of the placeholders $label$
and $color$.
Make sure to enclose it in double quotes and prefix any commas within with a backslash: \,:
$label$ placeholder for the tag text
$color$ 6 digit hex value of the mail tag's color
%tags% |
Important, To Do, all new Taggy, Custom-1 |
%tags(color)% |
Important,
To
Do,
all
new Taggy, Custom-1 |
%tags(color-filled,uppercase,delimiter=" ",size=1.1)% |
IMPORTANT
TO
DO ALL
NEW TAGGY CUSTOM-1 |
%tags(filled,lowercase,delimiter=" - ")% |
important
- to
do -
all
new taggy - custom-1 |
%tags(dark-filled)% |
Important,
To
Do,
all
new Taggy,
Custom-1
|
%tags(format="<span style='background-color:$color$; color:white; border-radius:0.7em; padding-inline:1em'> ↦$label$ </span>")% |
↦Important,
↦To
Do, ↦all
new Taggy, ↦Custom-1 |
Running "sandboxed" JavaScript
To do more flexible things with SmartTemplates a user (Benito van der Zanders) once
contributed a JavaScript
feature - this is able to run some user supplied script in order
to insert SmartTemplates variables in a flexible manner. While I cannot guarantee
that this is going to work forever, it has come in handy for some advanced users.
Please note that Thunderbird may have some problems with certain commands being
executed by a script invoked by a user / Add-on, so I give no guarantees for this functionality.
You can currently use it as follows:
Enable the Thunderbird config setting extensions.smartTemplate4.allowScripts=true
and extensions.smartTemplate4.sandbox=true.
Then add a code section in between the following SmartTemplates "code brackets"
%{%
and %}%
.
You need to define an anonymous function that must always return a string - this will then be inserted
into the email.
E.g.:
%{%
(function() {
var date = new Date();
const hours = date.getHours();
if (hours < 12) { return "Good morning"; }
if (hours < 17) { return "Good afternoon"; }
return "Good evening";
} )()
%}%
The syntax (function { functionBody }() )
defines an
anonymous function and then calls it directly using the '()' Syntax.
You can also use the more modern Lambda expression
Syntax: (() => { functionBody }() )
You can use SmartTemplates variables (without the % signs) within code,
they should be replaced within the function like a variable would in your HTML template.
If the parameters of a variable contain keywords such as %from(firstname,mail,lowercase)%
they need to be enclosed in double quotes, to avoid the JavaScript throwing errors:
from("firstname,mail,lowercase")
.
However since Thunderbird 115, the any %variable%
functions now run asynchronously,
which means they do not return a value but a "Promise". This is ok if the script
block returns it directly, for example like this:
(function() {
return from("name,capitalize,bracketMail");
} )()
Usually you need to read the variable string result within the script in which case
you need to use the keyword await
and also need to to declare the function as asynchronous:
Example 1: load hardcoded test / a different template depending on who you reply
%{%
(async () => {
let mysender = await from("mail");
switch(mysender) {
case "thunderbirddaily@gmail.com":
return "<p>Special text for thunderbirddaily.</p>"
+ "<p>Another paragraph!</p>";
case "axel@gmail.com":
return await file("W:\\User\\axel\\stationery\\QuickFolders - Links (English).html");
default:
return "<p>default case!</p>";
}
})()
%}%
Here the keywords file
and from('mail')
are replaced in the script with the SmartTemplates
variables %file(path)%
and %from(mail)%
and then resolved by SmartTemplates.
Notes: backslashes in strings need to be escaped: "\\"
Keywords / unquoted parts within smartTemplate functions like %from()%
, such as
mail, firstname, toclipboard etc. should be wrapped in quotes
- otherwise the script parser will think they are undefined variables and return an error.
For example: %from(firstname,email)%
must become await from("firstname,email")
Example 2: Greeting based on time of day
%{%
( () => {
var date = new Date();
if (date.getHours() < 12) {return "Good morning";}
else { return "Good afternoon"; }
} )() %}%
Example 3: Reading email from clipboard and reacting accordingly
In the next example, the template will insert content based on whether an email
address is found in the clipboard. If no email is found the sender's
address is used instead. This function both reads the clipboard and writes
to it in order to communicated between different code blocks.
Important: if you use %clipboard%
outside of code blocks
(in the template text itself) it may not be executed in the same
order as the code blocks. I think code blocks are generally executed / replaced
first before the rest of the template is processed.
Please note that I am currently working on the syntactically problem of making await
work with smarttemplates variables that have no parameter, by using the syntax await smartVar()
.
Please see [issue 329]
to see progress on this and download trial versions.
%{%
(async () => {
var val = await clipboard("text");
if (val && val.includes("@")) {
console.log("Clipboard has email address")
return "";
}
console.log("no email in Clipboard:", val);
await from("mail,toclipboard");
console.log(`Copied from address to clipboard`);
return "";
})()
%}%
%{%
(async () => {
var val = await clipboard("text");
switch(val) {
case 'joe@domain.com':
return "<p>Hello Joe!</p>";
case 'customer@somedomain.com':
return await file('N:\\stationery\\Support_Template.html');
default:
return `<p>Dear ${val}</p>`;
}
})()
%}%
Other Benefits of having a Yearly License
You know that you support the project and that the development and support will be continue.
There is a huge amount of work involved not just programming and keeping SmartTemplates up to date
but also supporting users, coming up with better ways of doing things, fixing bugs, and keeping
SmartTemplates usable across various platforms and host programs (at the moment I support Thunderbird,
SeaMonkey and Postbox). I am constantly helping people with using SmartTemplates and their mail program
and how to get the most out of email on the desktop.
All notification messages that indicate Pro features are omitted.
The donation screen (which is normally shown after every Update) is hidden.
Alternative Monetisation Models
There are quite a few software developers (and also some users) who believe
that software should generally financed by advertisement or even by selling
information about their users.
I am firmly opposed to this way of making money as it impacts
both productivity and privacy rights; also in the world of Email I would
find this way of generating value deeply problematic - even if it was
strictly opt-in. There is a lot of personal information in our daily mail
and a lot of knowledge that is being stored and retrieved with this powerful
tool.
One of the reasons for a personal Email Client on the desktop
is the fact that we can store our data on our personal hardware and use it
any way we like. On the other hand, if we use a web mail client (like gmail)
we can never be sure whether the information is used otherwise and whether
we get targeted with distracting information (be it by injecting advertisements or via
targeted advertisement emails) - it is one of the goals of any mail desktop client
to eliminiate these distractions as much as possible, and focus on one thing only:
managing communication.
SmartTemplates is an especially powerful set of tools to harness this
information and it will evolve and keep saving time and make your experience
of mail more meaningful and intuitive.