PUT masters/{id}/target

Overview

This resource is used to set the targeting for a specific master. The target audience for a message can be defined at message delivery time by their attributes, actions, lists or web page visits. When building out the targeting for a master, the order of criteria is taken into account as subsequent parameters narrow the eligible audience. Each criteria can be negated and joined to the next criteria either with an AND or OR. These logical operators have the following effect on an audience; negate suppresses, AND narrows and OR widens the results. To edit a master it must be in the disabled state.

Profile:

This is the first criteria for all email targeting and is required. It is a boolean which must be set to yes.

Subscriptions:

This is the second criteria for all email targeting. Depending on your company’s configuration four options may be available, Subscribed, Subscribed&Unsubscribed, Subscribed to Division(s), or Subscribed&Unsubscribed to Divisions(s). This value is typically set to subscribed.

Required Attributes:

This is the next in the order of criteria for targeting. Required targeting attributes are defined in the UI.

Attributes:

This is an array of values defined per subscriber. In the Subscribers service they are the userAttrs under profile. Targeting supports theses attribute types, string, boolean, number, number range, date, date range, single and multi-select. SQL attributes are not supported by API targeting.

Actions:

These are email behavior based events. You can target based on whether a subscriber clicked, opened or received a specific master. You can also set the day range as a recency criteria.

Visited:

This is a special action related to having visited a webpage that is being tracked with the Yesmail after the click tracking (ATC). Targeting can be set based on the role, page, master id and the day range. Either role or page must be defined. If both are defined then page takes precedence. 

isMemberOfList:

If you’re using an external list management tool or want to suppress members of certain lists, then use the isMemberOfList. This is an array so more than one list can be set for targeting.

Group:

Grouping allows for joining together any of the optional segments so that their results are treated as one. For example, if you wanted to suppress people that had received a message and lived in a specific area, then you would put the received action and city attribute into a group and negate that group. 

 

The request payload examples demonstrate each of the segment configurations.

 

Resource URI

 https://api.yesmail.com/v2/masters/{id}/target

Call Description

The PUT /v2/masters/{id}/target replaces the targeting of the specified message master {id} with new targeting.

HTTP Return Codes

Code

Description

200 OK

Returned when the master ID exists, the payload will have the master's targeting section only.

400 Bad Request

The request if malformed, the targeting criteria are invalid, or the master is not in disabled state.

401 Unauthorized

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

404 Not Found

The master ID cannot be found, may not exist for the given Api-User or is archived.

Request

When a target audience has already been defined using the Target List API or list load import.

{
  "segments": [
    {
      "isMemberOfList": {
        "lists": [
          "banjo lovers",
          "9 finger club"
        ],
        "negate": false,
        "nextOp": "and"
      }
    }
  ]
}

Response

The response includes required fields, hasEmail & subscription, which do not need to be set in the request.

{
  "segments": [
    {
      "profile": {
        "hasEmail": true
      }
    },
    {
      "subscription": {
        "status": "subscribed",
        "divisions": [
          "marketing"
        ]
      }
    },
    {
      "isMemberOfList": {
        "lists": [
          "banjo lovers",
          "9 finger club"
        ],
        "negate": false,
        "nextOp": "and"
      }
    }
  ]
}

Request

This targeting checks to see if the subscriber has the attribute values and is not a member of the list nor did they receive master 116064

{
    "segments": [
        {
            "subscription": {
                "status": "subscribed"
            }
        },
        {
            "attribute": {
                "name": "Anniversaries",
                "values": [
                    "50",
                    "75"
                ],
                "nextOp": "and"
            }
        },
        {
            "isMemberOfList": {
                "lists": [
                    "ListLoad05182015"
                ],
                "negate": true,
                "nextOp": "and"
            }
        },
        {
            "action": {
                "type": "received",
                "masterIds": [
                    {
                        "masterId": "1116064"
                    }
                ],
                "negate": true
            }
        }
    ]
}

Response

Same as request.

{
    "segments": [
        {
            "subscription": {
                "status": "subscribed"
            }
        },
        {
            "attribute": {
                "name": "Anniversaries",
                "values": [
                    "50",
                    "75"
                ],
                "nextOp": "and"
            }
        },
        {
            "isMemberOfList": {
                "lists": [
                    "ListLoad05182015"
                ],
                "negate": true,
                "nextOp": "and"
            }
        },
        {
            "action": {
                "type": "received",
                "masterIds": [
                    {
                        "masterId": "1116064"
                    }
                ],
                "negate": true
            }
        }
    ]
}

Request

First message in a welcome series where new subscribers either come from a list load or POS API call. Note that Purchase Date is a range which can take a duration interval (P3Y). Product ID is a range of number values.

{
    "segments": [
        {
            "group": {
                "segments": [
                    {
                        "isMemberOfList": {
                            "lists": [
                                "Daily Store Import",
                                "Daily Partner Import"
                            ],
                            "negate": false,
                            "nextOp": "or"
                        }
                    },
                    {
                        "attribute": {
                            "name": "Purchase Date",
                            "values": [
                                "2010-07-28/P3Y"
                            ]
                        }
                    }
                ]
            }
        },
        {
            "attribute": {
                "name": "Product Id",
                "values": [
                    "600-699"
                ],
                "nextOp": "and"
            }
        },
        {
            "action": {
                "type": "received",
                "masterIds": [
                    {
                        "masterId": "1116064",
                        "lessThanDays": 365
                    }
                ]
            }
        }
    ]
}