POST subscribers/{id}/update

Overview

The subscriber profile is where personalization and targeting information is stored. POST /v2/subscribers/{id}/update amends and updates selected profile elements for an existing individual subscriber.

Unlike PUT v2/subscribers/{id}, POST v2/subscribers/{id}/update modifies only the elements specified in the request payload.  Any subscriber attributes missing from the request payload will retain their existing values. When mulit-value attributes are updated, new values are appended to existing values. Multi-value attribute values must be removed using the PUT v2/subscribers/{id} method.

This call may also be used to modify the subscriber's subscriptions, by using an optional "subscriptions" collection in the request payload.  Within this collection, the following arrays are allowed:

  • "add": Provides a list of subscriptions to be subscribed to
  • "remove": Provides a list of subscriptions to be unsubscribed from ("Remove": ["*"] can be used to unsubscribe from all subscriptions)
  • "memberOf": Provides the complete list of subscriptions to which the subscriber is to be subscribed.  Any divisions listed in this array will be subscribed, and any divisions not listed in this array will be unsubscribed.

Order of operations:  If "memberOf" is present, then "add" and "remove" are ignored.  If both "add" and "remove" are present, but "memberOf" is not, then the "remove" operation is performed before the "add" operation.

Target list membership may be modified by optional “add”, “remove”, or “memberOf” arrays within an optional “targetLists” collection.  The functionality of “add”, “remove”, and “memberOf” work for target-lists exactly the way as described above for subscriptions (except that “events” are not generated for target lists).

It is possible to set the “referred” property to [true].

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

 

Resource URI

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

 

Call Description

The POST /v2/subscribers/{id}/update call updates selected profile elements, or subscriptions, for an existing individual 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 of parameters, invalid parameter values, subscriber attribute does not exist, specified target-list does not exist, missing email address for new subscriber, subscriber email address fails superficial validation, attempt to update email, cdid, or subscriptions for a dead subscriber.

401 Unauthorized

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

404 Resource 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

Changing the email address when it is also the id.

PUT /v2/subscribers/bobm@reggae.com
 
{
    "id": "bob.marley@reggae.com",
    "email": "bob.marley@reggae.com",
    "profile": {
        "userAttrs": [
            {
                "lastName": "Marley"
            },
            {
                "firstName": "Bob"
            }
        ]
    }
}

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"
            }
        ]
    },
    "subscriptions": {
        "memberOf": [
            "New Solutions"
        ],
        "current": [
            {
                "division": "New Solutions",
                "state": "subscribed",
                "time": "2014-09-30T23:28:13Z"
            }
        ]
    }
}

Request

Subscriber has updated their mailing preferences and contact information.

{
    "id": "bob.marley@reggae.com",
    "profile": {
        "userAttrs": [
            {
                "lastName": "Marley"
            },
            {
                "firstName": "Bob"
            },
            {
                "Date of Birth": "1945-02-06T00:00:00Z"
            }
        ]
    },
    "subscriptions": {
        "add": [
            "Jamaica locals",
            "Rastafari"
        ],
        "remove": [
            "Jamaica lovers"
        ]
    },
    "targetLists": {
        "add": [
            "Newsletter"
        ]
    }
}

Response

{
    "id": "bob.marley@reggae.com",
    "profile": {
        "userAttrs": [
            {
                "lastName": "Marley"
            },
            {
                "firstName": "Bob"
            },
            {
                "Date of Birth": "1945-02-06T00:00:00Z"
            }
        ]
    },
    "subscriptions": {
        "memberOf": [
            "Jamaica locals",
            "Rastafari"
        ],
        "current": [
            {
                "division": "Rastafari",
                "state": "subscribed",
                "time": "2014-09-30T23:28:13Z"
            },
            {
                "division": "Jamaica locals",
                "state": "subscribed",
                "time": "2014-09-30T23:28:13Z"
            },
            {
                "division": "Jamaica lovers",
                "state": "unsubscribed",
                "time": "2014-09-30T23:28:13Z"
            }
        ]
    }
}

Request

Adding Wailers to the list of Bob's bands

{
    "id": "bob.marley@reggae.com",
    "profile": {
        "userAttrs": [
            {
                "bands": "Teenagers|Wailing Rude Boys|Wailers"
            }
 
        ]
    }
}

Response

{
    "id": "bob.marley@reggae.com",
    "profile": {
        "userAttrs": [
           {
                "lastName": "Marley"
            },
            {
                "firstName": "Bob"
            },
            {
                "Date of Birth": "1945-02-06T00:00:00Z"
            },
            {
                "bands": "Teenagers|Wailing Rude Boys|Wailers"
            }
 
        ]
    }
}