Mailtraq - the Complete Email Server
   

Enstar for Mailtraq email server sales & support
Making world-class Internet technology affordable  

Search for:

Advanced search

Getting Started with Scripts

This document introduces Mailtraq’s scripting language and discusses how it can be used to provide extensive customisation and automation. Many examples of scripts are also provided.

The following topics are covered:-

· An Introduction to Scripting
· The Scripting Language
· Using Scripts

Mailtraq is a relatively large system, and it is intended to be used in a wide variety of ways (hopefully including many the developers have never considered). To make Mailtraq as flexible as possible, and to be able to adapt it to any situation, a scripting language has been built into it. The scripting language allows you to enhance Mailtraq and integrate it with other applications and systems that you use.

Click here for a complete description of every function supplied with Mailtraq.

What is Scripting?

It may be easier to describe scripting by what it is not. It is not a macro language. Macro languages allow you to make repeated operations more efficient by creating a macro that represents what you would normally do (at the machine’s console), and then having the application repeat it when appropriate. It is also not an application programming language. You cannot build independent applications with scripts.

What you can do with the scripts is use the functions that Mailtraq provides to perform various tasks, access information stored in Mailtraq, and integrate Mailtraq with other applications. You can use scripts in message templates to customise them, and you can use scripts in web-page templates to build web-based applications that execute on the Mailtraq web server.

The scripting language is not as comprehensive as a “real” programming language, but it does at least allow you to link it to code written in such a language when you need functionality not provided within the Mailtraq environment.
 
What do you need to know?

Most people do not have any interest in learning how to program, and you are never forced to use the scripting in Mailtraq. It is simply an option that you may take if necessary. However, if you do find it necessary to use the Mailtraq scripting, but have never programmed before, then you will find the scripting language relatively simple.

If you have used other programming languages, you may find the scripting a little unusual. However, it does follow most of the common rules of programming, and it does provide many of the familiar programming constructs.

The Scripting Language

Functions
At the heart of the scripting language is the function. A function is a repeatable routine that can generate a result, and can be given parameters to compute. What parameters are required, and what value it returns, will depend on the function itself. Functions can, themselves, be parameters to other functions. Unlike many languages, when passing a function as a parameter you are not passing the result of the function, but the function itself. These ‘parameter-functions’ are executed only when a result is needed, and can be repeatedly executed if necessary.

In Mailtraq, functions are identified by textual names, followed immediately by parameters enclosed within parentheses. There should be no space between the name of the function and the opening parenthesis, and even if no parameters are being passed, a pair of parentheses must follow a function name.

Operators
Another important part of the scripting language is the ‘operator’. Operators are actually quite similar to functions, in that they are given parameters and return a result. However, in order to make them easier to read, operators are placed between their parameters instead of prefixing them.

The statement

1 + 2 * 3 / (4 - 5)

shows a number of operators in action.

Variables
The scripting language also includes variables. These are portions of data into which the results of functions and operators can be placed. Mailtraq often also inserts data into predefined variables before scripts are called. Variables do not have to be declared before they are used, they are simply created when first referenced. For example, the statement

x := 1 + 2

results in the variable x holding the value 3. Variables can be used in place of constants anywhere in the scripting language. For example, the statement

y := x * 2

(when following the previous statement) results in the value 6 being stored in the variable y.


Expressions
An expression is simply a piece of the script, which can be resolved into some value. Functions, operators, variables and constants are all expressions. Functions and operators take expressions as parameters, and expressions can be assigned to variables.

For example,

myfunc(l * 2, myfunc2(x * y), x)

is a perfectly valid statement, even though the parameters to myfunc() vary considerably.

Constructs
Constructs are used in most languages to control how and when expressions are evaluated. They are noticeably absent from the Mailtraq scripting language, but because you can pass functions as parameters to other functions, the tasks normally handled by language constructs can be just as easily handled by special functions.

Examples of constructs would include if...then...else (which will execute a statement only if a given expression evaluates to true) and repeat...until (which repeatedly executes a statement until a given expression evaluates to false).

In Mailtraq, the if...then...else construct is handled by the If() function, which takes two or three parameters. The first parameter is the expression, which will be evaluated in order to determine how to proceed. If the expression evaluates to true, then the second parameter will be evaluated and returned, otherwise the third parameter will be evaluated and returned (if it is given, otherwise no evaluation takes place).


For example:-

value := If(number < 2, number * 3, number * 4)

If the variable number is less than two, then value will be assigned the result of number * 3, otherwise it will be assigned the result of number * 4. The number * 3 expression could just as easily include a function, such as MsgGetUneCount() * 3.

The Top Level
The script itself is simply a series of expressions, and they could be considered the parameters to a function, which returns the concatenation of all of them. The only difference with the top level of the script is that the expressions are separated by semicolons instead of commas.

For example, the script...

Header( "subject" );
"\n";
Header( "date" )

...would evaluate to a message subject and date (taken from the message header fields) separated by a line break. In normal scripts, this information would simply be discarded (as the result from a script is never passed to anything else). However, in templates (where scripts are embedded amongst the plain text), this information would appear in the place of the script. You should refer to Chapter 16 which discusses this further.

Note that there was no semicolon trailing the last expression. This is because of the underlying nature of the script - the expressions are parameters to another hidden function, and the semicolons simply  
separate these parameters. You could equally use commas, but semicolons will make the structure clearer.

Loop Constructs
Another construct-like function is While(). This function takes two parameters, an expression that controls the loop, and the expression to be executed repeatedly. This is semantically equivalent to the more traditional while...do... loop used in many languages.

Here is an example:-
I := 0;
while(i < 10,
Do(
MsgGetLine(i) ++ "\n",
i := i + 1
)
)

We have also introduced another function: Do(). This function takes any number of parameters, and simply concatenates the results of each. This has the effect of allowing several expressions to be placed in a single parameter. In fact, the top level of the script is actually a hidden Do() function.

In the above example, the Do() function (which returns a specific line from a message with a line break appended) is repeated executed until the value of i is no longer less than 10.

Note also how the variable i was first used. There was no declaration, a value was simply assigned to it. If the i: = 0; line was excluded, the value would be undefined and the While() function would be unable
 
to compare the value of i to 10. You may be wondering what would have happened, so we’ll have a look at error handling.

Error Handling
There are generally two types of errors in most programming languages: syntactic and semantic. Syntactic errors are problems with the syntax of the script. Essentially, the syntax is what the script looks like (as opposed to what it does). For example, if you leave out a comma between two parameters, it is a syntactic error. Mailtraq can spot syntactic errors easily because it has a set of rules to follow, and as long as a script passes these rules (i.e. looks correct) then even if it doesn’t work, at least Mailtraq can
execute it.

Mailtraq cannot execute a script that has syntactic errors, and to help you identify them, it provides a graphing tool. In the Scripts and Templates dialogue (available from the Options menu in the console), you will find a ‘Graph’ button for both templates and scripts. This facility will take a script and draw it as Mailtraq has interpreted the script. Places where Mailtraq has become confused because of syntactic errors are highlighted with the word <ERROR>.

Semantic errors, on the other hand, cannot be spotted by Mailtraq. Such errors would include, for example, requesting a message line that does not exist. The script looks as though it is OK, but when it is actually used, no line would be found (and is therefore an error). Mailtraq does what it can to keep operating, so invariably semantic errors are simply ignored. If you refer to a message line that doesn’t exist, a null value is returned. Nulls are equivalent to the number zero, or an empty string (depending on the comparison being used).
 
Even the best programmers produce semantic errors, so the key is to test all your scripts thoroughly before using them.

Data Types
Mailtraq has no real concept of data types. All values are stored in a similar way, and their interpretation depends on the context in which they are used. For example, if you compare the value “1.0” to “1”, Mailtraq will examine both values, determine that they are both numbers, and compare them numerically (thus indicating that they are equal). If you actually intended to compare the string representations (in which case
they are clearly different), then you need to explicitly use the StrCmp() function (see page 287). Mailtraq will first try to compare values in their numerical form, and only if one of the values is clearly not a valid number, will it perform a string comparison.

Other than numbers and strings (which are just a series of characters) expressions can also evaluate to true and false (called Boolean values). For example, the greater-than operator (a > b) will return true if the first value is greater than the second, and false otherwise. In Mailtraq, these values are represented as the strings "TRUE" and "FALSE".

Lists
Lists are not really part of the scripting language, but they are used so often that it is worth understanding them. A list is simply a series of strings separated by commas. If a string in a list includes a comma, then .the string is surrounded by quotes. For example, the value Monday, Tuesday, “Wed, Fri”, Saturday is a list containing four items (the third of which is “Wed, Fri”. The functions ListItem() and ListCount() are used to access lists. Lists are returned by many function, and the function For() has been created specifically to iterate through them.
 
For example :-

For(“dayname”, “Mon, Tue, Wed, Thu, Fri, Sat, Sun”,
MsgAddL i ne( “on “ ++ dayname ++ “ do something”)
)

This function iterates through each day of the week, inserting that value into the dayname variable.

String Handling
Strings are used throughout the Mailtraq scripts, and many functions are supplied to manipulate them. There are also some aspects of strings that are part of the scripting language. Quite often you will need to concatenate (join) two strings together. The ++ operator is used for this purpose. For example, “one” ++ “two” becomes “one two”.

You may notice that the quotes are used to identify strings (specifically, strings are enclosed within a matching pair of quotation marks). How do you use quotes inside strings? Mailtraq provides a number of escape characters for such a purpose. A quote can be represented with the \q escape. For example, the string “one \qtwo\q three” becomes one “two” three when added to a message, or when written to a file.

Another escape is \n, which represents a line break. When a string containing line breaks is added to a message, the result is that several lines are added.

Finally, the \l and \r escapes represent the left and right braces ( { and} ) respectively. This is useful for templates, where the braces enclose embedded scripts.


Working with Scripts

What can you do with a script? Most often, you will want to modify a message in some way. After all, Mailtraq is essentially a mail server. Scripts can access and modify the header and body of a message, can also create new messages. For this reason, many of the functions available to scripts relate to message manipulation.

Signatures Examples
For example, you may wish to add a signature to all messages sent by certain people. You could use the scripting database functions to look up the sender’s name in a database, and if it exists, add a string to a message.

Here is an example:-

If(IsAddressLocal(GetMsgSender(),
Do(
name := UserOf(GetMsgSender()),
If(DBRecordExists(“signatures” , name),
MsgAddLine(DBRead(“signatures”, name, “sig”)
)
)
)

In the Mailtraq databases directory (database\db) you would create a file called “signatures” containing something like:-

[johns]
sig=\n-- \nJohn Smith, Projects Manager\nExt 133

[jamesw]
sig=\n-- \nJames Woods, Accounts Department\nExt 145


In the next section we will examine how to install and use this script.

Using Scripts

Scripts can be called manually by the user, automatically (either scheduled or as a result of some trigger), or they can be embedded in templates. The templates are discussed in the next chapter, and the following sections will examine the manual and automatic execution of scripts.

Manually Executing a Script
You can execute any script using the Run Script command from the File menu of the Mailtraq Console. You can also execute a script while Mailtraq is running by running a script file from the Windows Explorer.

Files with the extension .mtq are associated with Mailtraq’s scripting service, and when you double-click on such a file in Explorer, Mailtraq will be sent a message telling it to execute the script.

This way of executing scripts is not very useful, as the purpose behind scripts is the ability to repeat them.

Automatically Executing a Script
If you visit the Scripts and Templates dialogue (from the Options menu in the  Mailtraq Console), you will find where the scripts are configured.
 
In the Scripts tab, you will see a list of all the scripts that Mailtraq has stored in its database. To create a new script, click on the Add button. A new file will be added to the list, and you can change the name to something more appropriate. You can then edit the file and enter the contents of the script itself.

The Scripts Tab (Scripts and Templates)
 

Once you have done this, Mailtraq then ‘knows’ about the script. If you entered the script described above, and called it ‘add-sig’, then you could then call that script either from the Automatic Scripting service, or from any other script with the statement CallScript(“add-sig”).

The Automated Scripts Tab (Scripts and Templates)
 

The Automatic Scripting tab shows a list of all the automatic events that have been configured. To create a new event, click on the Add button. When a new event appears on the list, you can select it and click on Properties to edit it. In the ‘Script/Plug-In to execute’ option you can select the previously created script.
 
Automated Scripts Properties
 

The Trigger
Automatic Scripts can be triggered either by the receipt of a message that matches a given filter (at a certain point in the Mailtraq routing process), or at a scheduled time. Scripts triggered by the receipt of a message have a number of options.

Firstly, you should specify when the message trigger should take place. This determines at what point during the message handling process Mailtraq examines it’s list of scripts and triggers them.

· Inbound Mail Delivery

This takes place immediately after a message is received (for example, from a gateway or receipt via SMTP). This stage only occurs once per message, and it takes place before the message is routed (i.e., the message recipients will not have yet been altered according to the various routing configurations in Mailtraq).


· Outbound Mail Delivery

This takes place just prior to the message being delivered. Again, this only happens once per message, and it only takes place if the message actually leaves the Mailtraq server. This means that delivery to local addresses do not trigger scripts with this option.

· Mail Routing

This can take place several times per message. For example, a message can be routed to it’s recipient, which may in turn forward it to other addresses, for which the message will again enter the routing stage. Messages being distributed via a mailing list will always pass through the router at least twice.

· Mail Storage

This takes place just prior to the message being stored in a user’s mailbox (or archive). This is useful in that at this stage the final recipient of the message will be known (as no further routing will take place).

· Inbound News Delivery

This takes place when a news article is downloaded from another news server, or when a user posts a message from a local news client. At this stage, the news article has not yet been stored in a news group (or placed in the outgoing news folder).
 
· Outbound News Delivery

This takes place just prior to a news article being uploaded to a remote news server.

Modifying the Trigger Message
There is also a check-box “Script will modify the message”. Many scripts are intended to alter the message that triggers them in some way (as does the earlier example). Mailtraq needs to know if your script might do that, otherwise it will not wait for the script to complete before continuing with the message delivery.

The Message Trigger Properties
 

When this option is not selected, the “Handoff to script” option becomes available. If the handoff option is selected, then Mailtraq will not continue delivery of the message. Use this option when you wish to use the message to trigger an event, but when the message itself is of no value after the event has been triggered. For example, a message requesting data from a database can be automatically answered, and the trigger message discarded.

Note that you should consider keeping the message anyway as a record of the requests. You can always have the mailbox or archive that it is sent to expire the message after a period.

 


 

Download Trial
Buy now
Screenshots
Requirements
Feature Tree
FAQs
What's new
Print this pagePrint this Page  
Mailtraq 2.12 PDFDatasheet  
Send a friend an email about MailtraqShareMailtraq - Email Server at Delicious Mailtraq - Mail Server at digg Mailtraq - Mail Server at FacebookMailtraq - Email Server at stumbleupon Tweet about Mailtraq 

 

 

 
Mailtraq Highlights...
 SMTP Server     Mailtraq SMTP email server video IMAP Server     Mailtraq IMAP email Server video
 POP3 Server     Mailtraq POP3 email server video Proxy Server     Mailtraq proxy email server video
 Webmail Server     Mailtraq webmail email server video Mailing-list Server     Mailing list email server video
 Groupware Services     Mailtraq groupware email services video Spam and Virus control     Spam and virus control email server video

 

   Copyright © 2003 - 2011 Enstar Ltd, Enstar LLC & Fastraq Ltd. All rights reserved. Privacy policy.
   Mailtraq® is a registered trademark of Fastraq Limited.