List management

lists()

All email lists (array) are obtained.

lists(integer $start = 0, integer $limit = 1000) : array

Input parametrs

• start - page number starting from which selection will be made (optional). Default value is 0.
• limit - number of results returned in one page (optional). Default value is 1000.

Information obtained

Array of lists. Each list is represented as an array that includes:

• id - list ID that is used in other API functions
• web_id - list ID that is used in the administration page
• name - name of list
• date_created - date of list creation
• member_count - number of emails in list
• sms_member_count - number of SMS in list
• unsubscribe_count - number of unsubscribed emails
• default_from_name - sender name (by default)
• default_from_email - sender email (by default)
• default_subject - subject line (by default)
• default_language - language (by default)

Examples

mgapi_lists.php

lists();
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load lists()!";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "Lists returned: " . sizeof($retval) . "\n";
    foreach ($retval as $list) {
        echo "Id = " . $list['id'] . " - " . $list['name'] . "\n";
    }
}

xml-rpc_lists.php

 new xmlrpcval($apikey)
                ),
                'struct');
$f = new xmlrpcmsg('lists', array($v));
$c = new xmlrpc_client($apiUrl["path"], $apiUrl['host'], 80);
$c->setDebug($debug);
$r = &$c->send($f);
 
header("Content-Type: text/plain");
if (!$r->faultCode()) {
    $retval = php_xmlrpc_decode($r->value());
    echo "Lists returned: " . sizeof($retval) . "\n";
    foreach ($retval as $list) {
        echo "Id = " . $list['id'] . " - " . $list['name'] . "\n";
    }
} else {
    echo "Unable to run lists()!\n";
    echo "\tCode=" . $r->faultCode() . "\n";
    echo "\tMsg=" . $r->faultString() . "\n";
}

mgapi_lists.py

from lib.config import * #contains apikey
from lib.MGAPI import MGAPI
 
# This Example shows how to ping using the MGAPI.php class and do some basic error checking.
 
api = MGAPI(apikey)
 
retval = api.lists()
if api.errorCode:
    print "Unable to load lists()!"
    print "\tCode=", api.errorCode
    print "\tMsg=", api.errorMessage
else:
    print "Lists returned: %d" % (len(retval))
    for list in retval:
        print "Id = %s - %s" % (list["id"], list["name"])

listCreate()

Create new list..

listCreate(string $title, array $options) : string

Input parametrs

• title - list name
• options - array of campaign parameters consisting of:
  • permission_reminder - reminder message for users how they got on this list
  • notify_to - email address where notificiations will be sent
  • subscription_notify - whether notification is sent that a new user has been subscribed (true, false)
  • unsubscription_notify - whether notification is sent that a new user has been unsubscribed (true, false)
  • has_email_type_option - whether user can pick email format (true, false)
  • public_title - name that will be displayed on your web sign-up forms and sign-up confirmation emails

Information obtained

Array of lists. Each list is represented as an array that includes:

• ID of the new list

Examples

mgapi_listCreate.php

<?php
/**
 * This Example shows how to listCreate using the MGAPI.php class and do some basic error checking.
 */
require_once 'inc/MGAPI.class.php';
require_once 'inc/config.inc.php'; //contains apikey
 
$api = new MGAPI($apikey);
 
$title = 'Test List';
$options = array(
    'permission_reminder' =--> 'Write a short reminder about how the recipient joined your list.',
    'notify_to' => 'example@example.org',
    'subscription_notify' => true,
    'unsubscription_notify' => true,
    'has_email_type_option' => true,
    'public_title' => 'Public Name for Test List',
);
 
$retval = $api->listCreate($title, $options);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load listCreate()!\n";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "New List ID:" . $retval . "\n";
}

xml-rpc_listCreate.php

<?php
/**
 * This Example shows how execute a listCreate and check the result using XML-RPC.
 * Note that we are using the PEAR XML-RPC client and recommend others do as well.
 */
require_once 'xmlrpc-3.0.0.beta/xmlrpc.inc';
require_once 'inc/config.inc.php';
 
$apiUrl = parse_url($apiUrl);
 
$v = new xmlrpcval(array(
                    'apikey' =--> new xmlrpcval($apikey),
                    'title' => new xmlrpcval('Test List'),
                    'options' => php_xmlrpc_encode(
                            array(
                                "permission_reminder" => 'Write a short reminder about how the recipient joined your list.',
                                "notify_to" => 'example@example.org',
                                "subscription_notify" => true,
                                "unsubscription_notify" => true,
                                "has_email_type_option" => true
                            )
                    )
                ),
                'struct');
$f = new xmlrpcmsg('listCreate', array($v));
$c = new xmlrpc_client($apiUrl["path"], $apiUrl['host'], 80);
$c->setDebug($debug);
$r = &$c->send($f);
 
header("Content-Type: text/plain");
if (!$r->faultCode()) {
    $retval = php_xmlrpc_decode($r->value());
    echo "Returned: " . $retval . "\n";
} else {
    echo "Unable to load listCreate()!\n";
    echo "\tCode=" . $r->faultCode() . "\n";
    echo "\tMsg=" . $r->faultString() . "\n";
}

listUpdate()

Update list parameters.

listUpdate(string $id, string $name, $value) : boolean

Input parametrs

• id - list ID
• name - name of parameter (see Creation of new list for possible parameter names)
• value - value of parameter (see Creation of new list for possible parameter values)

Information obtained

• true, if uppdate was successful. Otherwise, an error message is returned.

Examples

mgapi_listUpdate.php

listUpdate($id, $name, $value);
 
header("Content-Type: text/plain");
if ($api->errorCode){
    echo "Unable to load listUpdate()!\n";
    echo "\tCode=".$api->errorCode."\n";
    echo "\tMsg=".$api->errorMessage."\n";
} else {
    echo "SUCCESS! \n";
}

xml-rpc_listUpdate.php

 new xmlrpcval($apikey),
                    'id' => new xmlrpcval($listId),
                    'name' => new xmlrpcval('title'),
                    'value' => new xmlrpcval('New Title')
                ),
                'struct');
$f = new xmlrpcmsg('listUpdate', array($v));
$c = new xmlrpc_client($apiUrl["path"], $apiUrl['host'], 80);
$c->setDebug($debug);
$r = &$c->send($f);
 
header("Content-Type: text/plain");
if (!$r->faultCode()) {
    $retval = php_xmlrpc_decode($r->value());
    echo "Returned: " . $retval . "\n";
} else {
    echo "Unable to load listUpdate()!\n";
    echo "\tCode=" . $r->faultCode() . "\n";
    echo "\tMsg=" . $r->faultString() . "\n";
}

listDelete()

List is deleted from the database..

listDelete(string $id) : boolean

Input parametrs

• id - list ID

Information obtained

• true if request for deleting list has succeeded.

Examples

mgapi_listDelete.php

listDelete($id, $tag);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load listDelete()!\n";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "List Deleted!\n";
}

listMergeVars()

This function obtains merge fields (array) from database, as well as all the necessary parameters of these fields.

listMergeVars(string $id) : array

Input parametrs

• id - list ID

Information obtained

Array of merge fields. Each merge field is represented as an array that includes:

• name - name of merge field
• req - whether this field is obligatory (true, false)
• field_type - type of field (email, text, number, radio, grouping, dropdown, date, address, sms, website, image)
• show - whether this field is shown in the list (true, false)
• pubilc - whether this field is shown in the web signup forms (true, false)
• order - serial number
• default - default value
• tag - merge field name that is used in forms and also in API functions such as listSubscribe and listUpdateMember
• predefined_values - user predefined custom field values for radio, grouping and dropdown field types
  Important

  • Array of values and labels are returned.

Examples

mgapi_listMergeVars.php

listMergeVars($id);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load listMergeVars()!";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "Merge tags returned: " . sizeof($retval) . "\n";
    foreach ($retval as $i => $var) {
        echo "Var #$i:\n";
        echo "\tTag: " . $var['tag'] . "\n";
        echo "\tName: " . $var['name'] . "\n";
        echo "\tRequired: " . $var['req'] . "\n";
    }
}

xml-rpc_listMergeVars.php

 new xmlrpcval($apikey),
                    'id' => new xmlrpcval($listId)
                ),
                'struct');
$f = new xmlrpcmsg('listMergeVars', array($v));
$c = new xmlrpc_client($apiUrl["path"], $apiUrl['host'], 80);
$c->setDebug($debug);
$r = &$c->send($f);
 
header("Content-Type: text/plain");
if (!$r->faultCode()) {
    $retval = php_xmlrpc_decode($r->value());
    echo "Merge tags returned: " . sizeof($retval) . "\n";
    foreach ($retval as $i => $var) {
        echo "Var #$i:\n";
        echo "\tTag: " . $var['tag'] . "\n";
        echo "\tName: " . $var['name'] . "\n";
        echo "\tRequired: " . $var['req'] . "\n";
    }
} else {
    echo "Unable to run listMergeVars()!\n";
    echo "\tCode=" . $r->faultCode() . "\n";
    echo "\tMsg=" . $r->faultString() . "\n";
}

mgapi_listMergeVars.py

from lib.config import * #contains apikey
from lib.MGAPI import MGAPI
 
# This Example shows how to ping using the MGAPI.php class and do some basic error checking.
 
api = MGAPI(apikey)
 
id = listId
 
retval = api.listMergeVars(id)
if api.errorCode:
    print "Unable to load listMergeVars()!"
    print "\tCode=", api.errorCode
    print "\tMsg=", api.errorMessage
else:
    print "Merge tags returned: ", len(retval)
    if isinstance(retval, dict):
        for i,var in retval.items():
            print "Var #%d:" % (i)
            print "\tTag: ", var['tag']
            print "\tName: ", var['name']
            print "\tRequired: ", var['req']
    elif isinstance(retval, list):
        for i,var in enumerate(retval):
            print "Var #%d:" % (i)
            print "\tTag: ", var['tag']
            print "\tName: ", var['name']
            print "\tRequired: ", var['req']

listMergeVarAdd()

This function adds a new merge field to a particular list in the database adding also the name and settings of this field.

listMergeVarAdd(string $id, string $tag, string $name, array $options) : boolean

Input parametrs

• id - list ID
• tag - merge field tag name. Used in forms and also in API functions such as listSubscribe and listUpdateMember
• name - user friendly name
• options - settings of a field (optional). Array consisting of:
• field_type - field type of merge tag (text, number, radio, grouping, dropdown, date, address, sms, website, image) (optional). Default value is text.
  Important adding data to date field type use the following format: YYYY-MM-DD, e.g., 2015-09-30 See API functions listSubscribe and listUpdateMember for adding data to merge fields.
• req - required (true, false) (optional). Default value is false.
• show - whether this field is shown in the list (true, false) (optional). Default value is true.
• pubilc - whether this field is shown in the web signup forms (true, false) (optional). Default value is true.
• default_value - default value of merge tag (optional).
• predefined_values - user predefined custom field values for radio, grouping and dropdown field types (optional).
  Important 

  • Two vertical lines (||) are used as a value separator. E.g.,

    Male||Female||Prefer not to say

  • Array of values and labels can be used as well. E.g.,

    array('values' => array('M', 'F'), 'labels' => array('Male', 'Female'))

Information obtained

Array of merge fields. Each merge field is represented as an array that includes:

• true, if request for field creation has succeeded.

Examples

mgapi_listMergeVarAdd.php

 'text',
    "req" => false,
    "default_value" => 'Default value',
    "show" => true
);
 
$retval = $api->listMergeVarAdd($id, $tag, $name, $options);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load listMergeVarAdd()!\n";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "Returned: " . $retval . "\n";
}

xml-rpc_listMergeVarAdd.php

 new xmlrpcval($apikey),
                    'id' => new xmlrpcval($listId),
                    'tag' => new xmlrpcval('MERGE_TAG'),
                    'name' => new xmlrpcval('Merge Tag name'),
                    'options' => php_xmlrpc_encode(
                            array(
                                "field_type" => 'text',
                                "req" => false,
                                "default_value" => 'Default value',
                                "show" => true
                            )
                    )
                ),
                'struct');
$f = new xmlrpcmsg('listMergeVarAdd', array($v));
$c = new xmlrpc_client($apiUrl["path"], $apiUrl['host'], 80);
$c->setDebug($debug);
$r = &$c->send($f);
 
header("Content-Type: text/plain");
if (!$r->faultCode()) {
    $retval = php_xmlrpc_decode($r->value());
    echo "Returned: " . $retval . "\n";
} else {
    echo "Unable to load listMergeVarAdd()!\n";
    echo "\tCode=" . $r->faultCode() . "\n";
    echo "\tMsg=" . $r->faultString() . "\n";
}

mgapi_listMergeVarAdd.py

from lib.config import * #contains apikey
from lib.MGAPI import MGAPI
 
# This Example shows how to ping using the MGAPI.php class and do some basic error checking.
 
api = MGAPI(apikey)
 
id = listId
tag = 'MERGE_TAG'
name = 'Merge Tag name'
options = {
    "field_type": 'text',
    "req": False,
    "default_value": 'Default value',
    "show": True
}
 
retval = api.listMergeVarAdd(id, tag, name, options)
if api.errorCode:
    print "Unable to load listMergeVarAdd()!"
    print "\tCode=", api.errorCode
    print "\tMsg=", api.errorMessage
else:
    print "Returned: ", retval

listMergeVarUpdate()

Update of merge field parameters. It is not possible to change the type of merge field.

listMergeVarUpdate(string $id, string $tag, array $options) : boolean

Input parametrs

• id - list ID
• tag - merge field tag
• options - settings of a field (see Adding new merge field for acceptable settings of a field)

Array of merge fields. Each merge field is represented as an array that includes:

• true, if request for field update has succeeded.

Examples

mgapi_listMergeVarUpdate.php

 false,
    "name" => 'Merge Tag name',
    "default_value" => 'Default value',
    "show" => true
);
 
$retval = $api->listMergeVarUpdate($id, $tag, $options);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load listMergeVarUpdate()!\n";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "Returned: " . $retval . "\n";
}

xml-rpc_listMergeVarUpdate.php

 new xmlrpcval($apikey),
                    'id' => new xmlrpcval($listId),
                    'tag' => new xmlrpcval('MERGE_TAG'),
                    'options' => php_xmlrpc_encode(
                            array(
                                "req" => false,
                                "name" => 'Merge Tag name',
                                "default_value" => 'Default value',
                                "show" => true
                            )
                    )
                ),
                'struct');
$f = new xmlrpcmsg('listMergeVarUpdate', array($v));
$c = new xmlrpc_client($apiUrl["path"], $apiUrl['host'], 80);
$c->setDebug($debug);
$r = &$c->send($f);
 
header("Content-Type: text/plain");
if (!$r->faultCode()) {
    $retval = php_xmlrpc_decode($r->value());
    echo "Returned: " . $retval . "\n";
} else {
    echo "Unable to load listMergeVarUpdate()!\n";
    echo "\tCode=" . $r->faultCode() . "\n";
    echo "\tMsg=" . $r->faultString() . "\n";
}

mgapi_listMergeVarUpdate.py

from lib.config import * #contains apikey
from lib.MGAPI import MGAPI
 
# This Example shows how to ping using the MGAPI.php class and do some basic error checking.
 
api = MGAPI(apikey)
 
id = listId
tag = 'MERGE_TAG'
options = {
    "req": False,
    "name": 'Merge Tag name',
    "default_value": 'Default value',
    "show": True
}
 
retval = api.listMergeVarUpdate(id, tag, options)
if api.errorCode:
    print "Unable to load listMergeVarUpdate()!"
    print "\tCode=", api.errorCode
    print "\tMsg=", api.errorMessage
else:
    print "Returned: ", retval

listMergeVarDel()

Merge field is deleted from the database, as well as deleted the value of field from all contacts in the list.

 

listMergeVarDel(string $id, string $tag) : boolean

Input parametrs

• id - list ID
• tag - merge field tag

Information obtained

• true if request for deleting list has succeeded.

Examples

mgapi_listMergeVarDel.php

listMergeVarDel($id, $tag);

header("Content-Type: text/plain");
if ($api->errorCode){
	echo "Unable to load listMergeVarDel()!\n";
	echo "\tCode=".$api->errorCode."\n";
	echo "\tMsg=".$api->errorMessage."\n";
} else {
	echo "Returned: ".$retval."\n";
}

xml-rpc_listMergeVarDel.php

 new xmlrpcval($apikey),
					'id' => new xmlrpcval($listId),
					'tag' => new xmlrpcval('MERGE_TAG')
				 ),
		         'struct');
$f=new xmlrpcmsg('listMergeVarDel', array($v));
$c=new xmlrpc_client($apiUrl["path"], $apiUrl['host'], 80);
$c->setDebug($debug);
$r=&$c->send($f);
//$response = $r->serialize();

header("Content-Type: text/plain");
if(!$r->faultCode()) {
	$retval = php_xmlrpc_decode($r->value());
	echo "Returned: ".$retval."\n";
} else {
	echo "Unable to load listMergeVarDel()!\n";
	echo "\tCode=".$r->faultCode()."\n";
	echo "\tMsg=".$r->faultString()."\n";
}

mgapi_listMergeVarDel.py

from lib.config import * #contains apikey
from lib.MGAPI import MGAPI

# This Example shows how to ping using the MGAPI.php class and do some basic error checking.

api = MGAPI(apikey)

id = listId
tag = 'MERGE_TAG'

retval = api.listMergeVarDel(id, tag)
if api.errorCode:
	print "Unable to load listMergeVarDel()!"
	print "\tCode=", api.errorCode
	print "\tMsg=", api.errorMessage
else:
	print "Returned: ", retval

listSubscribe()

This function adds a new email to existing list with all additional values of the field.

listSubscribe(string $id, string $email_address, array $merge_vars, string $email_type, boolean $double_optin, boolean $update_existing, boolean $send_welcome) : boolean

Input parametrs

• id - list ID
• email_address - address of added email
• merge_vars - values of merge fields (array)
• Merge fields are: FNAME, LNAME, EMAIL and other your defined fields.
• email_type - type of email (HMTL, plain) (optional). Default value is HTML.
• double_optin - whether confirmation email is sent (true, false) (optional). Default value is true.
• update_existing - whether existing emails are restored (true, false) (optional). Default value is false.
• send_welcome - whether ‘Thank you’ email is sent (true, false) (optional). Default value is false.

Array of merge fields. Each merge field is represented as an array that includes:

• true, if request for adding new email has succeeded.

Examples

mgapi_listSubscribe.php

/**
 * This Example shows how to listSubscribe using the MGAPI.php class and do some basic error checking.
 */
require_once 'inc/MGAPI.class.php';
require_once 'inc/config.inc.php'; //contains apikey
 
$api = new MGAPI($apikey);
 
$id = $listId;
$email_address = $my_email;
$merge_vars = array('EMAIL' => $my_email, 'FNAME' => 'Joe'); // or $merge_vars = array('');
$email_type = 'html';
$double_optin = true;
$update_existing = false;
$send_welcome = false;
 
$retval = $api->listSubscribe($id, $email_address, $merge_vars, $email_type, $double_optin, $update_existing, $send_welcome);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load listSubscribe()!\n";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "Returned: " . $retval . "\n";
}

xml-rpc_listSubscribe.php

/**
 * This Example shows how execute a listSubscribe and check the result using XML-RPC.
 * Note that we are using the PEAR XML-RPC client and recommend others do as well.
 */
require_once 'xmlrpc-3.0.0.beta/xmlrpc.inc';
require_once 'inc/config.inc.php';
 
$apiUrl = parse_url($apiUrl);
 
$v = new xmlrpcval(array(
                    'apikey' =--> new xmlrpcval($apikey),
                    'id' => new xmlrpcval($listId),
                    'email_address' => new xmlrpcval($my_email),
                    'merge_vars' => php_xmlrpc_encode(
                            array('EMAIL' => $my_email, 'FNAME' => 'Joe')
                    ),
                    'email_type' => new xmlrpcval('html'),
                    'double_optin' => new xmlrpcval(true),
                    'update_existing' => new xmlrpcval(false),
                    'send_welcome' => new xmlrpcval(false)
                ),
                'struct');
$f = new xmlrpcmsg('listSubscribe', array($v));
$c = new xmlrpc_client($apiUrl["path"], $apiUrl['host'], 80);
$c->setDebug($debug);
$r = &$c->send($f);
 
header("Content-Type: text/plain");
if (!$r->faultCode()) {
    $retval = php_xmlrpc_decode($r->value());
    echo "Returned: " . $retval . "\n";
} else {
    echo "Unable to load listSubscribe()!\n";
    echo "\tCode=" . $r->faultCode() . "\n";
    echo "\tMsg=" . $r->faultString() . "\n";
}

mgapi_listSubscribe.py

from lib.config import * #contains apikey
from lib.MGAPI import MGAPI
 
# This Example shows how to ping using the MGAPI.php class and do some basic error checking.
 
api = MGAPI(apikey)
 
id = listId
email_address = my_email
merge_vars = {'EMAIL': my_email, 'FNAME': 'Joe'} # or merge_vars = {}
email_type = 'html'
double_optin = True
update_existing = False
send_welcome = False
 
retval = api.listSubscribe(id, email_address, merge_vars, email_type, double_optin, update_existing, send_welcome)
if api.errorCode:
    print "Unable to load listSubscribe()!"
    print "\tCode=", api.errorCode
    print "\tMsg=", api.errorMessage
else:
    print "Returned: ", retval

listUnsubscribe()

This function removes recipient email from existing list with all additional field values. The functionality is similar if recipient unsubscribes using unsubscribe link.

listUnsubscribe(string $id, string $email_address, boolean $delete_member, boolean $send_goodbye, boolean $send_notify) : boolean

Input parametrs

• id - list ID
• email_address - email address or ID (can be found by listMemberInfo function, see Obtaining additional email information)
• delete_member - whether recipient is deleted from existing list (true, false) (optional). Default value is false.
• send_goodbye - whether notification is sent to the removed email (true, false) (optional).  Default value is true.
• send_notify - whether notification is sent to sender email which is indicated for a particular list (true, false) (optional). Default value is true.

Array of merge fields. Each merge field is represented as an array that includes:

• true, if request for removing email has succeeded

Examples

mgapi_listUnsubscribe.php

listUnsubscribe($id, $email_address, $delete_member, $send_goodbye, $send_notify);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load listUnsubscribe()!\n";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "Returned: " . $retval . "\n";
}

xml-rpc_listUnsubscribe.php

 new xmlrpcval($apikey),
                    'id' => new xmlrpcval($listId),
                    'email_address' => new xmlrpcval($my_email),
                    'delete_member' => new xmlrpcval(false),
                    'send_goodbye' => new xmlrpcval(true),
                    'send_notify' => new xmlrpcval(false)
                ),
                'struct');
$f = new xmlrpcmsg('listUnsubscribe', array($v));
$c = new xmlrpc_client($apiUrl["path"], $apiUrl['host'], 80);
$c->setDebug($debug);
$r = &$c->send($f);
 
header("Content-Type: text/plain");
if (!$r->faultCode()) {
    $retval = php_xmlrpc_decode($r->value());
    echo "Returned: " . $retval . "\n";
} else {
    echo "Unable to load listBatchUnsubscribe()!\n";
    echo "\tCode=" . $r->faultCode() . "\n";
    echo "\tMsg=" . $r->faultString() . "\n";
}

mgapi_listUnsubscribe.py

from lib.config import * #contains apikey
from lib.MGAPI import MGAPI
 
# This Example shows how to ping using the MGAPI.php class and do some basic error checking.
 
api = MGAPI(apikey)
 
id = listId
email_address = my_email
delete_member = False
send_goodbye = True
send_notify = False
 
retval = api.listUnsubscribe(id, email_address, delete_member, send_goodbye, send_notify)
if api.errorCode:
    print "Unable to load listUnsubscribe()!"
    print "\tCode=", api.errorCode
    print "\tMsg=", api.errorMessage
else:
    print "Returned: ", retval

listSubscribeSMS()

This function adds a new phone number to existing list with all additional values of the field.

listSubscribeSMS(string $id, string $phone, array $merge_vars, boolean $update_existing) : boolean

Input parametrs

• id - list ID
• phone - phone number
• merge_vars - values of merge fields (array)
• Merge fields are: FNAME, LNAME, EMAIL and other your defined fields.
• update_existing - whether existing emails are restored (true, false) (optional). Default value is false.

Array of merge fields. Each merge field is represented as an array that includes:

• true, if request for adding new phone number has succeeded.

Examples

mgapi_listSubscribeSMS.php

 $my_phone, 'FNAME' => 'Joe'); // or $merge_vars = array();
$update_existing = false;
 
$retval = $api->listSubscribeSMS($id, $phone, $merge_vars, $update_existing);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load listSubscribeSMS()!\n";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "Returned: " . $retval . "\n";
}

listUnsubscribeSMS()

This function removes recipient phone number from existing list with all additional field values.

listSubscribeSMS(string $id, string $phone, array $merge_vars, boolean $update_existing) : boolean

Input parametrs

• id - list ID
• phone - phone number or ID (can be found by listMemberInfo function, see Obtaining additional email information)
• delete_member - whether recipient is deleted from existing list (true, false) (optional). Default value is false.
• send_notify - whether notification is sent to sender email which is indicated for a particular list (true, false) (optional). Default value is true.

Array of merge fields. Each merge field is represented as an array that includes:

• true, if request for removing phone number has succeeded

Examples

mgapi_listUnsubscribeSMS.php

listUnsubscribeSMS($id, $phone, $delete_member, $send_notify);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load listUnsubscribeSMS()!\n";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "Returned: " . $retval . "\n";
}

listBatchSubscribe()

Array of recipients’ emails with settings and merge fields are passed, but information (also array) about how many emails have been added to a specific list is returned.

listBatchSubscribe(string $id, array $batch, boolean $double_optin, boolean $update_existing) : struct

Input parameters

• id - list ID
• batch - array of emails. Each email is represented as an array where field names are taken from merge fields and their appropriate values are set.
• double_optin - whether confirmation message will be sent (true, false) (optional). Default value is false.
  Value change of this parameter is deprecated. False value is used always.
• update_existing - whether existing emails will be restored (true, false) (optional). Default value is false.

Information obtained

Array consisting of:

• success_count - number of successfully added emails
• error_count - number of unsuccessfully added emails
• errors - array of error messages about each email. Each error message is represented as an array consisting of fields:
  • code - error code
  • message - error message
  • email - email address that raised error

Examples

mgapi_listBatchSubscribe.php

 $my_email, 'FNAME' => 'Joe');
$batch[] = array('EMAIL' => $boss_man_email, 'FNAME' => 'Boss');
$double_optin = true;
$update_existing = false;
 
$retval = $api->listBatchSubscribe($id, $batch, $double_optin, $update_existing);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load listBatchSubscribe()!\n";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "success:" . $retval['success_count'] . "\n";
    echo "errors:" . $retval['error_count'] . "\n";
    foreach ($retval['errors'] as $val) {
        echo "\t*" . $val['email'] . " failed\n";
        echo "\tcode:" . $val['code'] . "\n";
        echo "\tmsg :" . $val['message'] . "\n\n";
    }
}

xml-rpc_listBatchSubscribe.php

 new xmlrpcval($apikey),
                    'id' => new xmlrpcval($listId),
                    'batch' => php_xmlrpc_encode(
                            array(
                                array('EMAIL' => $my_email, 'FNAME' => 'Joe'),
                                array('EMAIL' => $boss_man_email, 'FNAME' => 'Boss')
                            )
                    ),
                    'double_optin' => new xmlrpcval(true),
                    'update_existing' => new xmlrpcval(false)
                ),
                'struct');
$f = new xmlrpcmsg('listBatchSubscribe', array($v));
$c = new xmlrpc_client($apiUrl["path"], $apiUrl['host'], 80);
$c->setDebug($debug);
$r = &$c->send($f);
 
header("Content-Type: text/plain");
if (!$r->faultCode()) {
    $retval = php_xmlrpc_decode($r->value());
    echo "success:" . $retval['success_count'] . "\n";
    echo "errors:" . $retval['error_count'] . "\n";
    foreach ($retval['errors'] as $val) {
        echo "\t*" . $val['email'] . " failed\n";
        echo "\tcode:" . $val['code'] . "\n";
        echo "\tmsg :" . $val['message'] . "\n\n";
    }
} else {
    echo "Unable to load listBatchSubscribe()!";
    echo "\tCode=" . $r->faultCode() . "\n";
    echo "\tMsg=" . $r->faultString() . "\n";
}

mgapi_listBatchSubscribe.py

from lib.config import * #contains apikey
from lib.MGAPI import MGAPI
 
# This Example shows how to ping using the MGAPI.php class and do some basic error checking.
 
api = MGAPI(apikey)
 
id = listId
batch = []
batch.append({'EMAIL': my_email, 'FNAME': 'Joe'})
batch.append({'EMAIL': boss_man_email, 'FNAME': 'Boss'})
double_optin = True
update_existing = False
 
retval = api.listBatchSubscribe(id, batch, double_optin, update_existing)
if api.errorCode:
    print "Unable to load listBatchSubscribe()!"
    print "\tCode=", api.errorCode
    print "\tMsg=", api.errorMessage
else:
    print "success:", retval['success_count']
    print "errors:", retval['error_count']
    for val in retval['errors']:
        print "\t*", val['email'], " failed"
        print "\tcode:", val['code']
        print "\tmsg :", val['message']

listBatchUnsubscribe()

Emails from the selected list are deleted. Array of recipients’ emails with additional parameters are passed, which determine whether a message/notification about email removal will or will not be sent to this particular email.

listBatchUnsubscribe(string $id, array $emails, boolean $delete_member, boolean $send_goodbye, boolean $send_notify) : struct

Input parameters

• id - list ID
• emails - array of emails
• delete_member - whether recipient is deleted from existing list (true, false) (optional). Default value is false.
• send_goodbye - whether notification is sent to the removed email (true, false) (optional).  Default value is true.
• send_notify - whether notification is sent to sender email which is indicated for a particular list (true, false) (optional). Default value is false.

Information obtained

Array consisting of:

• success_count - number of successfully removed emails
• error_count - number of unsuccessfully removed emails
• errors - array of error messages about each email. Each error message is represented as an array consisting of fields:
  • code - error code
  • message - error message
  • email - email address that raised error

Examples

mgapi_listBatchUnsubscribe.php

listBatchUnsubscribe($id, $emails, $delete_member, $send_goodbye, $send_notify);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load listBatchUnsubscribe()!\n";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "success:" . $retval['success_count'] . "\n";
    echo "errors:" . $retval['error_count'] . "\n";
    foreach ($retval['errors'] as $val) {
        echo "\t*" . $val['email'] . " failed\n";
        echo "\tcode:" . $val['code'] . "\n";
        echo "\tmsg :" . $val['message'] . "\n\n";
    }
}

xml-rpc_listBatchUnsubscribe.php

 new xmlrpcval($apikey),
                    'id' => new xmlrpcval($listId),
                    'emails' => php_xmlrpc_encode(array($my_email, $boss_man_email)),
                    'delete_member' => new xmlrpcval(false),
                    'send_goodbye' => new xmlrpcval(true),
                    'send_notify' => new xmlrpcval(false)
                ),
                'struct');
$f = new xmlrpcmsg('listBatchUnsubscribe', array($v));
$c = new xmlrpc_client($apiUrl["path"], $apiUrl['host'], 80);
$c->setDebug($debug);
$r = &$c->send($f);
 
header("Content-Type: text/plain");
if (!$r->faultCode()) {
    $retval = php_xmlrpc_decode($r->value());
    echo "success:" . $retval['success_count'] . "\n";
    echo "errors:" . $retval['error_count'] . "\n";
    foreach ($retval['errors'] as $val) {
        echo "\t*" . $val['email'] . " failed\n";
        echo "\tcode:" . $val['code'] . "\n";
        echo "\tmsg :" . $val['message'] . "\n\n";
    }
} else {
    echo "Unable to load listBatchUnsubscribe()!";
    echo "\tCode=" . $r->faultCode() . "\n";
    echo "\tMsg=" . $r->faultString() . "\n";
}

mgapi_listBatchUnsubscribe.py

from lib.config import * #contains apikey
from lib.MGAPI import MGAPI
 
# This Example shows how to ping using the MGAPI.php class and do some basic error checking.
 
api = MGAPI(apikey)
 
id = listId;
emails = [my_email, boss_man_email]
delete_member = False
send_goodbye = True
send_notify = False
 
retval = api.listBatchUnsubscribe(id, emails, delete_member, send_goodbye, send_notify)
if api.errorCode:
    print "Unable to load listBatchUnsubscribe()!"
    print "\tCode=", api.errorCode
    print "\tMsg=", api.errorMessage
else:
    print "success:", retval['success_count']
    print "errors:", retval['error_count']
    for val in retval['errors']:
        print "\t*", val['email'], " failed"
        print "\tcode:", val['code']
        print "\tmsg :", val['message']

listBatchSubscribeSMS()

Array of recipients’ phone numbers with settings and merge fields are passed, but information (also array) about how many phone numbers have been added to a specific list is returned.

listBatchSubscribeSMS(string $id, array $batch, boolean $update_existing) : struct

Input parameters

• id - list ID
• batch - array of phone numbers. Each phone number is represented as an array where field names are taken from merge fields and their appropriate values are set. Important
  Merge field type where phone numbers will reside, must be set to SMS type.
  Phone numbers need to be prefixed with international country code.
• update_existing - whether existing emails will be restored (true, false) (optional). Default value is false.

Information obtained

Array consisting of:

• success_count - number of successfully added phone numbers
• error_count - number of unsuccessfully added phone numbers
• errors - array of error messages about each phone number. Each error message is represented as an array consisting of fields:
  • code - error code
  • message - error message
  • phone - phone number that raised error

Examples

mgapi_listBatchSubscribeSMS.php

 $my_phone, 'FNAME' => 'Joe');
$batch[] = array('SMS' => $boss_phone, 'FNAME' => 'Boss');
$update_existing = false;
 
$retval = $api->listBatchSubscribeSMS($id, $batch, $update_existing);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load listBatchSubscribeSMS()!\n";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "success:" . $retval['success_count'] . "\n";
    echo "errors:" . $retval['error_count'] . "\n";
    foreach ($retval['errors'] as $val) {
        echo "\t*" . $val['phone'] . " failed\n";
        echo "\tcode:" . $val['code'] . "\n";
        echo "\tmsg :" . $val['message'] . "\n\n";
    }
}

listBatchUnsubscribeSMS()

Phone numbers from the selected list are deleted. Array of recipients’ phone numbers with additional parameters are passed, which determine whether a notification about phone number removal will or will not be sent.

listBatchUnsubscribeSMS(string $id, array $phones, boolean $delete_member, boolean $send_notify) : struct

Input parameters

• id - list ID
• phones - array of phone numbers
• delete_member - whether recipient is deleted from existing list (true, false) (optional). Default value is false.
• send_notify - whether notification is sent to sender email which is indicated for a particular list (true, false) (optional). Default value is false.

Information obtained

Array consisting of:

• success_count - number of successfully removed phone numbers
• error_count - number of unsuccessfully removed phone numbers
• errors - array of error messages about each phone number. Each error message is represented as an array consisting of fields:
  • code - error code
  • message - error message
  • phone - phone number that raised error

Examples

mgapi_listBatchUnsubscribeSMS.php

listBatchUnsubscribeSMS($id, $phones, $delete_member, $send_notify);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load listBatchUnsubscribeSMS()!\n";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "success:" . $retval['success_count'] . "\n";
    echo "errors:" . $retval['error_count'] . "\n";
    foreach ($retval['errors'] as $val) {
        echo "\t*" . $val['phone'] . " failed\n";
        echo "\tcode:" . $val['code'] . "\n";
        echo "\tmsg :" . $val['message'] . "\n\n";
    }
}

listUpdateMember()

Email or merge fields of this email is updated. Appropriate entry of recipient can be found both by e-mail and merge fields.

listUpdateMember(string $id, string $email_address, array $merge_vars, string $email_type) : boolean

Input parameters

• id - list ID
• email_address - email address or ID (can be found by listMemberInfo function, see Obtaining additional email information)
• merge_vars - merge fields (array)
• Merge fields are: FNAME, LNAME, EMAIL and other your defined fields. 
• email_type - type of email (HMTL, plain) (optional). Default value is empty string.

Information obtained

• true if request for updating email or merge field has succeeded

Examples

mgapi_listUpdateMember.php

 'Richard', "LNAME" => 'Wright');
$email_type = 'html';
 
$retval = $api->listUpdateMember($id, $email_address, $merge_vars, $email_type);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load listUpdateMember()!\n";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "Returned: " . $retval . "\n";
}

xml-rpc_listUpdateMember.php

 new xmlrpcval($apikey),
            'id' => new xmlrpcval($listId),
            'email_address' => new xmlrpcval($my_email),
            'merge_vars' => php_xmlrpc_encode(
                    array("FNAME" => 'Richard', "LNAME" => 'Wright')
            ),
            'email_type' => new xmlrpcval('html')
                ),
                'struct');
$f = new xmlrpcmsg('listUpdateMember', array($v));
$c = new xmlrpc_client($apiUrl["path"], $apiUrl['host'], 80);
$c->setDebug($debug);
$r = &$c->send($f);
 
header("Content-Type: text/plain");
if (!$r->faultCode()) {
    $retval = php_xmlrpc_decode($r->value());
    echo "Returned: " . $retval . "\n";
} else {
    echo "Unable to load listUpdateMember()!\n";
    echo "\tCode=" . $r->faultCode() . "\n";
    echo "\tMsg=" . $r->faultString() . "\n";
}

mgapi_listUpdateMember.py

from lib.config import * #contains apikey
from lib.MGAPI import MGAPI
 
# This Example shows how to ping using the MGAPI.php class and do some basic error checking.
 
api = MGAPI(apikey)
 
id = listId
email_address = my_email
merge_vars = {"FNAME": 'Richard', "LNAME": 'Wright'}
email_type = 'html'
 
retval = api.listUpdateMember(id, email_address, merge_vars, email_type)
if api.errorCode:
    print "Unable to load listUpdateMember()!"
    print "\tCode=", api.errorCode
    print "\tMsg=", api.errorMessage
else:
    print "Returned: ", retval

listMembers()

By sending a request that contains list ID and email settings, you can obtain emails of this list (array).

listMembers(string $id, string $status, integer $start, integer $limit) : array

Input parameters

• id - list ID
• status - email status (unsubscribed, inactive, bounced, subscribed) (optional). Default value is subscribed.
• start - page number starting from which selection will be made (optional). Default value is 0.
• limit - number of results returned in one page (optional). Default value is 100. Maximum allowable value is 15000.

Information obtained

Array of members. Each member is represented as an array consisting of:

• id - email ID
• email - email address
• timestamp - date of adding email to the list in timestamp format

Examples

mgapi_listMembers.php

listMembers($id, $status, $start, $limit);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load listMembers()!";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "Members returned: " . sizeof($retval) . "\n";
    foreach ($retval as $member) {
        echo "\t" . $member['email'] . " - " . $member['timestamp'] . "\n";
    }
}

xml-rpc_listMembers.php

 new xmlrpcval($apikey),
                    'id' => new xmlrpcval($listId),
                    'status' => new xmlrpcval('subscribed'),
                    'start' => new xmlrpcval(0),
                    'limit' => new xmlrpcval(500)
                ),
                'struct');
$f = new xmlrpcmsg('listMembers', array($v));
$c = new xmlrpc_client($apiUrl["path"], $apiUrl['host'], 80);
$c->setDebug($debug);
$r = &$c->send($f);
 
header("Content-Type: text/plain");
if (!$r->faultCode()) {
    $retval = php_xmlrpc_decode($r->value());
    echo "Members returned: " . sizeof($retval) . "\n";
    foreach ($retval as $member) {
        echo "\t" . $member['email'] . " - " . $member['timestamp'] . "\n";
    }
} else {
    echo "Unable to run listMembers()!\n";
    echo "\tCode=" . $r->faultCode() . "\n";
    echo "\tMsg=" . $r->faultString() . "\n";
}

mgapi_listMembers.py

from lib.config import * #contains apikey
from lib.MGAPI import MGAPI
 
# This Example shows how to ping using the MGAPI.php class and do some basic error checking.
 
api = MGAPI(apikey)
 
id = listId
status = "subscribed"
start = 0
limit = 500
 
retval = api.listMembers(id, status, start, limit)
if api.errorCode:
    print "Unable to load listMembers()!"
    print "\tCode=", api.errorCode
    print "\tMsg=", api.errorMessage
else:
    print "Members returned: ", len(retval)
    if isinstance(retval, dict):
        for member in retval.items():
            print "\t%s - %s" % (member['email'], member['timestamp'])
    elif isinstance(retval, list):
        for member in retval:
            print "\t%s - %s" % (member['email'], member['timestamp'])

listMembersByMerge()

You can obtain collection of emails (array) for a specific list by performing a search with given merge field value.

listMembersByMerge(string $id, string $merge_var, string $merge_value, string $status, integer $start, integer $limit) : array

Input parameters

• id - list ID
• merge_var - name of the merge field to use in a search.
• merge_value - exact value that given merge field holds. Empty value is used by default.
• status - email status (unsubscribed, inactive, bounced, subscribed) (optional). Default value is subscribed.
• start - page number starting from which selection will be made (optional). Default value is 0.
• limit - number of results returned in one page (optional). Default value is 25. Maximum allowable value is 15000.

Information obtained

Array of members. Each member is represented as an array consisting of:

• id - ID of the email address
• email - email address
• timestamp - date of adding email to the list in timestamp format

Examples

mgapi_listMembersByMerge.php

<?php
/**
 * This Example shows how to listMembersByMerge using the MGAPI.php class and do some basic error checking.
 */
require_once 'inc/MGAPI.class.php';
require_once 'inc/config.inc.php'; //contains apikey
 
$api = new MGAPI($apikey);
 
$id = $listId;
$merge_var = "FNAME";
$merge_value = "Fname";
$status = "subscribed";
$start = 0;
$limit = 500;
 
$retval = $api->listMembersByMerge($id, $merge_var, $merge_value, $status, $start, $limit);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load listMembersByMerge()!";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "Members returned: " . sizeof($retval) . "\n";
    foreach ($retval as $member) {
        echo "\t" . $member['email'] . " - " . $member['timestamp'] . "\n";
    }
}

listMemberInfo()

By sending a request that contains list ID and email address, you can obtain full information about the email of a specific recipient.

listMemberInfo(string $id, string $email_address) : array

Input parameters

• id - list ID
• email_address - email address or email ID

Information obtained

Information about email (array):

• id - email ID
• email - email address
• email_type - email type (HTML, plain text)
• merges - merge fields with appropriate values assigned to given recipient. Array consisting of key-value pairs where array key is a merge tag and key value represents assigned merge tag value for given recipient.
• status - email status (inactive, subscribed, unsubscribed, bounced)
• ip_opt - IP address of sign-up approval
• ip_signup - IP address of sign-up initialization
• timestamp - time of email added to list in timestamp format

Examples

mgapi_listMemberInfo.php

listMemberInfo($id, $email_address);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load listMemberInfo()!\n";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    foreach ($retval as $k => $v) {
        if (is_array($v)) {
            //handle the merges
            foreach ($v as $l => $w) {
                echo "\t$l = $w\n";
            }
        } else {
            echo "$k = $v\n";
        }
    }
}

xml-rpc_listMemberInfo.php

 new xmlrpcval($apikey),
                    'id' => new xmlrpcval($listId),
                    'email_address' => new xmlrpcval($my_email)
                ),
                'struct');
$f = new xmlrpcmsg('listMemberInfo', array($v));
$c = new xmlrpc_client($apiUrl["path"], $apiUrl['host'], 80);
$c->setDebug($debug);
$r = &$c->send($f);
 
header("Content-Type: text/plain");
if (!$r->faultCode()) {
    $retval = php_xmlrpc_decode($r->value());
    foreach ($retval as $k => $v) {
        if (is_array($v)) {
            //handle the merges
            foreach ($v as $l => $w) {
                echo "\t$l = $w\n";
            }
        } else {
            echo "$k = $v\n";
        }
    }
} else {
    echo "Unable to run listMemberInfo()!\n";
    echo "\tCode=" . $r->faultCode() . "\n";
    echo "\tMsg=" . $r->faultString() . "\n";
}

mgapi_listMemberInfo.py

from lib.config import * #contains apikey
from lib.MGAPI import MGAPI
 
# This Example shows how to ping using the MGAPI.php class and do some basic error checking.
 
api = MGAPI(apikey)
 
id = listId
email_address = my_email
 
retval = api.listMemberInfo(id, email_address)
if api.errorCode:
    print "Unable to load listMemberInfo()!"
    print "\tCode=", api.errorCode
    print "\tMsg=", api.errorMessage
else:
    for k,v in retval.items():
        if isinstance(v, dict):
            #handle the merges
            for l,w in v.items():
                print "\t", l, " = ", w
        elif isinstance(v, list):
            #handle the merges
            for l,w in enumerate(v):
                print "\t", l, " = ", w
        else:
            print k, " = ", v

listGrowthHistory()

Information about lists is obtained, divided by specific time intervals. Information is returned about number of emails at the beginning of the given time interval and growth of emails during given time interval.

listGrowthHistory(string $id, string $split_by, string $start_date, string $end_date, integer $start, integer $limit) : array

Input parameters

• id - list ID
• split_by - Statistics divided by periods of time: month, week, day (optional). Default is month.
• start_date - Filter statistics from given start date. Date should be in YYYY-MM-DD format.
  Parameter end_date should be provided together with parameter start_date.
• end_date - Filter statistics till given end date. Date should be in YYYY-MM-DD format.
  Parameter start_date should be provided together with parameter end_date.
• start - page number starting from which selection will be made (optional). Default value is 0.
• limit - number of results returned in one page (optional). Default value is 25. Maximum allowed value is 100.

Information obtained

Array of statistical information split by given time intervals. Each interval is represented as an array that includes:

• according to given split_by parameter value one of following is returned:
  • month - year and month in YYYY-MM format
  • week - year, month and week returned in YYYY-MM \WW format First W is escaped prefix letter "W" before week number. Second W is a week number of year (01..53). Weeks starting from Monday. E.g. 2015-09 W36 - september, the 36th week in the year 2015.
  • day - year, month and day returned in YYYY-MM-DD format
• existing - number of emails at the beginning of given period of time
• imports - how many emails of new recipients have been added during the given period of time

Examples

mgapi_listBatchSubscribe.php

 $my_email, 'FNAME' => 'Joe');
$batch[] = array('EMAIL' => $boss_man_email, 'FNAME' => 'Boss');
$double_optin = true;
$update_existing = false;
 
$retval = $api->listBatchSubscribe($id, $batch, $double_optin, $update_existing);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load listBatchSubscribe()!\n";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "success:" . $retval['success_count'] . "\n";
    echo "errors:" . $retval['error_count'] . "\n";
    foreach ($retval['errors'] as $val) {
        echo "\t*" . $val['email'] . " failed\n";
        echo "\tcode:" . $val['code'] . "\n";
        echo "\tmsg :" . $val['message'] . "\n\n";
    }
}

xml-rpc_listBatchSubscribe.php

 new xmlrpcval($apikey),
                    'id' => new xmlrpcval($listId),
                    'batch' => php_xmlrpc_encode(
                            array(
                                array('EMAIL' => $my_email, 'FNAME' => 'Joe'),
                                array('EMAIL' => $boss_man_email, 'FNAME' => 'Boss')
                            )
                    ),
                    'double_optin' => new xmlrpcval(true),
                    'update_existing' => new xmlrpcval(false)
                ),
                'struct');
$f = new xmlrpcmsg('listBatchSubscribe', array($v));
$c = new xmlrpc_client($apiUrl["path"], $apiUrl['host'], 80);
$c->setDebug($debug);
$r = &$c->send($f);
 
header("Content-Type: text/plain");
if (!$r->faultCode()) {
    $retval = php_xmlrpc_decode($r->value());
    echo "success:" . $retval['success_count'] . "\n";
    echo "errors:" . $retval['error_count'] . "\n";
    foreach ($retval['errors'] as $val) {
        echo "\t*" . $val['email'] . " failed\n";
        echo "\tcode:" . $val['code'] . "\n";
        echo "\tmsg :" . $val['message'] . "\n\n";
    }
} else {
    echo "Unable to load listBatchSubscribe()!";
    echo "\tCode=" . $r->faultCode() . "\n";
    echo "\tMsg=" . $r->faultString() . "\n";
}

mgapi_listBatchSubscribe.py

from lib.config import * #contains apikey
from lib.MGAPI import MGAPI
 
# This Example shows how to ping using the MGAPI.php class and do some basic error checking.
 
api = MGAPI(apikey)
 
id = listId
batch = []
batch.append({'EMAIL': my_email, 'FNAME': 'Joe'})
batch.append({'EMAIL': boss_man_email, 'FNAME': 'Boss'})
double_optin = True
update_existing = False
 
retval = api.listBatchSubscribe(id, batch, double_optin, update_existing)
if api.errorCode:
    print "Unable to load listBatchSubscribe()!"
    print "\tCode=", api.errorCode
    print "\tMsg=", api.errorMessage
else:
    print "success:", retval['success_count']
    print "errors:", retval['error_count']
    for val in retval['errors']:
        print "\t*", val['email'], " failed"
        print "\tcode:", val['code']
        print "\tmsg :", val['message']

listsForEmail()

Information with email address is passed on the server, and search in lists for a particular email is performed. The whole array of all these lists is returned.

listsForEmail(string $email_address) : array

Input parameters

• email_address - email address

Information obtained

Array consisting of:

• List (array) of list IDs

Examples

mgapi_listsForEmail.php

listsForEmail($email_address);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to get lists ID!\n";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "Returned:\n";
    foreach ($retval as $id) {
        echo "\tID = " . $id . "\n";
    }
}

xml-rpc_listsForEmail.php

 new xmlrpcval($apikey),
                    'email_address' => new xmlrpcval($my_email)
                ),
                'struct');
$f = new xmlrpcmsg('listsForEmail', array($v));
$c = new xmlrpc_client($apiUrl["path"], $apiUrl['host'], 80);
$c->setDebug($debug);
$r = &$c->send($f);
 
header("Content-Type: text/plain");
if (!$r->faultCode()) {
    $retval = php_xmlrpc_decode($r->value());
    echo "Returned:\n";
    foreach ($retval as $id) {
        echo "\tid = " . $id . "\n";
    }
} else {
    echo "Unable to get lists ID!\n";
    echo "\tCode=" . $r->faultCode() . "\n";
    echo "\tMsg=" . $r->faultString() . "\n";
}

mgapi_listsForEmail.py

from lib.config import * #contains apikey
from lib.MGAPI import MGAPI
 
# This Example shows how to ping using the MGAPI.php class and do some basic error checking.
 
api = MGAPI(apikey)
 
email_address = my_email
 
retval = api.listsForEmail(email_address)
if api.errorCode:
    print "Unable to get lists ID!"
    print "\tCode=", api.errorCode
    print "\tMsg=", api.errorMessage
else:
    print "Returned: "
    if isinstance(retval, dict):
        for id in retval.items():
            print "\tID = ", id
    elif isinstance(retval, list):
        for id in retval:
            print "\tID = ", id

listSegments()

List of all segments is obtained.

listSegments(string $id) : struct

Input parameters

• id - list ID that the segment is based on

Information obtained

Array of segments. Each segment is represented as an array that includes:

• id - segment ID that is used in other API functions
• web_id - segment ID that is used in the administration page. This value is also used when creating a new SMS campaign.
• name - name of segment
• date_created - date of segment creation
• member_count - number of emails in segment

Examples

mgapi_listSegments.php

listSegments($id);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load listSegments()!";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "List Segments returned: " . sizeof($retval) . "\n";
    foreach ($retval as $segment) {
        echo "Id = " . $segment['id'] . " - " . $segment['name'] . "\n";
    }
}

listSegmentMembers()

List of all segment members is obtained.

listSegmentMembers(integer $id, string $status, integer $start, integer $limit) : array

Input parameters

• id - segment ID
• status - email status (unsubscribed, inactive, bounced, subscribed) (optional). Default value is subscribed.
• start - page number starting from which selection will be made (optional). Default value is 0.
• limit - number of results returned in one page (optional). Default value is 100. Maximum allowable value is 15000.

Information obtained

Array of members. Each member is represented as an array consisting of:

• id - member ID
• list - list ID
• email - email address
• timestamp - date of adding email to the list in timestamp format

Examples

mgapi_listSegmentMembers.php

listSegmentMembers($id, $status, $start, $limit);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load listSegmentMembers()!";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "Members returned: ". sizeof($retval). "\n";
    foreach ($retval as $segment) {
        echo "\t".$member['email']." - ".$member['timestamp']."\n";
    }
}

listSegmentCreate()

New segment is created for a given single list. You may add multiple rules to filter out contacts in your list by merge field values. Provide match type to match all or any of given rules.

listSegmentCreate(string $list, string $title, string $match, array $filter, boolean $auto_update) : string

Input parameters

• list - list ID that the segment will be based on
• title - name of the segment
• match - match type (AND, OR) to be used when chaining together multiple filter rules
• filter - list (array) of rules to filter out contacts. Every rule is an array consisting of:
  • field - merge field tag
  • condition - condition name (is, not, isany, isoneof, notoneof, contains, notcontain, starts, ends, greater, less)
  • value - value that will be used for filtering.
• auto_update - whether segment is static or updated automatically every time information about subscriber changes (true, false) (optional). Default value is false.

Information obtained

• ID of the new segment

Examples

mgapi_listSegmentCreate.php

<?php
/**
 * This Example shows how to listSegmentCreate using the MGAPI.php class and do some basic error checking.
 */
require_once 'inc/MGAPI.class.php';
require_once 'inc/config.inc.php'; //contains apikey
 
$api = new MGAPI($apikey);
 
$list = $listId;
$title = 'Test Segment';
$match = 'all'; //any, or, all, and
$filter = array(
    array(
        'field' => 'merge0',
        'condition' => 'ends', //is, not, isany, contains, notcontain, starts, ends, greater, less
        'value' => '@gmail.com',
    ),
    //...
    array(
        'field' => 'confirm_time',
        'condition' => 'greater',
        'value' => '2013-01-01',
    ),
);
$auto_update = false;

 
$retval = $api->listSegmentCreate($list, $title, $match, $filter, $auto_update);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load listSegmentCreate()!\n";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "New Segment ID:" . $retval . "\n";
}

listSegmentUpdate()

Update segment parameter, such as name, match type or filter.

listSegmentUpdate(integer $sid, string $name, string $value) : boolean

Input parameters

• id - segment ID
• name - name of the segment parameter to be updated (title, match, filter)
• value - new value of a given parameter. See listSegmentCreate for a value type of a parameter

Information obtained

• true, if uppdate was successful. Otherwise, an error message is returned.

Examples

mgapi_listSegmentUpdate.php

listSegmentUpdate($sid, $name, $value);
 
header("Content-Type: text/plain");
if ($api->errorCode){
    echo "Unable to load listSegmentUpdate()!\n";
    echo "\tCode=".$api->errorCode."\n";
    echo "\tMsg=".$api->errorMessage."\n";
} else {
    echo "SUCCESS! \n";
}

listSegmentDelete()

Segment is deleted from the database.

listSegmentDelete(string $sid) : boolean

Input parameters

• id - segment ID

Information obtained

• true if request for deleting segment has succeeded. Otherwise, an error message is returned.

Examples

mgapi_listSegmentDelete.php

listSegmentDelete($sid);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load listSegmentDelete()!\n";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "Segment Deleted!\n";
}

suppressedListMembers()

By sending a request you can obtain emails of the Global Suppression List (GSL).

suppressedListMembers(integer $start, integer $limit) : array

Input parameters

• start - page number starting from which selection will be made (optional). Default value is 0.
• limit - number of results returned in one page (optional). Default value is 25. Maximum allowable value is 15000.

Information obtained

Array of members. Each member is represented as an array consisting of:

• id - email ID
• email - email address
• timestamp - date of adding email to the Global Suppression List in timestamp format

Examples

mgapi_suppressedListMembers.php

<?php
/**
 * This Example shows how to suppressedListMembers using the MGAPI.php class and do some basic error checking.
 */
require_once 'inc/MGAPI.class.php';
require_once 'inc/config.inc.php'; //contains apikey
 
$api = new MGAPI($apikey);
 
$start = 0;
$limit = 500;
 
$retval = $api->suppressedListMembers($start, $limit);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load suppressedListMembers()!";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "Members returned: " . sizeof($retval) . "\n";
    foreach ($retval as $member) {
        echo "\t" . $member['email'] . " - " . $member['timestamp'] . "\n";
    }
}

suppressedListSubscribe()

This function adds a new email to Global Suppression List (GSL).

suppressedListSubscribe(string $email_address) : boolean

Input parametrs

• email_address - address of added email

Information obtained

• true, if request for adding new email has succeeded.

Examples

mgapi_suppressedListSubscribe.php

<?php
/**
 * This Example shows how to suppressedListSubscribe using the MGAPI.php class and do some basic error checking.
 */
require_once 'inc/MGAPI.class.php';
require_once 'inc/config.inc.php'; //contains apikey
 
$api = new MGAPI($apikey);
 
$email_address = $my_email;
 
$retval = $api->suppressedListSubscribe($email_address);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load suppressedListSubscribe()!\n";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "Returned: " . $retval . "\n";
}

suppressedListUnsubscribe()

This function removes recipient email from Global Suppression List (GSL)

suppressedListUnsubscribe(string $email_address) : boolean

Input parametrs

• email_address - email address or ID (can be found by listMemberInfo function, see Obtaining additional email information)

Information obtained

• true, if request for removing email has succeeded

Examples

mgapi_suppressedListUnsubscribe.php

<?php
/**
 * This Example shows how to suppressedListUnsubscribe using the MGAPI.php class and do some basic error checking.
 */
require_once 'inc/MGAPI.class.php';
require_once 'inc/config.inc.php'; //contains apikey
 
$api = new MGAPI($apikey);
 
$email_address = $my_email;
 
$retval = $api->suppressedListUnsubscribe($email_address);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load suppressedListUnsubscribe()!\n";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "Returned: " . $retval . "\n";
}

suppressedListBatchSubscribe()

Array of recipients’ emails are passed and information about how many emails have been added to Global Suppression List (GSL) is returned.

suppressedListBatchSubscribe(array $batch) : struct

Input parameters

• batch - array of emails. Each email is represented as an array.

Information obtained

Array consisting of:

• success_count - number of successfully added emails
• error_count - number of unsuccessfully added emails
• errors - array of error messages about each email. Each error message is represented as an array consisting of fields:
  • code - error code
  • message - error message
  • email - email address that raised error

Examples

mgapi_suppressedListBatchSubscribe.php

<?php
/**
 * This Example shows how to suppressedListBatchSubscribe using the MGAPI.php class and do some basic error checking.
 */
require_once 'inc/MGAPI.class.php';
require_once 'inc/config.inc.php'; //contains apikey
 
$api = new MGAPI($apikey);
 
$batch = array();
$batch[] = array('EMAIL' => $my_email);
$batch[] = array('EMAIL' => $boss_man_email);
 
$retval = $api->suppressedListBatchSubscribe($batch);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load suppressedListBatchSubscribe()!\n";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "success:" . $retval['success_count'] . "\n";
    echo "errors:" . $retval['error_count'] . "\n";
    foreach ($retval['errors'] as $val) {
        echo "\t*" . $val['email'] . " failed\n";
        echo "\tcode:" . $val['code'] . "\n";
        echo "\tmsg :" . $val['message'] . "\n\n";
    }
}

suppressedListBatchUnsubscribe()

Emails from the Global Suppression List (GSL) are removed. Array of recipients’ emails is passed

suppressedListBatchUnsubscribe(array $emails) : struct

Input parameters

• emails - array of emails

Information obtained

Array consisting of:

• success_count - number of successfully removed emails
• error_count - number of unsuccessfully removed emails
• errors - array of error messages about each email. Each error message is represented as an array consisting of fields:
  • code - error code
  • message - error message
  • email - email address that raised error

Examples

mgapi_suppressedListBatchUnsubscribe.php

<?php
/**
 * This Example shows how to suppressedListBatchUnsubscribe using the MGAPI.php class and do some basic error checking.
 */
require_once 'inc/MGAPI.class.php';
require_once 'inc/config.inc.php'; //contains apikey
 
$api = new MGAPI($apikey);
 
$emails = array($my_email, $boss_man_email);
 
$retval = $api->suppressedListBatchUnsubscribe($emails);
 
header("Content-Type: text/plain");
if ($api->errorCode) {
    echo "Unable to load suppressedListBatchUnsubscribe()!\n";
    echo "\tCode=" . $api->errorCode . "\n";
    echo "\tMsg=" . $api->errorMessage . "\n";
} else {
    echo "success:" . $retval['success_count'] . "\n";
    echo "errors:" . $retval['error_count'] . "\n";
    foreach ($retval['errors'] as $val) {
        echo "\t*" . $val['email'] . " failed\n";
        echo "\tcode:" . $val['code'] . "\n";
        echo "\tmsg :" . $val['message'] . "\n\n";
    }
}