GET subscribers

Overview

The subscriber profile is where personalization and targeting information is stored.  GET /v2/subscribers returns the profile information, subscriptions, and/or email summary for your subscribers.

In order to limit payload size, the maximum number of subscribers that can be returned in a single call is 100. The full list of subscribers can be obtained via a series of GET subscribers calls using appropriate values of the LIMIT and OFFSET parameters.

Resource URI

 https://api.yesmail.com/v2/subscribers

Call Description

The GET /v2/subscribers call returns the profile information, subscriptions, and/or message history for your subscribers.

Parameters

Parameter

Requirement

Description

email={address}

Optional

Filters list of subscribers by the specified email address. Sets view as full.

s&i Optional Uniqiue values provided with unsubscribe link to look up subscriber. Can be used with /v2/subscribers/unsubscribe to unsubscribe individual.

limit

Optional

The maximum number of subscribers to be provided within the request.  Valid values are integers 0-100.  The default is 25.

offset

Optional

The sequence number of the first subscriber to be provided within the request.  Valid values are 0-any positive integer.  The default is 0.  In conjunction with limit, this can be used to “page through” the full result set of subscribers or choose an individual subscriber. The offset value is one less than the internal id value for the subscriber.

view

Optional

Valid values are “basic”, “profile”, “subscriptions”, “emails”, “messages”, "target-lists", “full.”  The default is “basic”.

  • “basic” – for each subscriber in the result set,  returns the customer-defined ID and email address (along with ETag and lastUpdate).
  • “profile” – for each subscriber in the result set, returns the “basic” information and the entire contents of the profile collection.  See here for more information about the subscriber profile.
  • “subscriptions” – for each subscriber in the result set, returns the “basic” information and a "subscriptions" collection that contains an array of current subscriptions, an array of former subscriptions, and an array of all subscription events.
  • “emails” – for each subscriber in the result set, returns the “basic” information and an "emails" collection that contains summary information about the emails sent to that subscriber.
  • “messages” – for each subscriber in the result set, returns the “basic” information and the “emails” collection.
  • "target-lists" – for each subscriber in the result set, return the “basic” information and a “targetLists” collection which contains a single array, “memberOf”, which in turn lists all of the target lists that the subscriber is a member of. 
  • “full” – returns all subscriber information listed above.
  • “schema” – returns allowable data elements, data types and lengths. Note: limit and offset parameters are not applicable when view=schema is specified.

HTTP Return Codes

 

Code

Description

200 OK

The request has succeeded.

400 Bad Request

The request could not be understood by the server due to malformed syntax.  For example, incorrect syntax of parameters, invalid parameter values.

401 Unauthorized

The request requires user authentication.  Invalid Api-User and/or Api-Key header value.

404 Not Found The server has not found a subscriber matching the requested URI value.

Response

Basic view (default)

{
    "view": "basic",
    "offset": 0,
    "limit": 25,
    "count": 25,
    "total": 7519244,
    "subscribers": [
        {
            "id": "postqa_1414068498474_646@hotmail.com",
            "lastUpdate": "2015-01-22T12:44:17Z",
            "email": "postqa_1414068498474_646@hotmail.com"
        },
        {
            "id": "testmail1010531@testmail.com.post.post",
            "lastUpdate": "2015-01-25T15:16:06Z",
            "email": "testmail1010531@testmail.com.post.post"
        },
        {
            "id": "testmail1010531@testmail.com.post.post.post",
            "lastUpdate": "2015-01-24T10:17:19Z",
            "email": "testmail1010531@testmail.com.post.post.post"
        },
        {
            "id": "testmail1010532@testmail.com.post.post.post",
            "lastUpdate": "2015-01-26T17:51:31Z",
            "email": "testmail1010532@testmail.com.post.post.post"
        },
        {
            "id": "testmail1010533@testmail.com.post.post",
            "lastUpdate": "2015-01-26T15:38:45Z",
            "email": "testmail1010533@testmail.com.post.post"
        },
        {
            "id": "testmail1010533@testmail.com.post.post.post",
            "lastUpdate": "2015-02-11T17:30:35Z",
            "email": "testmail1010533@testmail.com.post.post.post"
        },
        {
            "id": "testmail1010534@testmail.com.post.post.post",
            "lastUpdate": "2015-01-27T03:31:03Z",
            "email": "testmail1010534@testmail.com.post.post.post"
        },
        {
            "id": "testmail1010535@testmail.com.post.post",
            "lastUpdate": "2015-02-01T10:08:03Z",
            "email": "testmail1010535@testmail.com.post.post"
        },
        {
            "id": "testmail1010535@testmail.com.post.post.post",
            "lastUpdate": "2015-02-07T10:30:07Z",
            "email": "testmail1010535@testmail.com.post.post.post"
        },
        {
            "id": "testmail1010536@testmail.com.post.post",
            "lastUpdate": "2015-02-02T18:46:27Z",
            "email": "testmail1010536@testmail.com.post.post"
        },
        {
            "id": "testmail1010537@testmail.com.post.post",
            "lastUpdate": "2015-02-06T23:09:31Z",
            "email": "testmail1010537@testmail.com.post.post"
        },
        {
            "id": "testmail1010538@testmail.com.post.post",
            "lastUpdate": "2015-02-10T14:39:11Z",
            "email": "testmail1010538@testmail.com.post.post"
        },
        {
            "id": "testmail1010540@testmail.com.post.post",
            "lastUpdate": "2015-02-04T15:46:40Z",
            "email": "testmail1010540@testmail.com.post.post"
        },
        {
            "id": "testmail1010541@testmail.com.post.post",
            "lastUpdate": "2015-01-17T18:24:54Z",
            "email": "testmail1010541@testmail.com.post.post"
        },
        {
            "id": "testmail1010542@testmail.com.post.post.post",
            "lastUpdate": "2015-02-10T02:23:25Z",
            "email": "testmail1010542@testmail.com.post.post.post"
        },
        {
            "id": "testmail1010543@testmail.com.post.post.post",
            "lastUpdate": "2015-01-26T08:01:55Z",
            "email": "testmail1010543@testmail.com.post.post.post"
        },
        {
            "id": "testmail1010545@testmail.com.post.post.post",
            "lastUpdate": "2015-02-10T07:13:40Z",
            "email": "testmail1010545@testmail.com.post.post.post"
        },
        {
            "id": "testmail1010546@testmail.com.post.post.post",
            "lastUpdate": "2015-01-25T04:54:48Z",
            "email": "testmail1010546@testmail.com.post.post.post"
        },
        {
            "id": "testmail1010548@testmail.com.post.post",
            "lastUpdate": "2015-01-26T08:52:23Z",
            "email": "testmail1010548@testmail.com.post.post"
        },
        {
            "id": "testmail1010549@testmail.com.post.post",
            "lastUpdate": "2015-02-08T09:46:21Z",
            "email": "testmail1010549@testmail.com.post.post"
        },
        {
            "id": "testmail1057747@testmail.com.post",
            "lastUpdate": "2015-01-27T09:45:42Z",
            "email": "testmail1057747@testmail.com.post"
        },
        {
            "id": "testmail1113993@testmail.com.post",
            "lastUpdate": "2015-02-02T09:40:33Z",
            "email": "testmail1113993@testmail.com.post"
        },
        {
            "id": "testmail1113994@testmail.com.post",
            "lastUpdate": "2015-02-10T13:49:02Z",
            "email": "testmail1113994@testmail.com.post"
        },
        {
            "id": "testmail1113995@testmail.com.post",
            "lastUpdate": "2015-01-19T23:52:47Z",
            "email": "testmail1113995@testmail.com.post"
        },
        {
            "id": "testmail1113996@testmail.com.post",
            "lastUpdate": "2015-02-07T22:50:52Z",
            "email": "testmail1113996@testmail.com.post"
        }
    ]
}

Response

Full subscriber details, limited to two records, at the 1967th position.

{
    "view": "full",
    "offset": 1967,
    "limit": 2,
    "count": 2,
    "total": 7519244,
    "subscribers": [
        {
            "id": "testmail1013489@testmail.com.post.post.post",
            "lastUpdate": "2015-02-07T15:15:29Z",
            "email": "testmail1013489@testmail.com.post.post.post",
            "profile": {
                "userAttrs": [
                    {
                        "lastName": "sunscope"
                    },
                    {
                        "firstName": "runscope1"
                    },
                    {
                        "prefersMobile": -1
                    },
                    {
                        "emailFormat": "HTML"
                    }
                ]
            },
            "subscriptions": {
                "memberOf": [
                    "Finance"
                ],
                "current": [
                    {
                        "division": "Corporate",
                        "state": "unsubscribed",
                        "time": "2014-10-23T18:08:54Z"
                    },
                    {
                        "division": "Finance",
                        "state": "subscribed",
                        "time": "2014-10-23T19:33:37Z"
                    },
                    {
                        "division": "Retail",
                        "state": "unsubscribed",
                        "time": "2014-10-23T17:56:19Z"
                    },
                    {
                        "division": "Another",
                        "state": "unsubscribed",
                        "time": "2014-10-23T19:33:37Z"
                    }
                ]
            }
        },
        {
            "id": "testmail1013490@testmail.com.post.post.post",
            "lastUpdate": "2015-01-27T15:08:08Z",
            "email": "testmail1013490@testmail.com.post.post.post",
            "profile": {
                "userAttrs": [
                    {
                        "lastName": "sunscope"
                    },
                    {
                        "firstName": "runscope1"
                    },
                    {
                        "prefersMobile": -1
                    },
                    {
                        "emailFormat": "HTML"
                    }
                ]
            },
            "subscriptions": {
                "memberOf": [
                    "Another"
                ],
                "current": [
                    {
                        "division": "Corporate",
                        "state": "unsubscribed",
                        "time": "2014-10-23T19:33:36Z"
                    },
                    {
                        "division": "Finance",
                        "state": "unsubscribed",
                        "time": "2014-10-23T17:54:40Z"
                    },
                    {
                        "division": "Retail",
                        "state": "unsubscribed",
                        "time": "2014-10-23T17:56:19Z"
                    },
                    {
                        "division": "Another",
                        "state": "subscribed",
                        "time": "2014-10-23T19:33:36Z"
                    }
                ]
            }
        }
    ]
}

Request

The offset is one less than the internal id value for the subscriber. offset=1967 is id=1968

Response

Email KPIs for subscriber with internal id=1968.

{
    "view": "emails",
    "offset": 1967,
    "limit": 1,
    "count": 1,
    "total": 7519244,
    "subscribers": [
        {
            "id": "testmail1012655@testmail.com.post.post.post",
            "lastUpdate": "2015-02-02T16:06:14Z",
            "email": "testmail1012655@testmail.com.post.post.post",
            "emails": {
                "countTotalSent": 57,
                "countTotalClicks": 0,
                "countUniqueClicks": 0,
                "countUniqueOpens": 0,
                "countTotalDelivered": 46,
                "countTotalBounced": 11
            }
        }
    ]
}

Response

Look-up subscriber by email address. Use this when email is not primary key. Shows full subscriber view.

{
    "view": "full",
    "offset": 0,
    "limit": 25,
    "count": 1,
    "total": 7519244,
    "subscribers": [
        {
            "id": "cust_id1234556677",
            "lastUpdate": "2015-02-02T16:06:14Z",
            "email": "testmail@testmail.com",
            "profile": {
                "userAttrs": [
                    {
                        "lastName": "sunscope"
                    },
                    {
                        "firstName": "runscope1"
                    },
                    {
                        "prefersMobile": -1
                    },
                    {
                        "emailFormat": "HTML"
                    }
                ]
            },
            "subscriptions": {
                "memberOf": [
                    "Another"
                ],
                "current": [
                    {
                        "division": "Corporate",
                        "state": "unsubscribed",
                        "time": "2014-10-23T17:56:16Z"
                    },
                    {
                        "division": "Finance",
                        "state": "unsubscribed",
                        "time": "2014-10-23T18:08:51Z"
                    },
                    {
                        "division": "Retail",
                        "state": "unsubscribed",
                        "time": "2014-10-23T19:33:32Z"
                    },
                    {
                        "division": "Another",
                        "state": "subscribed",
                        "time": "2014-10-23T19:33:32Z"
                    }
                ]
            }
        }
    ]
}

Response

Look-up subscribe by encrypted subscriber and message id

{
  "s": "4J0j",
  "i": "20445832",
  "view": "basic",
  "offset": 0,
  "limit": 25,
  "count": 1,
  "total": 97225,
  "subscribers": [
    {
      "id": "bobby@ratdog.com",
      "lastUpdate": "2015-03-11T00:19:42Z",
      "email": "bobby@ratdog.com"
    }
  ]
}