Lists

Get all lists from your account

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

Returns all lists you have in your account. Also basic summary for each list including the ID.

Parameters

Required Parameter Description
Yes apiKey
No limit sets the limit of results in one page (default 1000)
No page you can navigate trough records by increasing page number

PHP code example

To get all lists in your account.

$ML_Lists = new ML_Lists( API_KEY );
$lists = $ML_Lists->getAll( );

Response example

{
    "Results": [
        {
            "id": "11"
            "name": "My list",
            "date": "2013-05-05 07:22:54",
            "updated": "2013-06-18 15:57:35",
            "total": "212",
            "unsubscribed": "27",
            "bounced": "40"
        },
        {
            "id": "12"
            "name": "My second list",
            "date": "2013-05-08 01:21:15",
            "updated": "2013-06-19 12:55:34",
            "total": "789",
            "unsubscribed": "35",
            "bounced": "48"
        }
    ],
    "Page": "1",
    "Limit": "1000",
    "RecordsOnPage": "2",
    "Total": "2"
}

List details

GET https://api.mailersoft.com/api/v1/lists/{id}//

Retrieve stats about sent messages.

Parameters

Required Parameter Description
Yes apiKey
Yes id The ID of the list you want the stats for

PHP code example

$ML_Lists = new ML_Lists( API_KEY );
$list = $ML_Lists->setId( 11 )->get( );

Response example

{
	"id": "11"
	"name": "My list",
	"date": "2013-05-05 07:22:54",
	"updated": "2013-06-18 15:57:35",
	"total": "212",
	"unsubscribed": "27",
	"bounced": "40"
}

Add list

POST https://api.mailersoft.com/api/v1/lists/

Create new list.

Parameters

Required Parameter Description
Yes apiKey
Yes name The name of the new list you want to create

PHP code example

Creates a new list into which subscribers can be added or imported.

$ML_Lists = new ML_Lists( API_KEY );
$result = $ML_Lists->add( array( 'name' => 'My new list' ) );

Response example

{
	"id": "11"
	"name": "My new list",
}

Updating a list

PUT https://api.mailersoft.com/api/v1/lists/

Create new list.

Parameters

Required Parameter Description
Yes apiKey
Yes id The ID of the list you want to change
Yes name The name of the new list you want to create

PHP code example

Changes a name of the list.

$ML_Lists = new ML_Lists( API_KEY );
$result = $ML_Lists->setId( 11 )->put( array( 'name' => 'My another list' ) );

Response example

{
	"name": "My another list",
}

Removing a list

DELETE https://api.mailersoft.com/api/v1/lists/

Create new list.

Parameters

Required Parameter Description
Yes apiKey
Yes id The ID of the list you want to remove

PHP code example

Removes a list from your account.

$ML_Lists = new ML_Lists( API_KEY );
$result = $ML_Lists->setId( 11 )->remove( );

Response example

{
}

Active subscribers

GET https://api.mailersoft.com/api/v1/lists/{id}/active/

Returns all active subscribers in given list.

Parameters

Required Parameter Description
Yes apiKey
Yes id The ID of the list you want the stats for
No date Date from when only new added subscribers are returned
No limit sets the limit of results in one page (default 1000)
No page you can navigate trough records by increasing page number

PHP code example

$ML_Lists = new ML_Lists( API_KEY );
$active_subscribers = $ML_Lists->setId( 11 )->getActive( );
$new_subscribers = $ML_Lists->setId( 11 )->getActive( array('date' => '2014-09-01', 'page' => '2', 'limit' => '100' ) );

Response example

{
    "Results": [
        {
            "email": "first@example.com"
            "name": "First",
            "date": "2009-07-09",
            "group_date": "2010-10-01 12:30:44",
            "sent": "28",
            "opened": "24",
            "clicked": "7",
            "CustomFields": [
                {
                    "name": "City",
                    "value": "Vilnius"
                },
                {
                    "name": "Gender",
                    "value": "male"
                }
            ]
        },
        {
            "email": "second@example.com"
            "name": "Second",
            "date": "2010-07-02",
            "group_date": "2010-10-15 13:45:12",
            "sent": "18",
            "opened": "14",
            "clicked": "5"
            "CustomFields": [
                {
                    "name": "City",
                    "value": "Paris"
                },
                {
                    "name": "Gender",
                    "value": "female"
                }
            ]
        }
    ],
    "Page": "1",
    "Limit": "1000",
    "RecordsOnPage": "2",
    "Total": "7"
}

Unsubscribed subscribers

GET https://api.mailersoft.com/api/v1/lists/{id}.{json|xml}/unsubscribed/

Returns all unsubscribed subscribers in given list.

Parameters

Required Parameter Description
Yes apiKey
Yes id The ID of the list you want the stats for
No date Date from when only new unsubscribed subscribers are returned
No limit sets the limit of results in one page (default 1000)
No page you can navigate trough records by increasing page number

PHP code example

$ML_Lists = new ML_Lists( API_KEY );
$unsubscribed_subscribers = $ML_Lists->setId( 11 )->getUnsubscribed( );
$new_unsubscribes = $ML_Lists->setId( 11 )->getUnsubscribed( array('date' => '2015-09-15', 'limit' => '200', 'page' => '1' ) );

Response example

{
    "Results": [
        {
            "email": "adam@example.com"
            "name": "First",
            "date": "2009-07-09",
            "unsubscribe_date": "2015-10-01 15:32:34",
            "sent": "28",
            "opened": "24",
            "clicked": "7",
            "CustomFields": [
                {
                    "name": "City",
                    "value": "Vilnius"
                },
                {
                    "name": "Gender",
                    "value": "male"
                }
            ]
        },
        {
            "email": "jane@example.com"
            "name": "Second",
            "date": "2010-07-02",
            "unsubscribe_date": "2015-09-15 23:16:07",
            "sent": "18",
            "opened": "14",
            "clicked": "5"
            "CustomFields": [
                {
                    "name": "City",
                    "value": "Paris"
                },
                {
                    "name": "Gender",
                    "value": "female"
                }
            ]
        }
    ],
    "Page": "1",
    "Limit": "1000",
    "RecordsOnPage": "2",
    "Total": 12
}

Bounced subscribers

GET https://api.mailersoft.com/api/v1/lists/{id}.{json|xml}/bounced/

Returns all bounced subscribers in given list.

Parameters

Required Parameter Description
Yes apiKey
Yes id The ID of the list you want the stats for
No date Date from when only new bounced subscribers are returned
No limit sets the limit of results in one page (default 1000)
No page you can navigate trough records by increasing page number

PHP code example

$ML_Lists = new ML_Lists( API_KEY );
$bounced_subscribers = $ML_Lists->setId( 11 )->getBounced( );
$new_bounced = $ML_Lists->setId( 11 )->getBounced( array('date' => '2015-10-01') );

Response example

{
    "Results": [
        {
            "email": "one@example.com"
            "name": "First",
            "date": "2009-07-09",
            "bounce_date": "2009-09-12 17:45:43",
            "sent": "28",
            "opened": "24",
            "clicked": "7",
            "CustomFields": [
                {
                    "name": "City",
                    "value": "Vilnius"
                },
                {
                    "name": "Gender",
                    "value": "male"
                }
            ]
        },
        {
            "email": "two@example.com"
            "name": "Second",
            "date": "2010-07-02",
            "bounce_date": "2011-12-31 23:15:32",
            "sent": "18",
            "opened": "14",
            "clicked": "5"
            "CustomFields": [
                {
                    "name": "City",
                    "value": "Paris"
                },
                {
                    "name": "Gender",
                    "value": "female"
                }
            ]
        }
    ],
    "Page": "1",
    "Limit": "1000",
    "RecordsOnPage": "2",
    "Total": "23"
}

Changed subscribers

GET https://api.mailersoft.com/api/v1/lists/{id}.{json|xml}/changed/

Returns all changed subscribers (active, unsubscribed, bounced) from specified date in one list.

Parameters

Required Parameter Description
Yes apiKey
Yes id The ID of the list you want the stats for
Yes date Date from when only new changed subscribers are returned
No limit sets the limit of results in one page (default 1000)
No page you can navigate trough records by increasing page number

PHP code example

$ML_Lists = new ML_Lists( API_KEY );
$changed = $ML_Lists->setId( 11 )->getChanged( array('date' => '2015-10-01') );

Response example

{
    "Results": [
        {
            "email": "one@example.com"
            "name": "First",
            "date": "2009-07-09",
            "bounce_date": "2009-09-12 17:45:43",
            "sent": "28",
            "opened": "24",
            "clicked": "7",
            "CustomFields": [
                {
                    "name": "City",
                    "value": "Vilnius"
                },
                {
                    "name": "Gender",
                    "value": "male"
                }
            ],
			"type": "bounced"
        },
        {
            "email": "adam@example.com"
            "name": "First",
            "date": "2009-07-09",
            "unsubscribe_date": "2015-10-01 15:32:34",
            "sent": "28",
            "opened": "24",
            "clicked": "7",
            "CustomFields": [
                {
                    "name": "City",
                    "value": "Vilnius"
                },
                {
                    "name": "Gender",
                    "value": "male"
                }
            ],
			"type": "unsubscribed"
        },
        {
            "email": "first@example.com"
            "name": "First",
            "date": "2009-07-09",
            "group_date": "2010-10-01 12:30:44",
            "sent": "28",
            "opened": "24",
            "clicked": "7",
            "CustomFields": [
                {
                    "name": "City",
                    "value": "Vilnius"
                },
                {
                    "name": "Gender",
                    "value": "male"
                }
            ],
			"type": "active"
        },
        
    ],
    "Page": "1",
    "Limit": "1000",
    "RecordsOnPage": "2",
    "Total": "23"
}