NewsMAN API: subscriber.search

Sections

Newsman – Knowledge Base

HomeAPISubscribersubscriber.search

Newsman Api Method: subscriber.search

Prototype: subscriber.search(list_id, keywords, status, since, start, limit)

Description: Returns the subscribers matching keywords, status and since (optional) for a list.

HTTP method: GET

Endpoint HTTP: /subscriber.search.json

Endpoint XML-RPC: subscriber.search

Return type: struct

Return info: Hash array, each array item has: subscriber_id, email, date (refering to status, can be: subscribe, unsubscribe, bounce, spam and some times inactivated date).

Request parameters GET

Variable	Type	Description
list_id	string\|int	The ID of the list for which to get the subscribers
keywords	string	They keywords to search by
status	string	Can be: subscribed, unsubscribed, bounced, spam, inactivated (lowercase)
since	string\|null	Date since joining the list (>=), UTC date, format: YYYY-MM-DD HH:mm:ss
start	int\|null	Optional, for large lists. The page number to start. Defaults to first page (page = 0).
limit	int\|null	Optional, for large lists. The number of results to return per page. Defaults to 100. Upper limit is 1000.

Response parameters

Parameter	Description
abonat_id	The ID of the subscriber
email	The email of the subscriber
subscription_status	The subscription status of the subscriber
subscription_date	The subscription date of the subscriber
firstname	The firstname of the subscriber
lastname	The lastname of the subscriber

Output example

[
    {
        "abonat_id": 75005,
        "email": "test3@example.com",
        "subscription_status": "subscribed",
        "subscription_date": "2017-08-17 16:26:51",
        "firstname": "",
        "lastname": ""
    },
    {
        "abonat_id": 75006,
        "email": "test4@example.com",
        "subscription_status": "subscribed",
        "subscription_date": "2017-08-17 16:26:51",
        "firstname": "",
        "lastname": ""
    }
]

Response Errors

Code	Message	Description
407	Missing required param list_id	list_id param is required
407	Missing required param keywords	keywords param is required
407	Missing required param status	status param is required
407	Missing required param since	since param is required
407	Missing required param start	start param is required
407	Missing required param limit	limit param is required
101	Not allowed for list_id = %s	Invalid access to subscriber list_id
108	List %s has been deleted	List has been deleted
801	Please start from the first page and traverse pages consecutively. The first page is 0	Please start from the first page and traverse pages consecutively. The first page is 0
801	Database error	A database error occurred

Error examples

{
    "err": true,
    "message": "Missing required param list_id",
    "code": 407
}

{
    "err": true,
    "message": "Missing required param keywords",
    "code": 407
}

{
    "err": true,
    "message": "Missing required param status",
    "code": 407
}

{
    "err": true,
    "message": "Missing required param since",
    "code": 407
}

{
    "err": true,
    "message": "Missing required param start",
    "code": 407
}

{
    "err": true,
    "message": "Missing required param limit",
    "code": 407
}

{
    "err": true,
    "message": "Database error",
    "code": 801
}