Using API to manage subscribers and lists

If you wish to manage subscribers and lists via a custom form or you are a third-party plugin author looking to integrate with MailPoet, our public API makes it easy.

Lists
Subscribers

Lists

Getting available subscription lists

$subscription_lists = \MailPoet\API\API::MP('v1')->getLists();

This will return a two-dimensional array with the following format:

array(
  array(
    'id' => 1
    'name' => "List 1"
    'type' => "default"
    'description' => "List 1 description..."
    'created_at' => "2017-05-18 01:01:29"
    'updated_at' => "2017-05-18 01:01:29"
    'deleted_at' => NULL
  ),
  array(
    'id' => 2
    'name' => "List 2"
    'type' => "default"
    'description' => "List 2 description..."
    'created_at' => "2017-05-18 01:01:29"
    'updated_at' => "2017-05-18 01:01:29"
    'deleted_at' => NULL
  ),
  ...
);

Adding List

addList() method allows you to create a new list and accepts a one-dimensional array as a parameter with list name (required) and description (optional). The method returns an array with list data or throws an exception with one of the following error messages: List name is requiredThis list already existsFailed to add list: <error message>.

try {
  $list_data = array(
    'name' => 'Custom List', // required
    'description' => 'List created via API' //
  );
  $list = \MailPoet\API\API::MP('v1')->addList($list_data);
} catch(Exception $exception) {
  // return $exception->getMessage();
}

Subscribing to List(s)

subscribeToList() and subscribeToLists() methods allow you to subscribe to one or multiple lists, respectively. Both methods return an array with subscriber data or throw an exception with one of the following error messages: This subscriber does not exist, These lists do not existCan't subscribe to a WordPress Users list <id>, Lists with ID <ids> do not exist

Single List
$subscriber = "test@example.com"; // you can also pass a subscriber ID
$list = 1; // you can get available list IDs by using the \MailPoet\API\API::MP('v1')->getLists(); method

try {
  $subscriber = \MailPoet\API\API::MP('v1')->subscribeToList($subscriber, $list); 
} catch(Exception $exception) {
  // return $exception->getMessage();
}
Multiple Lists
$subscriber = "test@example.com"; // you can also pass a subscriber ID
$lists = array(
 1,
 2
); // you can get available list IDs by using the \MailPoet\API\API::MP('v1')->getLists(); method

try {
  $subscriber = \MailPoet\API\API::MP('v1')->subscribeToLists($subscriber, $lists); 
} catch(Exception $exception) {
  // return $exception->getMessage();
}

Unsubscribing from List(s)

unsubscribeFromList() and unsubscribeFromLists() methods allow you to unsubscribe from one or multiple lists, respectively. Both methods return an array with subscriber data or throw an exception with one of the following error messages: This subscriber does not exist, At least one segment ID is requiredThis subscriber does not exist, This list does not exist,Can't subscribe to a WordPress Users list with ID %d, List with ID %s does not exist.

Single List
$subscriber = "test@example.com"; // you can also pass a subscriber ID
$list = 1; // you can get available list IDs by using the \MailPoet\API\API::MP('v1')->getLists(); method

try {
  $subscriber = \MailPoet\API\API::MP('v1')->unsubscribeFromList($subscriber, $list); 
} catch(Exception $exception) {
  // return $exception->getMessage();
}
Multiple Lists
$subscriber = "test@example.com"; // you can also pass a subscriber ID
$lists = array(
 1,
 2
); // you can get available list IDs by using the \MailPoet\API\API::MP('v1')->getLists(); method

try {
  $subscriber = \MailPoet\API\API::MP('v1')->unsubscribeFromList($subscriber, $lists); 
} catch(Exception $exception) {
  // return $exception->getMessage();
}

Subscribers

Getting available subscriber fields

$subscriber_fields = \MailPoet\API\API::MP('v1')->getSubscriberFields();

This will return an array with field IDs names:

array(
  'email' => 'Email',
  'first_name' => 'First Name', 
  'last_name' => 'Last Name',
  'cf_1' => 'Your custom field',
  ...
);

Getting Subscriber

getSubscriber() method allows you to get subscriber by ID or e-mail. The method returns an array with subscriber data or throws an exception the the This subscriber does not exist error message.

try {
  $subscriber = \MailPoet\API\API::MP('v1')->getSubscriber($identifier); // $identifier can be either a subscriber ID or e-mail
} catch(Exception $exception) {
  // return $exception->getMessage();
}

Adding subscriber

try {
  $subscriber = \MailPoet\API\API::MP('v1')->addSubscriber($subscriber_data, $lists, $options);
} catch(Exception $exception) {
  // return $exception->getMessage();
}

The addSubscriber() method accepts 3 parameters.

  • (required) Subscriber data is a one-dimensional array of subscriber field IDs and values:

    $subscriber_data = array(
      'email' => 'test@example.com',
      'first_name' => 'John',
      'last_name' => 'Doe',
      'cf_1' => 'Custom field',
      ...
    );
  • (optional) Lists is a one-dimensional array of list IDs:

    $lists = array(
      1,
      2,
      ...
    );
  • (optional) Options is a one-dimensional array of option names and values:

    $options = array(
      'send_confirmation_email' => false // default: true
      'schedule_welcome_email' => false // default: true
    );	

The method returns an array with subscriber data or throw an exception with one of the following error messages. Should the action fail, an exception with one of the following error messages will be thrown: Subscriber email address is required, This subscriber already exists, Failed to add subscriber: <reason>.

Putting it all together

HTML form:

<form action="<URL OF THE PAGE WHERE FORM DATA IS SENT TO>" method="POST">
    <input name="email" type="text" required placeholder="Email address">
    <input name="first_name" type="text" placeholder="First name">
    <input name="last_name" type="text" placeholder="Last name">
    <input type="checkbox" name="lists[]" value="1"/>List 1<br/>
    <input type="checkbox" name="lists[]" value="2"/>List 2<br/>
    <input value="Subscribe!" type="submit">
</form>

PHP script:

$subscriber_data = array(
  'email' => sanitize_text_field($_POST['email']),
  'first_name' => sanitize_text_field($_POST['first_name']),
  'last_name' => sanitize_text_field($_POST['first_name'])
);

$lists = array_map('intval', $_POST['lists']);

try {
  $subscriber = \MailPoet\API\API::MP('v1')->addSubscriber($subscriber_data, $lists, $options);
} catch(Exception $exception) {
  // return $exception->getMessage();
}