Advanced E-mail Management: Creating a Template

Hints, Tips and Tricks

Technical Hints Tips and Tricks that cover customization and development using Sage CRM. API usage and coding are covered.

Advanced E-mail Management: Creating a Template

  • Comments 2
  • Likes

In this article I want to discuss how new rule templates for the Sage CRM Advanced E-mail Manager can be created and which SDK resources are available to developers.

I have written previously about the Advanced E-mail Manager and these articles are worth looking at again as a they provide a useful set of background information about what features the Mail Manager provides and the possibilities this opens up for working inbound communications of all types.

About the Advanced E-mail Manager (Mail Manager)

The mail manager processes emails that come into the monitored accounts. Each monitored account is associated with a Script Template. The association is done in the administration screens.

Administration -> E-mail and Documents -> E-mail Management Server Options

The scripts that are shown available in the Template field are automatically drawn from a folder on the server.

C:\Program Files (x86)\Sage\CRM\Services\CustomPages\Scripts

The script files are written in JavaScript. There are several resources available for you to use when working with the Advanced E-mail Manager scripts.

There are dedicated snippets for the Advanced E-mail Manager for the simple Text Editor program Textpad

Sage CRM 7.2: Textpad Snippet Files

There are also snippets available for the Visual Studio installed as part of the SDK.

The specialist E-mail Manager code snippets can be combined with the standard JavaScript snippets that can be used with either the classic ASP pages or with the internal scripting like Validate or Table Level Scripts.

Sage CRM adds several script files as examples when it is installed. These provide very good patterns for an script that you may wish to create. And easy way of experimenting with the script files is to create a copy of a template like 'support.js'.

But the SDK resources do allow you to start assembling you own template script file quite easily.

Script files have a common structure.

  • Comments
  • Initialise Variables
  • General Event Functions
    • BeforeMainAction
    • AfterMainAction
  • Main Functions (referenced in Config screen)
    • N.B. MainAction is a reserved word. Do not call any function ‘MainAction’ as this is internally replaced with function called from configuration screen.
  • Utility Functions

The JavaScript of these templates is processed by 'eWareEmailManager.exe' that runs as a service. It is processed externally from the main eware.dll and uses CRM's registered COM objects with some particular object available to it.

The Comments area is an important reminder that certain objects are automatically passed into the scripting environment as the template loads and is processed.

These objects are

  • UserQuery
  • PersonQuery
  • CompanyQuery
  • eWare
  • MsgHandler
  • eMail

An email being processed will have come from 'someone' and that 'someone' maybe in the system and needs to be identified by the senders email address.

The first three objects are 'QueryObjects' passed into the process that have carried searches using the SQL shown below


[code language="sql"]
user_emailaddress = FromAddress
user_mobileemail = FromAddress


[code language="sql"]
SELECT * FROM vEmail, vPerson WHERE email_personid
= pers_personid AND emai_emailaddress = FromAddress


[code language="sql"]
SELECT * FROM vEmail, vCompany WHERE
emai_companyid = comp_companyid AND
emai_emailaddress = FromAddress

You will note that Leads are not automatically scanned by the Mail Manager but the fourth object passed into the the template scope is the eWare object.

The eWare object is more normally referenced as the CRM object and provides access to all the general API objects.  The eWare or CRM object could then be used to search for the email address in the Lead table or if it was associated with any custom entity that may have been added to the system e.g. project.  Through the use of the QueryObject it could also check the email address in external systems such as an ERP database.

All COM API interactions have to be done as a CRM user. This is part of the system security. See the article "An Overview of System Security".   The eWare or CRM object will have used the credentials provided in the Administration screen. This will typically be a user with Administration rights.  

The MsgHandler allows for Debugging control and the eMail object represents the interface to the email and provides ways of accessing the recipients list and any attachments. The same object can be used by the template script to both process an inbound email but also to formulate a outbound email response.

Note: The email object is not available for either internal scripts like Table Scripts or ASP pages.

There are some other objects passed to the script. In the Administration screen shown above the administrator can configure

  • Default Ruleset Assigned User
  • Default Ruleset Assigned team


  • Default Ruleset Action

The log files for the eWareEmailManager.exe service can be found here

C:\Program Files (x86)\Sage\CRM\Services\Logs

These would show how the additional objects are passed

**********RulesScript is...********
if (bCond)
AssignedUser = 4;
AssignedChannel = 1;
**********End of RulesScript.****

There will be another article that discusses how the Sage CRM Advanced E-mail Manager can be configured to use different functions within templates to allow processing of emails according to business requirements.

Where alternative functions are specified then the additional object passed look like this

**********RulesScript is...********
if ((!CompanyQuery.EOF) && (CompanyQuery("comp_type")=="Customer")
AssignedUser = 4;
AssignedChannel = 1;

if (bCond)
AssignedUser = 4;
AssignedChannel = 1;
**********End of RulesScript.****

The comments section of a Template therefore acts as a good reminder of the objects that are passed to the process. The template script also needs to declare global variables that will facilitate the passing to data between the different functions within the template.

In the examples above we can see that a function called 'SalesEnquiry' is called. This is an example of a main action function.

The main action function defines the key behaviour invoked by the template. Typically this will further reference helper functions that do standardised tasks such as filing an email or providing the auto-response.

The Email Object

The email object is automatically passed to the template script and is globally available to all functions. It has properties and methods to allow the inbound email to be parsed.


  • Body - String (read/write)
  • IsHTML - Boolean (read/write)
  • Subject - String; (read/write)
  • Priority - Integer (read/write)
  • Recipients - AddressList Object
  • SenderName - String (read/write)
  • SenderAddress - String
  • DeliveryTime - Date
  • Attachments - AttachmentList Object
  • BCC - AddressList Object
  • CC - AddressList Object


  • Send()
  • AddFile('physical path')
  • Clear()
  • Header("named header")

Code Example

In have attached an example template script file to this article which can be referenced to see how the object is used.

The example also discusses the way in which the email's addresslist and mail addresses can be parsed.



  • Items(index)
  • Count - Integer(readonly)


  • AddAddress(Address, Name)



  • Name - String (read/write)
  • Address - String (read/write)



  • Items(index)
  • Count - Integer(readonly)
  • LibraryPath - String



  • Name - String (read/write)
  • Extension - String (read only)


  • Save(Name, Path)
  • SaveAs(Name, Path)

  • Is it possible to get an up to date (CRM 7.3) definition for the query objects passed into a template?  eg it says above that PersonObject SQL = "SELECT * FROM vEmail, vPerson WHERE email_personid = pers_personid AND emai_emailaddress = FromAddress" but vEmail no longer exists.  I'm trying to determine which columns are included; Pers_Salutation seems to be absent, for instance, which is annoying.

  • So, I found in the 7.3 System Administrator Guide (p. 35-15) it says the PersonQuery object "runs the following script":

    Select * from vPersonEmail where elink_recordid = pers_

    Personid and emai_emailaddress = FromAddress

    However, vPersonEmail doesn't include any columns prefixed with pers_ and the PersonQuery object passed into a template definitely contains pers_firstname and pers_lastname.