Web Services Full Cycle

Below you'll find an overview of the steps you'll have to take in order to launch a campaign using the Addemar web service.

This consumes the creation of an e-mail, segmentation of contacts, launching a campaign and evaluating a campaign.

Useful info
Web service docs: http://ws.email.addemar.com/
All parameters are found under their designated function in the WS docs.

How to make a connection
You must first retrieve a valid token (connection URL) by creating a web service user in your account under My Account >Users > New web service user.

When you have a valid token, you can make your connection:

$sClient = new SoapClient('http://ws.mi.addemar.com/soap/wsdl/?token=1dfg132z65g654dfg651dc1&version=1.1&t=' . rand());

Creating a mail
When you have a valid email template, you can supply the HTML directly to addemar via the function createCreation(). The function returns an ID assigned to that creation.

$creation_id = $sClient->createCreation(
'Newsletter January Test', 'en_UK', 'html', $html, 'Newsletters 2010/January', 'Newsletters 2010');

It’s possible to use a dynamic template or a static template. Using a dynamic template has the advantage that you can edit it’s content through the web service with the editCreationTagX() functions.

More info on constructing dynamic Addemar templates can be found in our online help:

You can retrieve all the editable fields with the function getCreationTags():


Editing a specific tag goes as follows:

$sClient->editCreationTagImage( 1, 'Banner', 'http://www.example.com/banner.jpg', 600, 80, 'Our company banner');

You can always request a preview with the function previewCreation():

echo $sClient->previewCreation('3');

You can upload a bulk of contacts through the function importContacts() (detailed info about this function can be found in the WSdocs).

$sClient->importContacts($xml, 'logmsg', 8);

It will either create a contact when it doesn’t exist or it will just update it.

<contact ref_id="1212">

The function importContacts() will return the ID that is assigned to the import job. You can retrieve the status of any job by calling the function getScheduledJobStatus(). You’ll need to use the job ID from the importContacts() method as a parameter.

$xml = $sClient->getScheduledJobStatus(11);

An example of a returned result:

<contact id="5" ref_id="1212">

You can use the ID attribute of the contact entity to create a reference between the contacts in the Addemar database and your own system. The ID also reappears in the evaluation XML after you launched a campaign. The reference ID (= ref_id attribute) is used to identify which contact is assigned to which ID.

Launching a campaign
When you are satisfied with your creation, you can make a campaign out of it and launch it to your uploaded contacts.

Before creating a campaign, you have to request the structure of your campaign with function getCampaignItemStructure(). You can request a structure for a HTML mail, TEXT mail or a regular landing page:

$campaign_item = $sClient->getCampaignItemStructure('html');

When you have the structure, you can fill it with data necessary to launch it:

$campaign_item->name = 'Newsletter January';
$campaign_item->creation_id = 3;
$campaign_item->to_gid = 8;
$campaign_item->subject = 'Newsletter January';
$campaign_item->to_name = ' ';
$campaign_item->from_name = 'Our Companyname';
$campaign_item->from_email = 'will@addemar.com';
$campaign_item->reply_email = 'reply@example.com';
$campaign_item->reporting_gid = 6;

With the function createCampaignItem(), you actually convert the creation (the creation will also remain) into a campaign:

$ciid = $sClient->createCampaignItem($campaign_item, 'Customer Newsletters/2009/January');

You can preview this campaign, similar to previewCreate(), with the function previewCampaignItem():

echo $sClient->previewCampaignItem(1);

When you are satisfied with the outcome, you can start to test it in an actual email client with the function testCampaignItem():

$sClient->testCampaignItem(1, 2);

After sufficient testing you can do a definite launch with the function launchCampaignItem():


There are a couple of evaluation functions at your disposal. General statistics can be requested with the function getCampaignItemOverview(). It will return you an array with statistical data of the specific campaign item:


Contact specific data can be retrieved with the function getContactsByCampaignItemId():

$xml = $sClient->getContactsByCampaignItemId(1);

Here’s an example of the result:

<?xml version="1.0" encoding="UTF-8"?>
<addemar account="marketing" created="20100114142026">
<contact id="1">
<ts>2010-02-22 12:50:02</ts>

Again, you receive the Addemar contact ID like you did when using the function importContacts().

When you want to retrieve form results you can use the function getFormData():

$xml = $sClient->getFormData(3);