Technical Notes: Using the JangoMail API with PHP

Cool Life Systems, a provider of custom business solutions, uses the JangoMail API with PHP to send emails. They have graciously allowed us to share a sample of the PHP code they use to integrate their system with JangoMail's email solution. We hope this is helpful to anyone looking to use the JangoMail API with PHP. Thanks, Cool Life Systems!

We have two samples available that allow a user to input all of the parameters required by the API in order to send out an email message.

PHP Sample #1: Send a Mass Email - allows a user to send a mass email to a specified group that is in their account using the SendMassEmail method at http://api.jangomail.com/api.asmx?op=SendMassEmail

<?php
                    
$client = new SoapClient('https://api.jangomail.com/api.asmx?WSDL');
$parameters = array
    (
        'Username'          => (string) 'username',
        'Password'          => (string) 'password',
        'FromEmail'         => (string) 'fromaddress@domain.com',
        'FromName'          => (string) 'name',
        'ToGroups'          => (string) 'group name',
        'ToGroupFilter'     => (string) '',
        'ToOther'           => (string) '',
        'ToWebDatabase'     => (string) '',
        'Subject'           => (string) 'Mass Subject',
        'MessagePlain'      => (string) 'Mass Plain (plain text)',
        'MessageHTML'       => (string) 'Mass HTML (html) <br><a href="http://www.google.com">Link #1</a>',
        'Options'           => (string) 'OpenTrack=True,ClickTrack=True'
    );
   
try
{
    $response = $client->SendMassEmail($parameters);
    echo "Message(s) sent!";
}
catch(SoapFault $e)
{
    echo $client->__getLastRequest();
}
?>

PHP Sample #2: Send a Transactional Email - allows a user to send a transactional email to a recipient that they specify using the SendTransactionalEmail method at http://api.jangomail.com/api.asmx?op=SendTransactionalEmail

<?php
               
$client = new SoapClient('https://api.jangomail.com/api.asmx?WSDL');
$parameters = array
    (
        'Username'          => (string) 'username',
        'Password'          => (string) 'password',
        'FromEmail'         => (string) 'fromaddress@domain.com',
        'FromName'          => (string) 'name',
        'ToEmailAddress'    => (string) 'recipient@domain.com',
        'Subject'           => (string) 'Transactional Subject',
        'MessagePlain'      => (string) 'Transactional Plain (plain text)',
        'MessageHTML'       => (string) '<b>Transactional HTML</b> (html)',
        'Options'           => (string) 'OpenTrack=True,ClickTrack=True'
    );
   
try
{
    $response = $client->SendTransactionalEmail($parameters);
    echo "Message(s) sent!";
}
catch(SoapFault $e)
{
    echo $client->__getLastRequest();
}
?>

How we restored a customer's lost email list

Sometimes I'm surprised by the creativity of our staff to solve customer problems.

Today we had a customer (name changed to protect their privacy), Pecan Films, that returned to JangoMail after being inactive for two months and not having sent an email campaign through JangoMail for over a year. When the customer reactivated their account with us, they logged in, only to discover that their main email list was no longer in the account.

What happened?

We recently put in a data purge mechanism such that email lists for inactive accounts are deleted if there hasn't been any email sending activity for over a year. The Pecan Films account met this criteria, and so their Email List was deleted from the system in the last two months.

Unfortunately, this was the only copy of their email list in existence. They had not exported their email list prior to deactivating their JangoMail account.

Digging for the lost data

I discussed with our sysadmin, and he mentioned that he had an old copy of the database that stores customer Email Lists on a spare server. The database was from September, which would have been right around the time when the Email List was automatically deleted due to account inactivity. The only problem is that the database that stores customers' email lists identifies a particular email list only by its internal numeric identifier, and not by name or by user account. A separate database actually ties the data in the first database to the user account to which it belongs, and the relevant data was also missing from this database, with no September backup copy on which to rely. So despite having the data somewhere in the huge database of customer Email Lists, we had no way of knowing the numerical identifier by which to find the email addresses.

Then, it dawned up on us that had the customer been using JangoMail's subscriber form generator, their web site may have the missing clue. So I go to www.pecanfilms.com (URL changed for privacy), find their Subscriber Signup Form, and am relieved that it looks like a JangoMail subscriber signup form:


And by viewing the source, I found this key line of HTML code:

This is the old version of the FORM ACTION tag for a JangoMail-generated subscriber signup form (the form generator has since been updated). So there was the missing identifier, right in the FORM's ACTION tag. With that in hand, we were able to pinpoint the correct database table, extract the email addresses, and restore them into the customer's account.

Lessons Learned

As a customer, you should regularly backup your email list data. We make it easy to do. Just click the Export List Data button:

If you're using JangoMail to connect in real-time to a database file, then make sure you regularly backup your database using the database's backup tool. All of your database files containing email list data, from Excel Files, to Access Files, to SQL Server databases, should be regularly backed up. With the advent of inexpensive Internet-based backup services like Mozy and Carbonite, it's easy and fast to implement. If you're using JangoMail with a web-based CRM system like Salesforce to send email marketing campaigns, you should use the export functionality built-into the CRM system to keep a local copy of your data handy.

New Survey Features: Export survey data, filter responses, specify a redirect URL

We've launched some long-awaited enhancements to our survey platform. You can now:

1. Export detailed survey response data straight out of Reporting
2. Filter survey responses by a particular question or answer, and then send follow-up email campaigns or create Email Lists based on filtered recipient data.
3. Specify a redirect URL where the user is taken after completing a survey
4. Call the API to retrieve survey responses programatically

Exporting survey data from Reporting

Click the survey column for an email campaign to go to the detailed responses data for that campaign.

Screenshot of detailed survey response data

Filtering survey data

You can filter survey response data by question or by response. After filtering the data, you can then send a followup email campaign to just the recipients that match the filter criteria, or create a new Email List based on the filtered data.



Specifying a redirect URL after survey completion

When designing a survey, you can specify a redirect URL as shown below:

After the user is done taking the survey, the user will be redirected to the URL specified rather than the default JangoMail survey-completion page.


API methods to access survey data

The new method is available in 3 formats, depending on your desired output format:



Survey responses must be retrieved by their corresponding email campaign, specifying the numeric Job ID. Additionally, the data can be sorted one of two ways, by recipient email address ("e") or by question ("q").

Reports_GetSurveyResponses_Dataset
Retrieves survey responses for a particular mass email campaign. Returns a Dataset.

Reports_GetSurveyResponses_String
Retrieves survey responses for a particular mass email campaign. Returns a String.

Reports_GetSurveyResponses_XML
Retrieves survey responses for a particular mass email campaign. Returns an XML document.

New Feature: Google Analytics integration now works with transactional email

Google Analytics integration is now available with transactional email sent through the SMTP relay or through the API.

If you're already sending mass emails through JangoMail and using Google Analytics, then you need not change anything for your transactional email to also start working with Google Analytics. The only difference between the way in which mass emails are tracked versus transactional emails, is that the "Subject" becomes the "Transactional Group Name" and the "CampaignID" becomes the "Transactional Group ID".

For example, if you're using the default Google Analytics settings in your account, as shown below:



Mass emails with click-tracked links will take the recipient to a URL that looks like this:

http://www.browniekitchen.com/?utm_source=JangoMail&utm_medium=Email&utm_campaign=Welcome+to+Brownie+Kitchen+(789829313)&utm_content=ajay.goel%gmail.com

Transactional email with click-tracked links will take the recipient to a URL that looks like this:

http://www.browniekitchen.com/?utm_source=JangoMail&utm_medium=Email&utm_campaign=Welcome+Group+(22514)&utm_content=ajay.goel%gmail.com

Notice that the difference is that with transactional email, it's not the Subject of the email that gets recorded in Google Analytics, but the Transactional Group name to which it belongs. This determines what the campaign is named inside your Google Analytics account. For mass emails, it makes intuitive sense that the campaign would be named by the mass email's Subject line. For transactional email, it wouldn't make sense to use each individual email's Subject line, because if you send 1,000 transactional emails, all with different Subject lines, you'll end up with 1,000 different campaigns in your Google Analytics account, and making sense of the data would be impossible. That's why transactional emails will be categorized by their Transactional Group Name and not their Subject.

You may use any combination of these values in the four Google Analytics variable fields:

%%EmailAddress%% = the email address of recipient
%%Subject%% = the subject of the mass email campaign
%%CustomID%% = a custom identifier chosen by the user for mass email campaigns
%%CampaignID%% = the JangoMail identifier for a mass email campaign
%%TransactionalGroupName%% = the Transactional Group Name of a transactional email
%%TransactionalGroupID%% = the Transactional Group ID of a transactional email

%%Subject%% and %%CampaignID%% are used for mass emails and %%TransactionalGroupName%% and %%TransactionalGroupID%% are used for transactional email. However, if you are using %%Subject%% and %%CampaignID%%, and you send transactional email, then %%Subject%% will be treated as %%TransactionalGroupName%% and %%CampaignID%% will be treated as %%TransactionalGroupID%%. That means that if you're using your account to send both mass email and transactional email, you can leave the defaults in place for utm_campaign:

utm_campaign: %%Subject%% (%%CampaignID%%)

This setting will allow Google Analytics integration to work with both your mass email and transactional email messages.

More Reading:

For more information on our Google Analytics integration including screenshots of what your campaigns will look like inside Google Analytics, please download the PDF guide to JangoMail's integration with Google Analytics.