Mailtraq Scripting Reference

Properties

Request
Response
Session
Application
System
Server
Directory
Toolkit
Config
Calendaring
UserLanguage
SessionManager
Version
Build
Software
SitePath
DatabasePath

Methods

Write
WriteLine
CreateObject
GetLanguages
SameAddress
NameOf
UniqueString
AddressOf
HostOf
UserOf
CreateUser
DeleteUser
Transfer
MessageSend
MessageSaveDraft
MessageSaveSent
GenerateMessageId
GenerateMessageFilename
URLEncode
URLDecode

Request : HttpRequest or MailMessage

This property holds a reference that depends on the context of the script being executed. If the script is running within the Web Server, then the return value will be the HTTP object. If the script is running in response to a trigger or input message, then the return value will be the MailMessage object that triggered it.

Response : HttpResponse or MailMessage

This property holds a reference that depends on the context of the script being executed. If the script is running within the Web Server, then the return value will be the HTTP object which contains the output web page. If the script is being run in order to generate an output message (such as a message template) then the return value will be the MailMessage object being created.

Session : HttpSession

This property holds a reference to the current session. In the context of Web Scripts: A cookie named SESSIONKEY is used maintain sessions between requests. Sessions can contain an arbitrary number of simple variables and HttpObject objects.

Application : HttpSession

This property holds a reference to the current application object. An application is similar to a HttpSession object in that it maintains values between web requests. However, the application values are shared amongst all the sessions for the current web site.

System : Config

This property is the same as the Config property (named for compatibility with earlier scripts)

Server : Server

This property holds a reference to itself. Because the server is the default object for scripts, it is necessary in order to obtain an object reference for passing to other functions.

Directory : DIS

This property holds a reference to the directory manager. The directory holds information about users and contacts

Toolkit : Toolkit

This property refers to a toolkit of useful functions.

Config : Config

This property holds a reference to the configuration object. Use this object to access or modify properties relating to the system configuration (such as user management and mailbox configuration).

Calendaring : Calendaring

This property holds a reference to the calendaring system. All the user calendars can be accessed and modified through this object.

UserLanguage : string

This property holds the currently selected language code. The language code is in the format base-region, for example en-uk for British English, or fr-ca for Canadian French. The default setting is taken from the environment or web browser, but it can be manually overriden. Some other functions, such as text macros, will select text based on the current language.

SessionManager : SessionManager

This property provides access to the global Session Manager. The Manager is responsible for issuing and maintaining objects.

Version : string

Returns the server version in the form major.minor.release.build

Build : integer

Returns the server build version

Software : string

Returns the server software name

SitePath : string

Returns the root filing system path to the current web site

DatabasePath : string

Returns the root filing system path to the database

Write ( Text ): none

This method outputs text to the current response environment (whatever is returned by the Response property). If the script is being called in a web page then this method will output text to the web page being created. If the script is being called in a template, then the text will be output to the message being created.

WriteLine ( Text ): none

This method outputs a line of text to the current response environment (whatever is returned by the Response property). If the script is being called in a web page then this method will output a line of text to the web page being created. If the script is being called in a template, then the line of text will be output to the message being created.

This method is the same as the Write method except that a carriage-return/linefeed is appended.

CreateObject ( Class ): ActiveXObject

This method creates a new ActiveX object. The object must first be appropriately registered on the server.

Example

var fso = Server.CreateObject("Scripting.FileSystemObject");
fso.DeleteFile("c:\\temp\\dummy.txt");

GetLanguages (): string

This method returns a comma separated list of language names and language codes as defined in the underlying string macro table.

The returned list is sequence of language code and language name pairs. For example, "en,English,fr,French,de,German,pt,Portugese,nl,Dutch".

SameAddress ( Addr1 , Addr2 ): boolean

This method compares two e-mail addresses and returns true if they are the same after certain canonisation. If an address is either the local domain or one of it's aliases then it will match any other alias. If no domain is included, the local domain is assumed. If an address resolves to a local mailbox, then aliases for that mailbox are also considered.

Example

var match = SameAddress("user", "user@local.domain.com");
var anothermatch = SameAddress("user@host.com", "user-alias@host.com");
var fail = SameAddress("user@hotmail.com", "user@yahoo.com");

NameOf ( str ): boolean

This method takes an RFC2822 header e-mail entry and extracts the name part. Header e-mail entries generally appear in formats such as John Smith <jsmith@domain.com> or jsmith@domain.com (John Smith). In both of these cases the return string would be John Smith.

This method is useful for rendering To: or From: message headers, particularly in conjunction with AddressOf.

UniqueString (): string

This method returns a unique string, often useful in creating unique identifies such as message ids. The string can be any length but at present it is eight characters.

AddressOf ( str ): string

This method takes an RFC2822 header e-mail entry and extracts the e-mail address part. Header e-mail entries generally appear in formats such as John Smith <jsmith@domain.com> or jsmith@domain.com (John Smith). In both of these cases the return string would be John Smith.

This method is useful for rendering To: or From: message headers, particularly in conjunction with NameOf.

HostOf ( address ): string

This method returns the domain part of an e-mail address (the part after the @ symbol). If the domain part does not exist, it returns the default local domain.

Given jsmith@domain.com the string domain.com is returned.

UserOf ( address ): string

This method returns the user part of an e-mail address (the part before the @ symbol).

Given jsmith@domain.com the string jsmith is returned.

CreateUser ( username , fullname , password , template (optional) , mailboxtemplate (optional) ): User

This method creates a new user account with the given parameters (subject to sufficient remaining user licenses).

The newly created user account is returned by this method, or null if user creation was unsuccessul.

DeleteUser ( username , mailslots (optional) ): none

This method deletes the named user account. If specified, all owned mailslots will be deleted as well.

Transfer ( path ): string

Transfers execution to another named script. The given parameter is a path (relative to the path of the currently executing script). When the current scriptlet completes, execution will start on the new script.

It is important to note that transfer does not take place immediately, see the example.

Example

1<%
2 var a = 1 + 2;
3 Server.Transfer("script2.asp");
4 a++;
5%>
6 Some text to output
7<%
8 a *= 2;
9%>

In the above example, the execution continues to line 4, after the Server.Transfer() on line 3, but the next scriptlet is not executed because the transfer takes place when the first scriptlet ends on line 5.

MessageSend ( sender , recipients , header , body , attachments , messageid ): none

This method will create and send a new e-mail, optionally with attachments from the current session.

MessageSaveDraft ( mailslot , sender , recipients , header , body , attachments , messageid ): none

This method will create a new e-mail and save it as a draft in the specified mailslot, optionally with attachments from the current session.

MessageSaveSent ( mailslot , sender , recipients , header , body , attachments , messageid ): none

This method will create a new e-mail and save it in the sent-items folder of the specified mailslot, optionally with attachments from the current session.

GenerateMessageId (): string

This method will create a new message-id in the format of <uniquestring@local.domain.com> using the primary domain name.

GenerateMessageFilename (): string

This method will generate a unique string suitable for using as a filename in a mailslot.

URLEncode ( text ): string

This method will encode the given string in a manner suitable for passing as a URL parameter. Effectively, characters not valid in a URL parameter are converted to %hex and spaces are converted to + symbols.

Example

var str = Server.URLEncode("The & character isn't valid");
str == "The+%26character+isn%27t+valid";

See also URLDecode

URLDecode ( text ): string

This method will decode the given string that might have been passed as a URL parameter. Such strings are typically encoded by a routine similar to URLEncode. Effectively, characters not valid in a URL parameter are converted to %hex and spaces are converted to + symbols.

Example

var str = Server.URLDecode("The+%26character+isn%27t+valid");
str == "The & character isn't valid";

See also URLEncode

Properties

Methods

ExtractEmailAddresses
ExtractNamesEmails
SetStringPrefix
SetStringSuffix
HtmlEncode
FirstNonBlank
FormatNumber
HeaderEncode
HeaderEncodeTo
HeaderDecode
HeaderDecodeHtml
HeaderDecodeUtf8
DisDecode
DisDecode
DisToHtml
SuffixNonBlank
PrefixNonBlank
SurroundNonBlank
JoinNonBlank
WrapToColumn
TabList
TabMap
ListItemOf
ListContains
ListRemove
ListCount
VDateCreate
VDateFormat
FirstNameOf
SurnameOf
UserOfEmail
DomainOfEmail
FullnameOf
InsertParams
QualifyAddresses
HtmlToPlainText
DnsLookupA
DnsLookupMx
DnsLookupTxt
DnsLookupPtr
DblVerify
SpfVerify
LongQuoteString
MessageTimestamp
HashMD5
CharsetConvert

ExtractEmailAddresses ( text ): string

This method extracts e-mail addreses from a string that is formatted in a manner suitable for use in an RFC2822 header (such as To: or CC:). This method is capable of extracting multiple e-mail addresses.

The method returns a comma-separated list of addreses.

See also ExtractNamesEmails

ExtractNamesEmails ( text , separator ): string

This method is similar to ExtractEmailAddresses except that it extracts both the e-mail addresses and corresponding display names.

The input string is formatted in a manner suitable for use in an RFC2822 header (such as To: or CC:).

The returned string is a list of e-mail address, display name pairs. The separator string can be specified as a parameter and is used to separate the items in the pairs and the pairs themselves.

Example

var to_header = "To: John Smith To: John Smith <jsmith@domain.org>, Jane Doe <jdoe@host.com>";
var list = Toolkit.ExtractNamesEmails(to_header, "\t");
var array = new String(list).split("\t");
for (var i = 0; i < array.length; i += 2) {
Response.Write(array[i+1] + "'s e-mail is " + array[i]);
}

SetStringPrefix ( text , prefix ): string

This method ensures that the given string starts with the given prefix. This is not the same as concatenating two strings as the method checks first to see if the given prefix is already attached (in a case-insensitive manner).

This function is very useful for prepending the Re: to a subject line when replying.

SetStringSuffix ( text , suffix ): string

This method ensures that the given string ends with the given prefix. This is not the same as concatenating two strings as the method checks first to see if the given suffix is already attached (in a case-insensitive manner).

HtmlEncode ( text ): string

This method encodes the given string in a manner suitable for including in HTML without being interpreted by the HTML engine. Specifically, angle brackets and ampersands are converted into their HTML equivilent.

It is important to note that as both of these changes result in ampersands, repeating the function on a string will further encode it. Thus, the number of encodings must later match the number of decodings.

FirstNonBlank ( text ): string

This method takes a variable number of paramters and returns the first parameter that is neither null or an empty string.

Example

var first = Toolkit.FirstNonBlank(null, "", "First", 2, 3.0);
first == "First";

FormatNumber ( number , type ): string

This method takes an integer and formats it in a suitable manner for presentation.

In the current version, the type parameter bytes is used to reduce the number and append a suitable suffix (gb, mb or k if necessary).

HeaderEncode ( text ): string

This method encodes a string in a manner suitable for use in an RFC2822 header. Some characters are not valid in this context (such as 8bit characters or escape sequences) and must therefore be encoded using a standard mechanism.

The mechanism for encoding this text is inline content encoding which is a compact system that can identify character set and then encode the data using the basic 7bit character set.

This method only encodes the text if it is necessary, making it safe to execute on any text that will be used in a message header. The output format is quoted-printable and the default character-set is assumed.

See HeaderDecode for more information. For encoding To: style headers, see

HeaderEncodeTo ( text ): string

This method is very similar to HeaderEncode but is necessary when encoding header entries with multiple parts that must be encoded separately.

Normally, when a string requires encoding, the entire string is converted into quoted-printable. This is unsuitable for header entries such as To: where multiple addresses may be specified. Typically only the Names need to be encoded, while the e-mail addresses and separators should not.

Therefore, this method effectively divides the input text into a set of strings and each is tested for encoding separately, and then the string is re-combined.

Use this method for To: and CC: headers.

HeaderDecode ( text ): string

This method decodes a header string that may have been encoded using compact inline MIME encoding.

RFC2822 requires that all message headers be basic 7bit, which excludes various accent or language specific characters. In order to carry this data, header text can be encoded using a method called inline content encoding. This is a special construct that converts 8bit characters into 7bit using a content transfer encoding of either quoted-printable or base64.

This inline encoding also specifies the output character set.

Note: the entire subject line is encoded. This will cause problems for To: and CC: lines where other applications may need to extract e-mail addresses without first decoding. Use to handle encoding of this type of header.

Example

As an example: the subject line shown below...

Subject: The price is £99

...contains an 8bit character (the pound sign). The encoding of this text would be...

Subject: =?iso-8859-1?Q?The_price_is=A399?=

The encoded string identifies the character set (iso-8859-1), the content-encoding selected (Q indicates quoted-printable) and then the text appropriately encoded.

See also HeaderDecode

HeaderDecodeHtml ( text ): string

This method is similar to the HeaderDecode method except that the output is appropriately encoded for HTML if the input charset is UTF-8.

HeaderDecodeUtf8 ( text ): string

This method is similar to the HeaderDecode method except that the output is converted to UTF-8.

DisDecode ( text ): string

This method encodes a string in a suitable format for sending to the Directory Information Service. Directory Information is managed using LDAP techniques which require rigid text encoding. The function is similar to URLEncode in that a single string is encoded by replacing invalid characters.

DisDecode ( text ): string

This method decodes a string returned by the Directory Information Service. The output is very similar to the URLDecode method but line breaks are handled in a better manner.

The DIS provides address book information and text being received from the DIS should first be decoded with this method.

If you wish to display the decoded data in HTML, consider using the DisToHtml method instead. See also DisDecode.

DisToHtml ( text ): string

This method is similar to DisDecode except that where appropriate output characters are re-encoded in a manner suitable for display in HTML. In particular, line breaks are encoded into <br> strings.

See also DisDecode

SuffixNonBlank ( text , suffix ): string

This method will return the concatenation of two strings only if the first string is non-blank (not equal to an empty string).

See also PrefixNonBlank, SurroundNonBlank

PrefixNonBlank ( prefix , text ): string

This method will return the concatenation of two strings only if the second string is non-blank (not equal to an empty string).

See also SuffixNonBlank, SurroundNonBlank

SurroundNonBlank ( prefix , text , suffix ): string

This method will return the concatenation of three strings only if the second is non-blank (not equal to an empty string).

See also SuffixNonBlank, PrefixNonBlank

JoinNonBlank ( sep , text ): string

This method selects the non-blank strings from the given parameters and returns them as a single string joined by the given separator.

Example

var table = Toolkit.JoinNonBlank(", ", "One", "", "Three");
table == "One, Three";

WrapToColumn ( document , column , exceptchars ): string

This method takes a block of text and word-wraps it to the given column. If the input block includes CR/LF separators, then each line is wrapped separately.

Optionally, a set of exception characters can be given and if any line starts with one of these characters then the line will not be wrapped.

This method is used to wrap text when composing an e-mail. Typically replies include lines prefixed with > characters and those lines should not be wrapped (so the > character should be included in the exception characters.

Similarly, lines beginning with a | character represent quoted text and should also not be wrapped.