Add Subscribers Through Your Own Form or Plugin using our API

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

Adding Subscriber

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 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 subscriber

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

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,
      ...
    );<br>
    	
  • (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();
}

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();
}