Subscribers

Adding a subscriber

POST https://api.mailersoft.com/api/v1/subscribers/{list_id}/

Adds a subscriber to an existing subscriber list, including custom field data if supplied. If the subscriber (email address) already exists, their name and any custom field values are updated with whatever is passed in.

Parameters

Required Parameter Description
Yes apiKey
Yes id The ID of the subscriber list to which the subscriber should be added
Yes email The email of the subscriber
No name Name of the subscriber
No fields Array of custom fields of the subscriber
No resubscribe Set it to '1', if you want to reactivate subscriber (default '0')

PHP code example

$ML_Subscribers = new ML_Subscribers( API_KEY );

$subscriber = array(
    'email' => 'first@example.com',
    'name' => 'First name',
    'fields' => array( 
       array( 'name' => 'custom_field_1', 'value' => "field value 1" ),
       array( 'name' => 'custom_field_2', 'value' => "field value 2" )
    )
);
$subscriber = $ML_Subscribers->setId( LIST_ID )->add( $subscriber, 0 /* set to true if you want to reactivate recipient*/ );

Response example

{
    "first@example.com"
}

Adding many subscribers

POST https://api.mailersoft.com/api/v1/subscribers/{list_id}/import

Allows you to add many subscribers to a subscriber list in one API request, including custom field data if supplied. If a subscriber (email address) already exists, their name and any custom field values are updated with whatever is passed in.

Parameters

Required Parameter Description
Yes apiKey
Yes id The ID of the subscriber list to which the subscriber should be added
No subscribers Array of subscribers
No resubscribe Set it to '1', if you want to reactivate subscriber (default '0')

PHP code example

$ML_Subscribers = new ML_Subscribers( API_KEY );

$subscribers = array(
    array(
        'email' => 'first@example.com',
        'name' => 'First name',
        'fields' => array( 
            array( 'name' => 'gender', 'value' => "female" ),
            array( 'name' => 'city', 'value' => "Vilnius" )
        )
    ),
	array(
        'email' => 'second@example.com',
        'name' => 'First name',
        'fields' => array( 
            array( 'name' => 'gender', 'value' => "male" ),
            array( 'name' => 'city', 'value' => "Paris" )
        )
    )
);
$subscribers = $ML_Subscribers->setId( LIST_ID )->addAll( $subscribers, 1 /* set resubscribe to true*/ );

Response example (returns all bad emails)

{
    "Results": [
        {
            "email": "first@example.co"
            "message": "Wrong email address"
        },
        {
            "email": "second@example.com"
            "message": "Recipient is marked as unsubscribed"
        }
    ]
}

Getting a subscribers's details

GET https://api.mailersoft.com/api/v1/subscribers/

Retrieves a subscriber's details including their email address, name, active/inactive state, and any custom field data.

Parameters

Required Parameter Description
Yes apiKey
Yes email The email address of the subscriber whose details should be retrieved.
No history Set to true if you want to get historical records of campaigns and autoresponder emails received by a subscriber (default - false)

PHP code example

$ML_Subscribers = new ML_Subscribers( API_KEY );
$subscriber = $ML_Subscribers->get( 'first@example.com', true /*set true to get history*/ );

Response example

{
    "email": "first@example.com"
    "name": "John",
    "date": "2013-05-05",
    "groups": [
        {
            "id": "124",
            "name": "Clients",
            "count": "1563"
        },
        {
            "id": "1258",
            "name": "VIP",
            "count": "89"
        }
    ],
    "fields": [
        {
            "name": "City",
            "value": "London"
        },
        {
            "name": "Customer ID",
            "value": "4568"
        }
    ],
    "campaigns": [
        {
            "id": "32548",
            "date": "2013-04-11 11:47:58",
            "name": "Buy and get discount",
            "url": "http://api.mailer.lt/buy_and_get_discount_32548"
        },
        {
            "id": "24587",
            "date": "2013-03-12 10:14:51",
            "name": "Thanks for registration",
            "url": "http://api.mailer.lt/thanks_for_registration_24587",
            "opens": [
                {
                    "date": "2013-03-12 10:15:51"
                },
                {
                    "date": "2013-03-12 10:14:59"
                }
            ],
            "clicks": [
                {
                    "date": "2013-03-12 10:15:53",
                    "link": "http://www.example.com/thanks"
                },
                {
                    "date": "2013-03-12 10:15:01",
                    "link": "http://www.example.com"
                }
            ]
        }
    ]
}

Deleting a subscriber

DELETE https://api.mailersoft.com/api/v1/subscribers/{list_id}/

Removes subscriber from the group. He will no longer receive campaigns sent to this group.

Parameters

Required Parameter Description
Yes apiKey
Yes id The ID of the subscriber list to which the subscriber should be added
Yes email The email of the subscriber

PHP code example

$ML_Subscribers = new ML_Subscribers( API_KEY );

$subscriber = $ML_Subscribers->setId( LIST_ID )->remove( 'first@example.com' );

Response example

{
    "first@example.com"
}

Unsubscribing a subscriber

POST https://api.mailersoft.com/api/v1/subscribers/unsubscribe/

Marks subscriber as unsubscribed. He will no longer receive any campaigns.

Parameters

Required Parameter Description
Yes apiKey
Yes email The email of the subscriber

PHP code example

$ML_Subscribers = new ML_Subscribers( API_KEY );

$subscriber = $ML_Subscribers->unsubscribe( 'first@example.com' );

Response example

{
    "first@example.com"
}