PUT subscribers/{id}

Overview

The subscriber profile is where personalization and targeting information is stored. PUT /v2/subscribers/{id} updates all attributes for an existing individual subscriber, or creates a new individual subscriber. If the {id} in the URI is not an existing value of the id field, a new subscriber is created. If the value of {id} already exists, then the payload information is used to update the existing subscriber. 

Note that for this call, any attributes not listed in the request payload will be reset to a null value.  By contrast, the call POST v2/subscribers/{id}/update call can be used to update only the attributes specified in the request payload, while leaving the values intact for any attributes missing from the request payload.

"id" is also required in the request payload. If the payload id is not equal to the URI {id}, the call is interpreted as a request to change the ID for the subscriber from the URI {id} to the payload id.

An "email" key-value pair is required at the top level of the subscriber record. In the case that email is not available, an empty value of "email" may be specified -- "email": ""

The subscriber's subscriptions may be modified via a "subscriptions" collection in the request payload.  Within that collection, the "memberOf" array specifies the entire list of divisions to which the subscriber is to be subsubscribed.  (This operation may also be performed via the PUT subscribers/{id}/subscriptions call.)

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, subscriptions or target lists will return a 400 Bad Request error.

 

 

 

Resource URI

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

Call Description

The PUT /v2/subscribers/{id} call updates all attributes for an existing individual subscriber, or creates a new individual subscriber.  It can also be used to modify the subscriber's subscriptions.

HTTP Return Codes

Code

Description

200 OK

The resource (e.g. existing subscriber) has been updated.

201 Created

The resource (e.g. new subscriber) has been created successfully.

400 Bad Request The request could not be understood by the server due to malformed syntax or other issues.  For example, incorrect syntax of parameters, invalid parameter values, subscriber attribute does not exist, missing email address for new subscriber, subscriber email address fails superficial validation, or it is an attempt to a call on a dead subscriber..

401 Unauthorized

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

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

Create new subscriber with profile values (MultiValue attribute) a division and target list

{
    "id": "bob.marley@reggae.com",
    "email": "bob.marley@reggae.com",
    "profile": {
        "userAttrs": [
            {
                "lastName": "Marley"
            },
            {
                "firstName": "Bob"
            },
            {
                "Instruments": "Vocals|Guitar"
            }
        ]
    },
    "subscriptions": {
        "memberOf": [
            "New Solutions"
        ]
    },
    "mobileSubscriptions": {
       "memberOf": [
           "Vibes UK1",
           "Vibes Text Ka",
           "Vibes Test Automation"
        ]
    },
    "targetLists": {
        "memberOf": [
            "top10"
        ]
    }
}

Response

{
    "id": "bob.marley@reggae.com",
    "lastUpdate": "2014-10-23T17:10:57Z",
    "email": "bob.marley@reggae.com",
    "profile": {
        "userAttrs": [
            {
                "lastName": "Marley"
            },
            {
                "prefersMobile": -1
            },
            {
                "firstName": "Bob"
            },
            {
                "emailFormat": "UNKNOWN"
            },
            {
                "Instruments": "Vocals|Guitar"
            }
        ]
    },
    "subscriptions": {
        "memberOf": [
            "New Solutions"
        ],
        "current": [
            {
                "division": "New Solutions",
                "state": "subscribed",
                "time": "2014-09-30T23:28:13Z"
            }
        ]
    },
    "mobileSubscriptions": {
        "memberOf": [
            "Vibes Text Ka",
            "Vibes Test Automation",
            "Vibes UK1"
        ],
        "current": [
            {
                "mobileAccount": "Vibes Text Ka",
                "state": "SUBSCRIBED",
                "Mobile Number": "13312409403"
            },
            {
                "mobileAccount": "Vibes Test Automation",
                "state": "SUBSCRIBED",
                "Mobile Number": "13312409403"
            },
            {
                "mobileAccount": "Vibes UK1",
                "state": "SUBSCRIBED",
                "UK Phone Number": "447377722619"
            }
        ]
    },
    "targetLists": {
        "memberOf": [
            "top10"
        ]
    }
}

Request

This request will replace the subscribers subscriptions and lists with those defined in the memberOf arrays.

{
    "id": "jsmith@zzz.com",
    "email": "jsmith@zzz.com",
    "profile": {
        "userAttrs": [
            {"firstName": "John"},
            {"lastName": "Smith"}
         ]
    },
    "subscriptions": {
 
        "memberOf": [
            "division1", "division2"
         ]
   },                                        
"targetLists": {
     "memberOf": [
          "TargetList1", 
          "TargetList2"
          ]
}

Response

Updated subscriber, note division3 was unsubscribed

{
    "id": "jsmith@zzz.com",
    "lastUpdate": "2012-09-26T14:00:00Z",
    "email": "jsmith@zzz.com",
    "profile": {
        "userAttrs": [
            {"firstName": "John"},
            {"lastName": "Smith"}
         ]
    },    
    "subscriptions": {
 
        "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"
            }
        ]
    },
    "targetLists": {
         "memberOf": [
                "TargetList1", 
                "TargetList2"
          ]
    }
}