Online Manual Welcome Setup Overview Composing Details Managing Data List Management Scripting After Each Send   COM Integration   Include SubMailing   Scheduling More Help Mailer Home Download Mailer . Version History What's new in the latest version Contact Support We are here to help you via email. We will do our best to get back to you right away. Explore M5 Mailer Take the bulk out of email! TM Use your own data Personal email merge Send individual email HTML and/or text Handy email templates Explore M5 Subscriber Web-based list management made simple! Simple subscribe tool Opt-in confirmed Track reads and clicks Custom matching look Free for up to         5000 contacts

Mailer Gold and External Scripting Languages

The Gold version of Mailer 4 supports very powerful scripting language support using external language processors. Mailer 4 supports Microsoft Visual Basic, Javascript, and PHP, all driven by components within the operating system (for VBasic and Javascript) or in a separate installation (for PHP). What's really powerful about the external language capability in Mailer is that you can establish auxiliary connections to other data sources through ODBC from within those languages, and bring that data into each message.

With this capability, you can generate complex invoices with itemized detail, messages containing multiple attachments of source documents available to a customer, detailed scheduling information about upcoming events, and many other possibilites. Essentially, you have all the resources available in a powerful programming language all available within Mailer, which can manage the composition and sending of email for you. We think that's really cool!

To use this feature most effectively, you do need someone who can write the code to do the underlying data processing to produce your messages, but your developer doesn't have to worry about the details of email message handling, failed message management, and list management, and what's more, after a mailing is designed, someone else can perform the sending.

Preliminaries: Mailer's parsing process

When Mailer sends a mailing, the following steps happen:

1. Mailer pulls the data out of the data source
2. If an external language is selected:
   Mailer builds a header to provide the data source information for that record to the external language
   Mailer tacks the header onto the front of the message and runs it through the external language parser
3. If there are no errors, Mailer then runs the resulting output through the internal Mailer scripting language parser
4. Mailer then sends the resulting message

It's important to know that if you are using an external langauge, you can use both external language syntax and Mailer syntax. In fact, your external language syntax can generate Mailer syntax commands, since Mailer's internal language processing happens afterwards. Why does Mailer's internal language processing happen at all? Because it's necessary in order for Mailer to properly process message filters and attachments, which are done with Mailer's command language syntax.

In order to use an external language with Mailer, you need to know the following things which are different for each external language:

• How Mailer makes the header
• What functions are available to produce output
• How external language interfaces with Mailer processing operations

You also need to know how Mailer handles errors that happen during processing, which is independent of external language usage. Here we will cover error handling, and then for each external language, we'll outline the three items above, and then illustrate with an example based on a common example scenario.

Standard Methods and Procedures

Mach5 Mailer provides these methods which you can use in your mailings. The sysntax to access these methods depends slightly on the scripting language that you use, but the examples will show how the syntax differs. The only real difference is that PHP uses a $ for variables and -> to access method members rather than the period used by VBScript and JScript.

mailer.attachFile("Path To file"),     mailer.attachFile("Path To file", "ContentID")

Attaches a file to the mailing. The attachment will be added with the ContentID indicated, if present, for using in HTML references.

mailer.skip()

Tells Mailer to skip the message in which the command occurs.

mailer.format("FormatString")

If FormatString is PLAIN, Mailer will send only the PlainText portion of this message if both are present.
If FormatString is HTML, Mailer will send only the HTML portion of this message if both are present.
The FormatString is case sensitive.

mailer.header("HeaderTag", "Value")

If the HeaderTag is an existing header in the mailing, such as "Subject" or "To", then the command will override the header as defined for the current mailing. The X-Mailer header may not be changed, however.
If the HeaderTag does not yet exist in the mailing, Mailer will add the indicated header tag to your message.

Any of the commands can appear in the HTML or Plain Text portions of the mailing. They will have the same effect.

Mailer 3 Users: Note that the header and format commands are not available prior to Mailer 4.

Setting Up - choosing the scripting language

JavaScript and Visual Basic are included as components with Internet Explorer, which should be installed already on your computer. PHP requires installation of PHP which is free at the PHP website. Setting up Mailer to use a scripting language is very easy - just choose it from the pulldown menu in the General properties of the Message Information window when you are setting up your mailing.

If you are using PHP, just point Mailer to the directory that contains "php.exe" on your system.

It's not a good idea to change scripting languages after your mailing is already set up! You can do it, but you will have to go in and edit all of the script that your mailing uses to change source languages.

Error Handling

If you have a syntax or database or other runtime error in your scripting, you need accurate information about that error. Mailer simply shoves the results of the external language script execution into the mailing. Whatever error reporting that the external language provides will be passed along directly in the preview window.

The test run feature can be useful to see if there are any glaring problems in your mailing. However, you need to step through your mailing at key records to make sure that you've cleared up any errors first.

Note that errors can show up both in the plaintext and html components of your mailing independently. Therefore it's best to preview both sections.

Post Process Scripting

Mailer Gold also has the ability to run a script after it tries to send a message. The scripting syntax and methods are the same as per-mailing scripting. See the documentation on post-process scripting for more info.

Example Scenario - Overview

Each external language section in this documentation includes an example which leverages off a common problem, outlined here.

Need: We need to send regular emails to our customers with updates about multiple jobs we do for them. At any point of time, each customer has one or more jobs in progress, and we would like to send overall report about status of all individual jobs. For simplicity suppose each customer has at least one active job. Each job may have a job report associated with it, and if it does, we want to send that job report to the customer as an attachment. As a result, an email may have no attachments, one or more attachments up to the number of jobs for the customer.

Data Sources: For this example we will have two different database tables. One table, the main one, contains customer information such as name, email address, customer ID, and other related information. This table will be the data source for the mailing. We will pull information about jobs in process from a second table through ODBC. The second table has a filename field in it for the job report to send, which is an empty string if there is no job report.

Result: The result of the mailing may produce a message like the following:

Dear Josh,
Jobs currently in progress:

Job, Status, Amount
===========================
Job1, Completed, $10
Job2, Printing, $1
Job3, Not started, $2
===========================

Total: $13 in 3 jobs

(File attachment: "c:\jobs\job1.xls")

Producing the Result in Microsoft VBScript

VBScript creates and registers the following methods that you can use in your mailings:

mailer.attachFile()
mailer.skip()
output context :mailer

Here's the source:

Dear <? mailer.fields("customer_name")?> ,
Jobs currently in progress:
Job, Status,    Amount
===========================
<?    
	Dim cnn, rst    Dim n, nTotal
    Set cnn = CreateObject("ADODB.Connection")
    Set rst = CreateObject("ADODB.Recordset")
    cnn.Open "Provider=MSDASQL.1;Data Source=jobs_odbc"
    rst.Open "SELECT * FROM jobs WHERE customer_id=" 
         &  CInt(mailer.fields("customer_id")), cnn
    n = 1
    nTotal = 0
    Do Until rst.EOF
        mailer.write("Job" & n & ", ")
        mailer.write(rst("status") & ", ")
        mailer.write(rst("amount"))
        if Len(rst("attach")) > 0 then mailer.attachFile(rst("attach"))
        mailer.write(vbCrLf)
        n = n + 1
        nTotal = nTotal + rst("amount")
        rst.MoveNext
    Loop
    rst.Close
    cnn.Close
?>   
===========================
<?
    mailer.write("Total: $" & nTotal & " in " & (n ? 1) & " jobs")
?>

Producing the Result in Javascript

Javascript creates and registers the following methods that you can use in your mailings:

mailer.attachFile()
mailer.Skip()
output context :mailer.PlainText and mailer.HtmlText

Here's the source:

Dear <? mailer.fields("customer_name"); ?>
Jobs currently in progress:
Job, Status, Amount
===========================<?
    var    cnn, rst;
    var     n, nTotal;
    cnn = new ActiveXObject("ADODB.Connection");
    rst = new ActiveXObject("ADODB.Recordset");
    cnn.Open("Provider=MSDASQL.1;Data Source=jobs_odbc");
    rst.Open("SELECT * FROM jobs WHERE customer_id=" 
          + mailer.fields("customer_id"), cnn);
    n = 1;
    nTotal = 0;
    while (!rst.EOF())    {
        mailer.write("Job" + n + ", ");
        mailer.write(rst("status") + ", ");
        mailer.write(rst("amount"));
        if (rst("attach").length() > 0)
               mailer.attachFile(rst("attach"));
        mailer.write("\r\n");
        n++;
        nTotal = nTotal + rst("amount");
        rst.MoveNext();
     }
    rst.Close();
    cnn.Close();
?>===========================
<?
    mailer.write("Total: $" + nTotal + " in " + (n ? 1) + " jobs");
?>

Producing the Result in PHP

To use PHP, you need to tell Mailer which directory contains the php installation. This is the directory that contains the file php.exe. This information is stored in mail merge informatio, which is under the "Mail" menu. The General tab of the Mail Merge Information window indicates which scripting language to use, and for PHP, where the php installation is located. In many cases this location will simply be "C:\php4\" but it may be installed in a different place on your computer.

First, Mailer must do some character conversion to interface with PHP as follows:

• Template text is converted into UTF-8
• "Header" with record information and extra PHP function definitions is added to the template
• Final text is saved to a temp file
• PHP executable is launched to process prepared file
• Results of parsing are analyzed for errors and error information is extracted
• Returns results of parsing along with error information to Mailer

PHP creates and registers the following methods that you can use in your mailings:

$mailer->attachFile()
$mailer->skip()
$mailer->plainText->write() and $mailer->.htmlText->write()

Here's the source:

Dear <? $mailer->fields("customer_name") ?>,
Jobs currently in progress:
Job, Status, Amount
===========================<?
  $cnn = odbc_connect("jobs_odbc", "", "");
  $rst = odbc_exec($cnn, "SELECT * FROM jobs WHERE customer_id="
         .   $mailer->fields("customer_id"));
  $n = 1;
  $nTotal = 0;
  while (odbc_fetch_row($rst)) {
    $mailer->plainText->write("Job$n, ");
    $mailer->plainText->write(odbc_result($rst, "status") . ', ');
    $mailer->plainText->write('$' . odbc_result($rst, "amount"));
    if (strlen(odbc_result($rst, "attach")))
      $mailer->attachFile(odbc_result($rst, "attach"));
    $mailer->plainText->write(NL);
    $n++;
    $nTotal += odbc_result($rst, "amount");
  }
  odbc_free_result($rst);
  odbc_close($cnn);
?>===========================<?
  $mailer->plainText->write("Total: \$$nTotal in ? . ($n ? 1) . ? jobs");
?>

Note that it is not necessary to be running a webserver on your system to use the PHP processing. PHP is a general scripting language and can be run independently of a browser environment. PHP is freely distributable and isn't included with the Mach5 Mailer package, but you can download and install it from http://www.php.net/

Home   |   Site map   |   Analyzer   |   Mailer   |   PopMonger   |   Resources   |   Customers and Partners  |   Contact
Mach5 and M5 are registered trademarks of Mach5 Development, LLC.