GET masters

Overview

The masters resource is the collection of all non-archived masters in your instance. With this resouce you can get a count of masters, filter your masters by keyword, subscription  (division) or campaign. This service is useful for building lists of masters based on filtered criteria, e.g. Welcome messages in your brand x division.

GET /v2/masters?keyword=sales&keyword=Monday&campaign=2014&campaign=welcome

The example above represents: (keyword = ('sales' OR 'Monday')) AND (campaign = 'welcome')

Keyword filters are partial word matches, e.g. keyword=day would match any day of the week. Subscription and campaign filters are exact matches.

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

Resource URI

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

Call Description

The GET /v2/masters call returns a list of masters sorted by id.

Parameters

Parameter

Requirement

Description

keyword={value}

Optional

Filters list of masters by keyword.

campaign={value} Optional Filters list of masters by campaign.
subscription={value} Optional Filters list of masters by subscription division.

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.

triggered

Optional

Boolean parameter used to indicate whether to include only triggered messages (true), or only non-triggered messages (false), or both (if the parameter is not present in the URL).

state

Optional

Used to filter based on the state of the master. It accepts comma separated list of states. Accepted states are (disabled, enabled, delivered, halted, paused, deleted).

schedulePeriod

Optional

Takes a period / interval to filter the masters based on the scheduled time period (nextTimeToDeliver). It takes the interval in ISO format 2015-08-01T13:00:00Z/2015-05-11T15:30:00Z. Note that this period should be in future. Zero results will return if it is in past.

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.

Response Payload: 
{
  "counts": {
    "count": 2,
    "match": 120,
    "total": 185
  }
  masters: [
    {
      "id": "345678",
      "lastUpdate": "2014-04-29T16:08:32Z",
      "name": "unique-master-name-1",
      "subscription": "division-1",
      "status": "enabled",
      "campaign": "My high-tech campaign",
      "keywords": [
        "premium",
        "butter",
        "churner"
      ]
    },
    {
      "id": "234567",
      "created": "2014-03-22T11:12:13Z",
      "lastUpdate": "2014-04-11T11:12:14Z",
      "name": "unique-master-name-2",
      "subscription": "division-2",
      "status": "disabled",
      "keywords": [
        "premium"
      ]
    }
  ]
}