<?php
/**
* Your Mailing List Provider class
*
* This source file can be used to communicate with Your MailingList Provider (http://ymlp.com)
*
* The class is documented in the file itself. If you find any bugs help me out and report them. Reporting can be done by creating an issue on https://github.com/tijsverkoyen/ymlp/issues
* If you report a bug, make sure you give me enough information (include your code).
*
* Changelog since 1.0.0
* - code styling
*
* License
* Copyright (c), Tijs Verkoyen. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
* 3. The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission.
*
* This software is provided by the author "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the author be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.
*
* @author Tijs Verkoyen <php-hide@address.com>
* @version 1.0.1
*
* @copyright Copyright (c), Tijs Verkoyen. All rights reserved.
* @license BSD License
*/
class YourMailingListProvider
{
// url for the bitly-api
const API_URL = 'https://www.ymlp.com/api';
// port for the bitly-API
const API_PORT = 443;
// current version
const VERSION = '1.0.1';
/**
* The API-key that will be used for authenticating
*
* @var string
*/
private $apiKey;
/**
* The timeout
*
* @var int
*/
private $timeOut = 60;
/**
* The user agent
*
* @var string
*/
private $userAgent;
/**
* The username that will be used for authenticating
*
* @var string
*/
private $username;
// class methods
/**
* Default constructor
*
* @return void
* @param string $username The username that has to be used for authenticating.
* @param string[optional] $apiKey The API-key that has to be used for authentication.
*/
public function __construct($username, $apiKey)
{
$this->setUsername($username);
$this->setApiKey($apiKey);
}
/**
* Make the call
*
* @return mixed
* @param string $url The URL to call.
* @param array[optional] $parameters The parameters to send.
* @param string[optional] $method The method to use, possible values are: GET, POST.
* @param bool[optional] $expectJSON Do we expect JSON?
*/
private function doCall($url, array $parameters = null, $method = 'GET', $expectJSON = true)
{
// redefine
$url = (string) $url;
$method = (string) $method;
// validate
if(!in_array($method, array('GET', 'POST'))) throw new YourMailingListProviderException('Invalid method.');
// prepend
$url = self::API_URL . '/' . $url;
// set options
$options[CURLOPT_URL] = $url;
$options[CURLOPT_PORT] = self::API_PORT;
$options[CURLOPT_USERAGENT] = $this->getUserAgent();
if(ini_get('open_basedir') == '' && ini_get('safe_mode' == 'Off')) $options[CURLOPT_FOLLOWLOCATION] = true;
$options[CURLOPT_RETURNTRANSFER] = true;
$options[CURLOPT_TIMEOUT] = (int) $this->getTimeOut();
$options[CURLOPT_SSL_VERIFYPEER] = false;
$options[CURLOPT_SSL_VERIFYHOST] = false;
// add authentication stuff
$parameters['Key'] = $this->getApiKey();
$parameters['Username'] = $this->getUsername();
// add output
$parameters['Output'] = 'JSON';
// POST
if($method == 'POST')
{
// reset
$options[CURLOPT_POST] = true;
// ant parameters?
if(!empty($parameters)) $options[CURLOPT_POSTFIELDS] = $parameters;
}
// GET
else
{
// reset
$options[CURLOPT_POST] = false;
// any parameters?
if(!empty($parameters))
{
if(substr_count($url, '?') > 0) $options[CURLOPT_URL] .= '&' . http_build_query($parameters);
else $options[CURLOPT_URL] .= '?' . http_build_query($parameters);
}
}
// init
$curl = curl_init();
// set options
curl_setopt_array($curl, $options);
// execute
$response = curl_exec($curl);
$headers = curl_getinfo($curl);
// fetch errors
$errorNumber = curl_errno($curl);
$errorMessage = curl_error($curl);
// close
curl_close($curl);
// error?
if($errorNumber != '') throw new YourMailingListProviderException($errorMessage, $errorNumber);
// we don't expect JSON
if(!$expectJSON) return $response;
// we expect JSON so decode it
$json = @json_decode($response, true);
// validate json
if($json === false) throw new YourMailingListProviderException('Invalid JSON-response');
// is error?
if(isset($json['Code']) && $json['Code'] != 0) throw new YourMailingListProviderException((string) $json['Output'], (int) $json['Code']);
// return
return $json['Output'];
}
/**
* Get the APIkey
*
* @return mixed
*/
private function getApiKey()
{
return $this->apiKey;
}
/**
* Get the timeout that will be used
*
* @return int
*/
public function getTimeOut()
{
return (int) $this->timeOut;
}
/**
* Get the useragent that will be used. Our version will be prepended to yours.
* It will look like: "PHP Your Mailing List Provider/<version> <your-user-agent>"
*
* @return string
*/
public function getUserAgent()
{
return (string) 'PHP Your Mailing List Provider/' . self::VERSION . ' ' . $this->userAgent;
}
/**
* Get the username
*
* @return string
*/
private function getUsername()
{
return (string) $this->username;
}
/**
* Set the API-key that has to be used
*
* @return void
* @param string $apiKey The key to set.
*/
private function setApiKey($apiKey)
{
$this->apiKey = (string) $apiKey;
}
/**
* Set the password that has to be used
*
* @return void
* @param string $password The password to use.
*/
private function setPassword($password)
{
$this->password = (string) $password;
}
/**
* Set the timeout
* After this time the request will stop. You should handle any errors triggered by this.
*
* @return void
* @param int $seconds The timeout in seconds.
*/
public function setTimeOut($seconds)
{
$this->timeOut = (int) $seconds;
}
/**
* Set the user-agent for you application
* It will be appended to ours, the result will look like: "PHP Your Mailing List Provider/<version> <your-user-agent>"
*
* @return void
* @param string $userAgent Your user-agent, it should look like <app-name>/<app-version>.
*/
public function setUserAgent($userAgent)
{
$this->userAgent = (string) $userAgent;
}
/**
* Set the username that has to be used
*
* @return void
* @param string $username The username to use.
*/
private function setUsername($username)
{
$this->username = (string) $username;
}
// general
/**
* Ping is the simplest command, doesn't serve any useful purpose but is a great command to understand this API feature and to test your API implementation.
* When you call this command, it will return "Hello!"
*
* @return string
*/
public function ping()
{
// set url
$url = 'Ping';
// make the call
return $this->doCall($url);
}
// contacts
/**
* Adds a new contact to one or more groups in your database.
*
* @return bool
* @param string $email The emailadress.
* @param array $groups An array with the ids of the groups.
* @param array[optional] $fields An key-value-pair array, where the key is the id of the field.
* @param bool[optional] $overruleUnsubscribedBounced If true the e-mailadress will be added even if this persion previously unsubscribed or if the email address previously was removed by bounce back handling.
*/
public function contactsAdd($email, array $groups, array $fields = null, $overruleUnsubscribedBounced = false)
{
// redefine
$email = (string) $email;
$overruleUnsubscribedBounced = (bool) $overruleUnsubscribedBounced;
// set url
$url = 'Contacts.Add';
// build parameters
$parameters['Email'] = $email;
// any fields?
if(!empty($fields))
{
// loop fields and add them
foreach($fields as $id => $value) $parameters['Field' . $id] = $value;
}
// group
$parameters['GroupID'] = implode(',', $groups);
// overrule?
if($overruleUnsubscribedBounced) $parameters['OverruleUnsubscribedBounced'] = 1;
// make the call
return ($this->doCall($url, $parameters, 'POST') == $email . ' has been added');
}
/**
* Removes a given email address from one or more groups.
*
* @return bool
* @param string $email The emailadress.
* @param array $groups An array with the ids of the groups.
*/
public function contactsDelete($email, array $groups)
{
// redefine
$email = (string) $email;
// set url
$url = 'Contacts.Delete';
// build parameters
$parameters['Email'] = $email;
$parameters['GroupID'] = implode(',', $groups);
// make the call
return ($this->doCall($url, $parameters, 'POST') == $email . ' has been removed');
}
/**
* Unsubscribes a given email address.
*
* @return bool
* @param string $email The emailadress.
*/
public function contactsUnsubscribe($email)
{
// redefine
$email = (string) $email;
// set url
$url = 'Contacts.Unsubscribe';
// build parameters
$parameters['Email'] = $email;
// make the call
return ($this->doCall($url, $parameters, 'POST') == $email . ' has been unsubscribed');
}
/**
* Retrieves all available information regarding a contact.
*
* @return array
* @param string $email The emailadress.
*/
public function contactsGetContact($email)
{
// redefine
$email = (string) $email;
// set url
$url = 'Contacts.GetContact';
// build parameters
$parameters['Email'] = $email;
// make the call
return $this->doCall($url, $parameters);
}
/**
* Returns the list of contacts in a given list of groups.
*
* @return array
* @param array $groups An array with the ids of the groups.
* @param array $fields An array with the ids of the fields.
* @param int[optional] $startDate Only show contacts that were added after this date.
* @param int[optional] $stopDate Only show contacts that were added before this date.
* @param int[optional] $page ID of the result page to show.
* @param int[optional] $numberPerPage number of contacts per result page.
* @param string[optional] $sorting Sorting order of the returned email addresses, either Ascending or Descending.
*/
public function contactsGetList(array $groups, array $fields, $startDate = null, $stopDate = null, $page = null, $numberPerPage = null, $sorting = null)
{
// set url
$url = 'Contacts.GetList';
// build parameters
$parameters['GroupID'] = implode(',', $groups);
$parameters['FieldID'] = implode(',', $fields);
if($startDate !== null) $parameters['StartDate'] = date('Y-m-d', (int) $startDate);
if($stopDate !== null) $parameters['StopDate'] = date('Y-m-d', (int) $stopDate);
if($page !== null) $parameters['Page'] = (int) $page;
if($numberPerPage !== null) $parameters['NumberPerPage'] = (int) $numberPerPage;
if($sorting !== null) $parameters['sorting'] = (string) $sorting;
// make the call
return $this->doCall($url, $parameters);
}
/**
* Returns the list of unsubscribed contacts in your account.
*
* @return array
* @param array $fields An array with the ids of the fields.
* @param int[optional] $startDate Only show contacts that were added after this date.
* @param int[optional] $stopDate Only show contacts that were added before this date.
* @param int[optional] $page ID of the result page to show.
* @param int[optional] $numberPerPage number of contacts per result page.
* @param string[optional] $sorting Sorting order of the returned email addresses, either Ascending or Descending.
*/
public function contactsGetUnsubscribed(array $fields, $startDate = null, $stopDate = null, $page = null, $numberPerPage = null, $sorting = null)
{
// set url
$url = 'Contacts.GetUnsubscribed';
// build parameters
$parameters['FieldID'] = implode(',', $fields);
if($startDate !== null) $parameters['StartDate'] = date('Y-m-d', (int) $startDate);
if($stopDate !== null) $parameters['StopDate'] = date('Y-m-d', (int) $stopDate);
if($page !== null) $parameters['Page'] = (int) $page;
if($numberPerPage !== null) $parameters['NumberPerPage'] = (int) $numberPerPage;
if($sorting !== null) $parameters['sorting'] = (string) $sorting;
// make the call
return $this->doCall($url, $parameters);
}
/**
* Returns the list of manually removed contacts in your account.
*
* @return array
* @param array $fields An array with the ids of the fields.
* @param int[optional] $startDate Only show contacts that were added after this date.
* @param int[optional] $stopDate Only show contacts that were added before this date.
* @param int[optional] $page ID of the result page to show.
* @param int[optional] $numberPerPage number of contacts per result page.
* @param string[optional] $sorting Sorting order of the returned email addresses, either Ascending or Descending.
*/
public function contactsGetDeleted(array $fields, $startDate = null, $stopDate = null, $page = null, $numberPerPage = null, $sorting = null)
{
// set url
$url = 'Contacts.GetDeleted';
// build parameters
$parameters['FieldID'] = implode(',', $fields);
if($startDate !== null) $parameters['StartDate'] = date('Y-m-d', (int) $startDate);
if($stopDate !== null) $parameters['StopDate'] = date('Y-m-d', (int) $stopDate);
if($page !== null) $parameters['Page'] = (int) $page;
if($numberPerPage !== null) $parameters['NumberPerPage'] = (int) $numberPerPage;
if($sorting !== null) $parameters['sorting'] = (string) $sorting;
// make the call
return $this->doCall($url, $parameters);
}
/**
* Returns the list of contacts removed by bounce back handling in your account.
*
* @return array
* @param array $fields An array with the ids of the fields.
* @param int[optional] $startDate Only show contacts that were added after this date.
* @param int[optional] $stopDate Only show contacts that were added before this date.
* @param int[optional] $page ID of the result page to show.
* @param int[optional] $numberPerPage number of contacts per result page.
* @param string[optional] $sorting Sorting order of the returned email addresses, either Ascending or Descending.
*/
public function contactsGetBounced(array $fields, $startDate = null, $stopDate = null, $page = null, $numberPerPage = null, $sorting = null)
{
// set url
$url = 'Contacts.GetBounced';
// build parameters
$parameters['FieldID'] = implode(',', $fields);
if($startDate !== null) $parameters['StartDate'] = date('Y-m-d', (int) $startDate);
if($stopDate !== null) $parameters['StopDate'] = date('Y-m-d', (int) $stopDate);
if($page !== null) $parameters['Page'] = (int) $page;
if($numberPerPage !== null) $parameters['NumberPerPage'] = (int) $numberPerPage;
if($sorting !== null) $parameters['sorting'] = (string) $sorting;
// make the call
return $this->doCall($url, $parameters);
}
/**
* Lists the groups in your account, along with their group IDs and the number of contacts in each group.
*
* @return array
*/
public function GroupsGetList()
{
// set url
$url = 'Groups.GetList';
// make the call
return $this->doCall($url);
}
/**
* Creates a new group.
*
* @return string
* @param string $name Label to use for the new group.
*/
public function GroupsAdd($name)
{
// redefine
$name = (string) $name;
// set url
$url = 'Groups.Add';
// build parameters
$parameters['GroupName'] = $name;
// make the call
return str_replace('ID: ', '', $this->doCall($url, $parameters, 'POST'));
}
/**
* Removes a group based on a given group ID.
*
* @return bool
* @param string $id ID of the group.
*/
public function GroupsDelete($id)
{
// redefine
$id = (string) $id;
// set url
$url = 'Groups.Delete';
// build parameters
$parameters['GroupID'] = $id;
// make the call
return ($this->doCall($url, $parameters, 'POST') == 'Removed ID: ' . $id);
}
/**
* Update the properties of a group.
*
* @return bool
* @param string $id ID of teh group.
* @param string $name New label to use for this group.
*/
public function GroupsUpdate($id, $name)
{
// redefine
$id = (string) $id;
$name = (string) $name;
// set url
$url = 'Groups.Update';
// build parameters
$parameters['GroupID'] = $id;
$parameters['GroupName'] = $name;
// make the call
return ($this->doCall($url, $parameters, 'POST') == 'Updated ID: ' . $id);
}
/**
* Remove all contacts in a group.
*
* @return string
* @param string $id The id of the group.
*/
public function GroupsEmpty($id)
{
// redefine
$id = (string) $id;
// set url
$url = 'Groups.Empty';
// build parameters
$parameters['GroupID'] = $id;
// make the call
return $this->doCall($url, $parameters, 'POST');
}
/**
* Lists the fields in your account along with the field ID, the alias, the default value and the "Correct Uppercase" value for each field.
*
* @return array
*/
public function FieldsGetList()
{
// set url
$url = 'Fields.GetList';
// make the call
return $this->doCall($url);
}
/**
* Creates a new field.
*
* @return string
* @param string $name Label to use for the new field.
* @param string[optional] $alias Alias for the new field, defaults to the field name.
* @param mixed[optional] $default The default value.
* @param bool[optional] $correctUppercase Correct uppercase values?
*/
public function FieldsAdd($name, $alias = null, $default = null, $correctUppercase = false)
{
// redefine
$name = (string) $name;
$correctUppercase = (bool) $correctUppercase;
// set url
$url = 'Fields.Add';
// build parameters
$parameters['FieldName'] = $name;
if($alias !== null) $parameters['Alias'] = (string) $alias;
if($default !== null) $parameters['DefaultValue'] = $default;
if($correctUppercase) $parameters['CorreectUppercase'] = 1;
// make the call
return str_replace('ID: ', '', $this->doCall($url, $parameters, 'POST'));
}
/**
* Removes a field based on a given field ID.
*
* @return bool
* @param string $id The id of the field to delete.
*/
public function FieldsDelete($id)
{
// redefine
$id = (string) $id;
// set url
$url = 'Fields.Delete';
// build parameters
$parameters['FieldID'] = $id;
// make the call
return ($this->doCall($url, $parameters, 'POST') == 'Removed ID: ' . $id);
}
/**
* Update the properties of a field.
*
* @return bool
* @param string $id The if of the field.
* @param string[optional] $name The name of the field.
* @param string[optional] $alias The alias of the field.
* @param mixed[optional] $default The default value for the field.
* @param bool[optional] $correctUppercase Correct uppercase values?
*/
public function FieldsUpdate($id, $name = null, $alias = null, $default = null, $correctUppercase = null)
{
// redefine
$id = (string) $id;
// set url
$url = 'Fields.Update';
// build parameters
$parameters['FieldID'] = $id;
if($name !== null) $parameters['FieldName'] = (string) $name;
if($alias !== null) $parameters['Alias'] = (string) $alias;
if($default !== null) $parameters['Default'] = $default;
if($correctUppercase !== null) $parameters['CorrectUppercase'] = ((bool) $correctUppercase) ? '1' : '0';
// make the call
return ($this->doCall($url, $parameters, 'POST') == 'Updated ID: ' . $id);
}
/**
* Lists the filters in your account along with the filter ID, the filter name, the criterion description and the field-operand-value combination for each filter.
*
* @return array
* @param bool[optional] $overruleDeleted Whether or not to include deleted filters in the output.
*/
public function FiltersGetList($overruleDeleted = false)
{
// redefine
$overruleDeleted = (bool) $overruleDeleted;
// set url
$url = 'Filters.GetList';
// build parameters
if($overruleDeleted) $parameters['OverruleDeleted'] = '1';
// make the call
return $this->doCall($url, $parameters);
}
/**
* Creates a new filter.
*
* @return string
* @param string $name The name of the filter.
* @param string $field The name of the field.
* @param string $operand The operand to use.
* @param string $value The value for the filter.
*/
public function FiltersAdd($name, $field, $operand, $value)
{
// redefine
$name = (string) $name;
$field = (string) $field;
$operand = (string) $operand;
$value = (string) $value;
// set url
$url = 'Filters.Add';
// build parameters
$parameters['FilterName'] = $name;
$parameters['Field'] = $field;
$parameters['Operand'] = $operand;
$parameters['Value'] = $value;
// make the call
return str_replace('ID: ', '', $this->doCall($url, $parameters, 'POST'));
}
/**
* Removes a filter based on a given filter ID.
*
* @return bool
* @param string $id ID of the filter.
*/
public function FiltersDelete($id)
{
// redefine
$id = (string) $id;
// set url
$url = 'Filters.Delete';
// build parameters
$parameters['FilterID'] = $id;
// make the call
return $this->doCall($url, $parameters, 'POST');
}
// send messages
/**
* Returns the list of available sender addresses in the account.
*
* @return array
*/
public function newsletterGetFroms()
{
// set url
$url = 'Newsletter.GetFroms';
// make the call
return $this->doCall($url);
}
/**
* Creates a new sender address.
*
* @return string
* @param string $email The emailadress.
* @param string $name Name/description for the new sender address.
*/
public function newsletterAddFrom($email, $name)
{
// redefine
$email = (string) $email;
$name = (string) $name;
// set url
$url = 'Newsletter.AddFrom';
// build parameters
$parameters['FromEmail'] = $email;
$parameters['FromName'] = $name;
// make the call
return str_replace('ID: ', '', $this->doCall($url, $parameters, 'POST'));
}
/**
* Removes a sender address based on a given From ID.
*
* @return bool
* @param string $id The id of the from-address.
*/
public function newsletterDeleteFrom($id)
{
// redefine
$id = (string) $id;
// set url
$url = 'Newsletter.DeleteFrom';
// build parameters
$parameters['FromID'] = $id;
// make the call
return ($this->doCall($url, $parameters, 'POST') == 'Removed ID: ' . $id);
}
/**
* Queues a message for delivery.
*
* @return bool
* @param string $subject Subject for the message.
* @param string[optional] $html HTML code for the message (optional if a text part is specified).
* @param string[optional] $text Plaintext for the message (optional if a HTML part is specified).
* @param int[optional] $deliveryTime Delivery time for the message.
* @param string $fromID ID of the sender address to use, use NewsletterGetFroms() to retrieve the ID for each sender address.
* @param bool[optional] $trackOpens Whether or not to track opens for the message?
* @param bool[optional] $trackClicks Whether or not to track clicks for the message?
* @param bool[optional] $testMessage Whether it's a test message or a message to be sent to contacts in your database?
* @param array $groups ID of the group(s) to send to, use GroupsGetList() to retrieve the ID for each group (ignored for test messages).
* @param array[optional] $filters ID of the filter(s) to apply, use FiltersGetList() to retrieve the ID for each filter (ignored for test messages).
* @param bool[optional] $combineFilters Whether contacts must match all applied filters or just one?
*/
public function newsletterSend($subject, $html = null, $text = null, $deliveryTime = null, $fromID, $trackOpens = null, $trackClicks = null, $testMessage = null, array $groups, array $filters = null, $combineFilters = null)
{
// redefine
$subject = (string) $subject;
// set url
$url = 'Newsletter.Send';
// build parameters
$parameters['Subject'] = $subject;
if($html !== null) $parameters['HTML'] = (string) $html;
if($text !== null) $parameters['Text'] = (string) $text;
if($deliveryTime !== null) $parameters['DeliveryTime'] = date('Y-m-d H:m', (int) $deliveryTime);
$parameters['FromID'] = (string) $fromID;
if($trackOpens !== null && $trackOpens) $parameters['TrackOpens'] = '1';
if($trackClicks !== null && $trackClicks) $parameters['TrackClicks'] = '1';
if($testMessage !== null && $testMessage) $parameters['TestMessage'] = '1';
$parameters['GroupID'] = implode(',', $groups);
if($filters !== null) $parameters['FilterID'] = implode(',', $filters);
if($combineFilters !== null && $combineFilters) $parameters['CombineFilters'] = '1';
// make the call
return ($this->doCall($url, $parameters, 'POST') == 'Message queued for delivery');
}
// read data
/**
* Returns a list of newsletters in the archives of your account.
*
* @return array
* @param int[optional] $page ID of the result page to show.
* @param int[optional] $numberPerPage Number of newsletters per result page.
* @param int[optional] $startDate Only return newsletters that were sent after this date.
* @param int[optional] $stopDate Only return newsletters that were sent before this date.
* @param string[optional] $sorting Sorting order of the returned newsletters, either Ascending or Descending.
* @param bool[optional] $showTestMessages Whether or not to include test messages in the output.
*/
public function archiveGetList($page = null, $numberPerPage = null, $startDate = null, $stopDate = null, $sorting = null, $showTestMessages = null)
{
// set url
$url = 'Archive.GetList';
// build parameters
if($page !== null) $parameter['Page'] = (int) $page;
if($numberPerPage !== null) $parameters['NumberPerPage'] = (int) $numberPerPage;
if($startDate !== null) $parameters['StartDate'] = date('Y-m-d', (int) $startDate);
if($stopDate !== null) $parameters['StopDate'] = date('Y-m-d', (int) $stopDate);
if($sorting !== null) $parameters['Sorting'] = (string) $sorting;
if($showTestMessages !== null && $showTestMessages) $parameters['ShowtestMessages'] = '1';
// make the call
return $this->doCall($url, $parameters);
}
/**
* Returns all available information regarding a newsletter, except for its content.
*
* @return array
* @param string $id ID of the Newsletter.
*/
public function archiveGetSummary($id)
{
// redefine
$id = (string) $id;
// set url
$url = 'Archive.GetSummary';
// build parameters
$parameters['NewsletterID'] = $id;
// make the call
return $this->doCall($url, $parameters);
}
/**
* Returns the list of email addresses a newsletter was sent to.
*
* @return array
* @param string $id ID of the Newsletter.
* @param int[optional] $page ID of the result page to show.
* @param int[optional] $numberPerPage Number of email addresses per result page.
* @param string[optional] $sorting Sorting order of the returned email addresses, either Ascending or Descending.
*/
public function archiveGetRecipients($id, $page = null, $numberPerPage, $sorting = null)
{
// redefine
$id = (string) $id;
// set url
$url = 'Archive.GetRecipients';
// build parameters
$parameters['NewsletterID'] = $id;
if($page !== null) $parameters['Page'] = (int) $page;
if($numberPerPage !== null) $parameters['NumberPerPage'] = (int) $numberPerPage;
if($sorting !== null) $parameters['Sorting'] = (string) $sorting;
// make the call
return $this->doCall($url, $parameters);
}
/**
* Returns the list of email addresses a newsletter was successfully delivered to.
*
* @return array
* @param string $id ID of the Newsletter.
* @param int[optional] $page ID of the result page to show.
* @param int[optional] $numberPerPage Number of email addresses per result page.
* @param string[optional] $sorting Sorting order of the returned email addresses, either Ascending or Descending.
*/
public function archiveGetDelivered($id, $page = null, $numberPerPage, $sorting = null)
{
// set url
$url = 'Archive.GetDelivered';
// build parameters
$parameters['NewsletterID'] = $id;
if($page !== null) $parameters['Page'] = (int) $page;
if($numberPerPage !== null) $parameters['NumberPerPage'] = (int) $numberPerPage;
if($sorting !== null) $parameters['Sorting'] = (string) $sorting;
// make the call
return $this->doCall($url, $parameters);
}
/**
* Returns the bouncebacks for a newsletter.
*
* @return array
* @param string $id ID of the Newsletter.
* @param bool[optional] $showHardBounces Whether to include email addresses that returned a permanent error or "hard" bounceback.
* @param bool[optional] $showSoftBounces Whether to include email addresses that returned a temporary error or "soft" bounceback.
* @param int[optional] $page ID of the result page to show.
* @param int[optional] $numberPerPage Number of email addresses per result page.
* @param string[optional] $sorting Sorting order of the returned email addresses, either Ascending or Descending.
*/
public function archiveGetBounces($id, $showHardBounces = null, $showSoftBounces = null, $page = null, $numberPerPage, $sorting = null)
{
// redefine
$id = (string) $id;
// set url
$url = 'Archive.GetBounces';
// build parameters
$parameters['NewsletterID'] = $id;
if($showHardBounces !== null && $showHardBounces) $parameters['ShowHardBounces'] = '1';
if($showSoftBounces !== null && $showSoftBounces) $parameters['ShowSoftBounces'] = '1';
if($page !== null) $parameters['Page'] = (int) $page;
if($numberPerPage !== null) $parameters['NumberPerPage'] = (int) $numberPerPage;
if($sorting !== null) $parameters['Sorting'] = (string) $sorting;
// make the call
return $this->doCall($url, $parameters);
}
/**
* Returns the list of email addresses that opened a newsletter.
*
* @return array
* @param string $id ID of the Newsletter.
* @param bool[optional] $showUniqueOpens Whether or not to list only the first open from an email address, if that email address opened multiple times.
* @param int[optional] $page ID of the result page to show.
* @param int[optional] $numberPerPage Number of email addresses per result page.
* @param string[optional] $sorting Sorting order of the returned email addresses, either Ascending or Descending.
*/
public function archiveGetOpens($id, $showUniqueOpens = null, $page = null, $numberPerPage, $sorting = null)
{
// set url
$url = 'Archive.GetOpens';
// build parameters
$parameters['NewsletterID'] = $id;
if($showUniqueOpens !== null && $showUniqueOpens) $parameters['UniqueOpens'] = '1';
if($page !== null) $parameters['Page'] = (int) $page;
if($numberPerPage !== null) $parameters['NumberPerPage'] = (int) $numberPerPage;
if($sorting !== null) $parameters['Sorting'] = (string) $sorting;
// make the call
return $this->doCall($url, $parameters);
}
/**
* Returns the list of email addresses that opened a newsletter.
*
* @return array
* @param string $id ID of the Newsletter.
* @param int[optional] $page ID of the result page to show.
* @param int[optional] $numberPerPage Number of email addresses per result page.
* @param string[optional] $sorting Sorting order of the returned email addresses, either Ascending or Descending.
*/
public function archiveGetUnopened($id, $page = null, $numberPerPage, $sorting = null)
{
// redefine
$id = (string) $id;
// set url
$url = 'Archive.GetUnopened';
// build parameters
$parameters['NewsletterID'] = $id;
if($page !== null) $parameters['Page'] = (int) $page;
if($numberPerPage !== null) $parameters['NumberPerPage'] = (int) $numberPerPage;
if($sorting !== null) $parameters['Sorting'] = (string) $sorting;
// make the call
return $this->doCall($url, $parameters);
}
/**
* Returns the list of tracked links for a newsletter that was sent with click tracking.
*
* @return array
* @param string $id ID of the Newsletter.
*/
public function archiveGetTrackedLinks($id)
{
// redefine
$id = (string) $id;
// set url
$url = 'Archive.GetTrackedLinks';
// build parameters
$parameters['NewsletterID'] = $id;
// make the call
return $this->doCall($url, $parameters);
}
/**
* Returns the list of clicks for a newsletter that was sent with click tracking, either for all links in the newsletter or for a given link.
*
* @return array
* @param string $id ID of the Newsletter.
* @param string[optional] $linkId ID of a link if you want to limit the results to the clicks on a particular link.
* @param bool[optional] $showUniqueClicks Whether or not to list only the first click from an email address, if that email address clicked multiple times.
* @param int[optional] $page ID of the result page to show.
* @param int[optional] $numberPerPage Number of email addresses per result page.
* @param string[optional] $sorting Sorting order of the returned email addresses, either Ascending or Descending.
*/
public function archiveGetClicks($id, $linkId = null, $showUniqueClicks = null, $page = null, $numberPerPage, $sorting = null)
{
// set url
$url = 'Archive.GetClicks';
// build parameters
$parameters['NewsletterID'] = $id;
if($linkId !== null) $parameters['LinkID'] = (string) $linkId;
if($showUniqueClicks !== null && $showUniqueClicks) $parameters['UniqueClicks'] = '1';
if($page !== null) $parameters['Page'] = (int) $page;
if($numberPerPage !== null) $parameters['NumberPerPage'] = (int) $numberPerPage;
if($sorting !== null) $parameters['Sorting'] = (string) $sorting;
// make the call
return $this->doCall($url, $parameters);
}
/**
* Returns the list of forwards for a newsletter.
*
* @return array
* @param string $id ID of the Newsletter.
* @param int[optional] $page ID of the result page to show.
* @param int[optional] $numberPerPage Number of email addresses per result page.
* @param string[optional] $sorting Sorting order of the returned email addresses, either Ascending or Descending.
*/
public function archiveGetForwards($id, $page = null, $numberPerPage, $sorting = null)
{
// set url
$url = 'Archive.GetForwards';
// build parameters
$parameters['NewsletterID'] = $id;
if($page !== null) $parameters['Page'] = (int) $page;
if($numberPerPage !== null) $parameters['NumberPerPage'] = (int) $numberPerPage;
if($sorting !== null) $parameters['Sorting'] = (string) $sorting;
// make the call
return $this->doCall($url, $parameters);
}
}
/**
* YourMailingListProvider Exception class
*
* @author Tijs Verkoyen <php-hide@address.com>
*/
class YourMailingListProviderException extends Exception
{
}
?>