Common Use Cases

Use Cases

• Adding a Subscriber
• Sending Messages
• Getting Statistics that Track Email Results
• Synchronising your List with your Website Database

Adding a Subscriber

Scenario

A website visitor purchases an item from your website. You want to add the visitor as a new Contact on your Purchaser List. You also want to immediately send the new Contact a purchase confirmation Email.

API Method

You use the subscribeContact method because it adds the new Contact information to a specified List and triggers any Subscribe Autoresponders configured in your system.

Preconditions

You have already created a Purchaser List for storing a purchaser's Email, street address, purchase details, and payment information. You have also created an Autoresponder that sends a purchase confirmation Email to a new Contact on the Purchaser List when a subscribe action triggers it.

Process

1. The visitor purchases an item on your website and pays for it.
2. Your website sends your system a subscribeContact request with the Email, street address, purchase details and payment information entered or computed on the website as well as the Purchaser List ID.
3. Your system reads the query and creates a new Contact on the Purchaser List with the data sent by subscribeContact.
4. The new Contact subscription triggers the Subscribe Autoresponder to send a purchase confirmation Email to the new Contact.
5. subscribeContact returns the details of the newly added Contact, either for further processing or to indicate that the method was successful.

Sending Messages

Scenario

You want to send a Message to all of the Contacts on your Purchaser List and some of the Contacts on your Leads List tomorrow.

API Method

You use the addBatch method, which initiates the send process.

Preconditions

You have already created the Message.

Process

1. Set the parameters for the Batch object and call addBatch as shown in the sample code below.
   
   The code includes two Batch Arrays to include two different sets of Contacts. In the first array, the value of type is list, which tells the system to send the Message to all Contacts in $list_id01. In the second array the value of type is contacts, which tells the system to send the Message to specific Contacts in $list_id02. In the second array, the Contacts are listed in an additional parameter, contact_list.
   
   The method call specifies the scheduled time as tomorrow in seconds (24*3600).

   // setup vars
   $list_id01     = 123;
   $list_id02     = 456;
   $message_id    = 111;
   $batch_details = array
   (array
     ('list_id'      => $list_id01,
     'type'         => 'list',       // all Contacts in List 123
     'time'         => 'send,        // populate Batch time of send
     )
   array
     ('list_id'      => $list_id02,
     'type'         => 'contact',     // send to contact_list, next
     'contact_list' => array(2),array(17),array(18),
     'time'         => 'send,        // populate Batch time of send
   ));
   $queue_id = $api->invokeMethod('addBatch', $message_id, $batch_details,
   time() + (24*3600), true);
   

2. addBatch sends a Batch with the Message ID and List ID/Contact IDs to a Batch Queue. The Batch's position in the Queue is determined by various factors, including whether it is scheduled and the amount of system resources it requires.

3. addBatch has now completed its task and returns the Queue ID to indicate that the Batch is in the Queue. The system takes over the task of sending the Batch.
4. At the scheduled time the next day, a processor populates the Batch with the addresses of all Contacts in List 123 and the three Contacts included from List 456.
5. After populating the Batch, the processor sends the Message to the addresses.
   
   

Getting Statistics that Track Email Results

Scenario

You want to find out how many times each Link in your most recent Email was clicked.

Method

To obtain data about Links you use getBatchLinkStatistics . (Note: Additional getBatch methods return different types of Batch statistics. See Message and Batch Methods for a compete list.)

Preconditions

The Batch was sent, and you have the Batch ID. Recipients have had enough time to open and read the Message.

Process

1. You write an application that calls getBatchLinkStatistics. There is only one parameter to include, the Batch ID.

2. The statistics are returned indexed by Link ID, as in the following example:

   <code>
   {
       "id": 1,
       "result": [
           {
               "link_name": "Example Website",
               "link_url": "http:\/\/www.example.com",
               "click_count": "2",
               "contact_count": "2"
           }
       ],
       "error": null
   }
   {
       "id": 2,
       "result": [
           {
               "link_name": "How to Know Your Audience",
               "link_url": "http:\/\/www.audience.com",
               "click_count": "43",
               "contact_count": "36"
           }
       ],
       "error": null
   }
   

Synchronising your Lists with your Website Databases

Scenario

You want to synchronise your website's subscriber database with your system's Customer List.

Method

You use the addContacts method, which already has synchronisation capability. You want to keep the defaults for the optional addContact settings: you will add duplicate Contacts to the List as new Contacts, and you will also add new copies or modificatons of both subscribers and unsubscribers who are on the List.

Preconditions

* The Fields in the website database match the Fields in your Customer List.

* The website database has a Field that stores the Contact's ID from Customer List.

Process

1. Your website system calls addContacts with the List ID and an associative array of subscriber details from its website database as parameters. The associative array includes each subscriber's record index as the key and an array of the subscriber's data as the value.

   To facilitate record matching, subscribers who have previously been added to Customer List via addContacts contain the value of a matching Contact ID in their array. In the example below, the Contact ID is the third value in the array.

    d544 => (jane@mysite.com, Jane,"1"):
   
    d545 => (alain@mysite.com, Alain,"2"):
   
    d546 => (lea@mysite.com, Lea,""):
   
    d547 => (kyle@mysite.com, Kyle,"")
   

2. addContact compares each website subscriber array with the Contacts in Customer List.

   • If it can match the Contact ID, it compares the two records, and if there are no modifications, it continues; otherwise it adds the modifications.
   • If it cannot match the Contact ID, the system creates a new Contact record for the subscriber and assigns it a Contact ID.

3. When addContacts has finished comparing and adding subscribers from the website database, it returns an array to the website. The array is an associative array of newly added Contacts, and includes the website subscribers' IDs as the keys and their new Contact List id's as the values: For example:

     d546 => 3,
     d547 => 4
   

4. The website database uses the website subscriber key to find each subscriber record, and then adds the Contact ID to the third Field on these records.

5. To complete synchronisation, call addContacts with the subscriber database ID as the key and an array of Contact details from Contact List. The same comparison process occurs, but now any new records or modifications entered directly into your system are added to the website database.