PUT subscribers/{id}/subscriptions

Overview

PUT /v2/subscribers/{id}/subscriptions updates the full set of subscriptions in a single operation for the specified subscriber.

Subscription state is set to "subscribed" for any divisions that are present in the "memberOf" array that are not currently subscribed.

Subscription state is set to "unsubscribed" for any divisions that are not present in the "memberOf" array that are currently subscribed.  (An empty memberOf array can be used to unsubscribe from all divisions.)

It is possible to set the “referred” property to [true]. However, is only permitted for new subscribers, or existing subscribers who are unsubscribed to all divisions.  

If the subscriber is already susbscribed to one or more divisions, or the API call simultaneously subscribes them to one or more divisions, then the attempt to set the “referred” property will be ignored, without generating an error, and permitting the rest of the update to proceed. 

This is set via the “setReferred” element in the request payload.  There are two allowable values (any other value is ignored):

“setReferred”: “newOrNotSubscribed” (as described above, this sets the subscriber status to “referred’ if the subscriber is new, or not subscribed to any divisons)

“setReferred”: “newOnly” (sets the subscriber status to “referred” only for new subscribers; otherwise the element is ignored, even if the subscriber is unsubscribed to all divisions).

If “dead” = true, only the subscriber profile information can be updated.  Attempts to update email, cdid or subscriptions will return a 400 Bad Request error.

Subscriptions cannot be modified for Dead subscribers.

Resource URI

PUT https://api.yesmail.com/v2/subscribers/{id}/subscriptions

Call Description

The PUT /v2/subscribers/{id}/subscriptions call updates the full set of subscriptions in a single operation for the specified subscriber.

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, a division specified in the request payload does not exist, or subscriber is dead.

401 Unauthorized

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

404 Not Found

The server has not found anything matching the request resource.   For instance, the “id” does not exist.
409 Conflict This occurs when the If-Match condition is used, and the specified ETag does not match the current ETag for the resource.

 

Request Payload: 
{
   "setReferred":  "newOrNotSubscribed", ;optional; see documentation for details
   "memberOf": [
        "Division1",
        "Division2"
    ]
}
Response Payload: 
{
                              ;"referred" = true or "dead" = true would go here, if applicable
    "memberOf": [
        "Division1",
        "Division2"
    ],
    "current": [
        {
            "division": "Division1",
            "state": "subscribed",
            "time": "2013-01-01T08:09:10Z"
        },
        {
            "division": "Division2",
            "state": "subscribed",
            "time": "2013-01-04T08:09:10Z"
        },
        {
            "division": "Division3",
            "state": "unsubscribed",
            "time": "2013-01-10T08:09:10Z"
        }
    ],
    "events": [
        {
            "division": "Division1",
            "state": "subscribed",
            "time": "2013-01-01T08:09:10Z"
        },
        {
            "division": "Division3",
            "state": "subscribed",
            "time": "2013-01-02T08:09:10Z"
        },
        {
            "division": "Division2",
            "state": "subscribed",
            "time": "2013-01-04T08:09:10Z"
        },
        {
            "division": "Division3",
            "state": "unsubscribed",
            "time": "2013-01-10T08:09:10Z"
        }
    ]
}