Wednesday, April 21, 2010

How to write a custom web server script for JangoMail integration

JangoMail was one of the first and is one of the only email marketing service providers that can connect to a customer's web site database in real-time. Historically, we've supported and provided web server script files for 4 different scenarios:

Active Server Pages / ODBC Database -- w_1.asp
Active Server Pages / Microsoft SQL Server -- w_2.asp
Active Server Page / Microsoft Access -- w_3.asp
PHP / MySQL -- w_4.php

Recently, we added a fifth option:

ASP.Net page / Microsoft SQL Server - w_5.aspx

All five of these platforms and the five corresponding files are provided to you by JangoMail.

Still, many customers have web/database server that don't fit into one of these canned scenarios. Now, you have the ability to write your own web server script file, based on whatever platform you're running.

First, let's look at the screen in JangoMail where you plug in variable names and values that will be passed into your custom web server script.

Go to Lists --> Databases --> Add New Item

Select Internet Web Database and then 

Download the script file provided and upload it to your platform.
Then click Configure this connection.

Here you will enter your variable names and values.

There are seven variable names and values you may specify. You need not use all seven. For each variable name/value that you specify, your web server script file must be written to accept each variable as a FORM POST. The variable and its corresponding value will be passed to your script file. Note that the variable "action" will be passed always with the value "massmail". This informs your script file that the purpose of this call is to generate a set of data for a mass emailing (as opposed to a synchronization call which we'll cover later).

Once you've programmed your script to accept the variables and values via FORM POST, you must next program your script to generate data based on these variables. Example variables may be:


Based on your web/database platform, these four variables may be sufficient for your script to connect to your database and generate a set of email addresses and other corresponding data.

Regardless of the input parameters that your script takes, the script must generate your email list data in the following format:


Let's break this down and look at it more closely. The output the script should generate is:

1. The field names, separated by a comma.
2. Next, is a standard separator used by JangoMail to separate the field names from the field values: "___ASDF---BREAK"
3. Next comes the actual data, using a column separator of "WG0COLWG0" and a row separator of WG0ROWWG0 (and add an extra row delimiter at the end, before the "end of data stream" line).
4. Finally, at the end of the data string, end with "WANGO-ENDOFDATASTREAM"

For example, assuming you're passing in the correct parameters to connect to your database, and your SQL is:

select FirstName, LastName, EmailAddress from Users

and it returns two records, the output of the script should look like:


Therefore, using the example above with the four input variables, the screen would be filled in as follows:

This example assumes that I have called my script file and that I've placed it in the root directory of It also assumes that is programmed to accept the five POST variables: action, DatabaseName, DatabaseLogin, DatabasePassword, SQL.

When you connect to that profile, JangoMail will connect to your file, the script will output the data for the two records, and take you to this screen, where you can select your campaign to send to the two recipients:

Frequently Asked Questions
1. Do I have to pass in variables to my script file, or can I hard-code the values directly into my script file?

No, you don't have to pass in any variables to the script file, and you may hard-code them within the script file. The disadvantage to doing so are that a. This allows anyone that knows the script file exists to access it and have it output your email list data and b. It prevents JangoMail from synchronizing your database with unsubscribes, bounces, and other recipient actions, since the SQL query will be hard-coded within your script file, and the SQL query will be the query to retrieve email list data, not update it. A better solution may be to do a hybrid between the integration scenario presented above and hard-coding. For example, the database credentials could be hard-coded into the script file, while only the SQL query and a special password that is validated within the logic of the page is passed to the file by JangoMail.

2. Is this method of connecting to my data secure?

Yes. It is inherently secure if you opt to have JangoMail connect over https instead of http. It can be additionally secured by restricting the range of IP addresses allowed to connect to the custom script file. JangoMail's range of IP addresses are: -

3. What is the purpose of the "action" variable name that is forced?

The action variable set to "massmail" tells the script file that this call is specifically to retrieve email list data for a mass emailing, as opposed to other possible actions, like those that synchronize the data with unsubscribe and bounce data.

4. Why does JangoMail need to know which of my variables represents the SQL string?

If you're only using the Web Database Connect feature to retrieve email list data via the web interface only (not the API), you can ignore this setting. This setting is only relevant if you wish to do one of the following:

a. Call the SendMassEmail API method and specify a SQL query in the ToWebDatabase input parameter.
b. Use any of the data synchronization options, like syncing unsubscribe and bounce data back to your database.

In both of these cases, a Master Web Database Profile must be set under Settings. And then, when JangoMail calls the SQL for either scenario a or b, the SQL for the scenario will be passed as the value of the variable rather than the value in the actual web database profile.

5. Where can I read more about this feature?

The following PDF was written when the Web Database Connectivity feature was first made available, and when it was only available on the first four platforms: