Interspire Email Marketer Blog

Over the coming days I will be explaining on how to manipulate segments using the API.

Today, I will explain to you on how to create segment using the API. When using the API to create segments, you will be able to create a more powerful filtering than using the standard UI in IEM.

require_once (SENDSTUDIO_API_DIRECTORY . '/segment.php');

$segment = new Segment_API();

// Owner ID of the new segment
$segment->ownerid = 1;

// Current time
$segment->createdate = AdjustTime();

// Segment name
$segment->segmentname = 'Test Segment';

// Segment search information
$segment->searchinfo = array(
  // The list of which the segment will apply it's rule
  // This is an array of list Ids
  'Lists'  => array(49),

  // Segment rules
  'Rules'  => array(
    array(
      'type'      => 'group',
      'connector' => 'and', // Connector for the next group
      'rules'     => array(

        // --- These are the rules that will be applied to the list
        array(
          'type'      => 'rule',
          'connector' => 'or', // Connector for the next rule
          'rules'     => array(
            'ruleName'     => 'email',
            'ruleOperator' => 'like',
            'ruleValues'   => array('someemail@somecompany.com')
          )
        ),
        array(
          'type'      => 'rule',
          'connector' => 'and', // Connector for the next rule
          'rules'     => array(
            'ruleName'     => 20, // Custom field ID
            'ruleOperator' => 'like',
            'ruleValues'   => array('somename')
          )
        )
        // ---

      )
    )
  )
);

$status = $segment->Create();
if (!$status) {
  print "Cannot create segment";
} else {
  print "Segment created with the following id: {$segment->segmentid}";
}

Analysis of the code:
(1) Include segment API
(3) Instantiate new Segment API
(5) Set up owner ID
(8) Specify current time (use AdjustTime() function to do this)
(11) Segment name
(14) Specify the segment search info
(17) Specify the list Ids 00 – These are arrays
(20) Specify the rules

The following rules apply:

• Rule Type can either be: “group” or “rule”
• Rule Connector can either be: “and” or “or”
• “ruleName”: is the fields that the rule will be applied to... This can either be a special fields, or a custom field ID. Currently available special fields are:
  • email: Filter by email
  • format: Filter by format (“h” or “t”)
  • status: Filter by format (“b”, “u”, or “a” translate to “bounced”, “unsubscribed”, “active”)
  • confirmation: Filter by conformation status (“1” or “0”)
  • confirmation: Filter by conformation status (“1” or “0”)
  • subscribe: Filter by subscribe data (mm/dd/yyyy)
  • link: Filter by have/have not clicked a particular link (it accept a link id)
  • campaign: Filter by have/have not opened a particular campaign (it accept a newsletterid)
  • subscriberid: Filter by subscriber id
• ”ruleOperator” value will depends on the context of the “ruleName”, so not all of the following rules will be available for each “ruleName”
  • equalto
  • notequalto
  • like
  • notlike
  • between
  • greaterthan
  • lessthan

Quite a few users have asked about methods to subscribe a user transparently from their website (ie. When they purchased a product from your website, and have opt-in to subscribe to your mailing list), and don't want to get the "Thank you" page displayed after the subscription process. Or when you want to simplify your subscription process by just asking only to fill their email address, and you pre-fill the form for them (ie. Set the format to HTML, etc).

There are two ways to achieve this:

1. Using the API -- Which means:
   • You need to understand how the API works
   • When the subscription process change, your code will also be obsolete (and you need to re-write them)
2. Using a wrapper that act as an intermediate between your subscription HTML form and the Interspire Email Marketer
   

On this occasion, I will talk about how to use a wrapper to achieve this. This is because it is fast, and does not require any knowledge of the Interspire Email Marketer inner workings, and in addition, it will shield your code from any changes that are made in the subscription process.

A quick illustration on how this will work is as follow:

+----------------+        +-------------------+       +-----------------------------+
| Your HTML Page |   ==>  | Your PHP page     |  ==>  | Interspire Email Marketter  |
|                |   <==  |                   |  <==  |                             |
+----------------+        +-------------------+       +-----------------------------+

First of all, you need to create a subscription web-form.... Please de-select the option to use CAPTCHA (As we want to keep the subscription form as simple as possible). After the creation is complete, you need to take note of the form ID.

Now the next process is to create your subscription form:

<html>
  <form action="forms_wrapper.php" method="POST">
    Please enter your email address:
    <input type="text" name="txtEmail" />
    <input type="button" name="cmdSubscribe" value="Subscribe" />
  </form>
</html>

And create a PHP wrapper file that will send the request to Interspire Email Marketer:

<?php
  $data = array(
    'format' => 'h',
    'email' => $_POST['txtEmail']
  );
  $ch = curl_init(CONST_YOUR_IEM_URL . '/form.php?form=' . CONST_YOUR_FORMID);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
  
  $response = @curl_exec($ch);
  curl_close($ch);
  // Response will contains Interspire Email Marketer response to your subscription.
  // It will either be success (Thank you page)
  // Or it will contains the error page
?>

A working example can be downloaded here If you have any queries about this I will be glad to answer them. Simply leave me a comment bellow.

The release of Interspire Email Marketer 5 has seen the addition of a lot of new features. Some of them (like segmenting) are major new additions that many people are excited about, but it may not be the major features that you find most useful in this release. We've been putting a lot of work into making Interspire Email Marketer as easy to use as possible and have snuck in a host of mini-features and improvements to make things clearer, easier and quicker. My favourite new mini-feature is Dynamic List Searching.

If you have a large number of Contact Lists then you may have experienced some frustration selecting the List you want to send a Campaign to, export Contacts from, or search for Contacts in. Now, instead of finding a needle in a haystack, you can let your fingers do the finding!

Simply type a few characters of the Contact List name and the list will shorten itself to just those entries that match your search criteria – as you type!


To get back to your original listing of all Contact Lists, simply clear your search string.

Dynamic List Searching is a very handy feature to speed up tedious list selections. Depending on how people are using it, we may tweak its behavior or roll it out into other areas of Interspire Email Marketer. We might even include it into other Interspire products if it proves popular.

If you have any questions about this or would like to just comment on it please reply below and I will answer you shortly.

On the error page of a form the field is used as a placeholder for the error message. This allows you to choose where the error message will be displayed. When you use a custom error page you cannot use the placeholder and instead the error message is passed to the error page in the Errors parameter. For example the URL for your error page might look something like this:
http://www.domain.com/error.html?Error=error+string+here

In order to print the error message on your custom error page you will need to get the Error parameter from the URL. If you're using a server-side scripting language for your custom error page printing the error message is as simple as printing the value of the Errors parameter. For example if you're using PHP:

An error occurred and your subscription was not completed:

If a server-side language is not available you can still print the error message using JavaScript. This is a bit more complicated since you will need to parse the URL in the JavaScript. A regular expression is ideal for this:

An error occurred and your subscription was not completed: