POST subscribers/import

Overview

This method is for the importing or updating of thousands of subscriber records in a single call. Using the method the caller can define the error threshold, import type (ignore/update/replace), default subscriptions and individual record updates. See Parameters for details.

The defaults object defines the subscription state and target list for the import. If individual subscription or targetLists values are provide, these overide the default values. If all members are being added to the same subscription then specify that subscription in the defaults object.

This is an asynchronous call and the response is a ticket with the status of the request. Once the request has been completed the response location will contain the resource for the invidiual record results. This is provided by the Async Results API.

The Async Results response payload contains the following summary information about the results of the call:

  • Counts - Requested, completed, failed, ignored and total.
  • Completed - Index value and timestamp
  • Failed - Index, timestamp and error message
  • Ignored - Index

Resource URI

 https://api.yesmail.com/v2/subscribers/import

Call Description

In addition to the standard response headers, this API call will also provide a header Content-Location: https://api.yesmail.com/v2/tickets/{id}, which provides the location of the ticket resource where status information is updated. See Tickets API documenation for more details.

URI Parameters

Parameter Required Description
responseUri 

 Optional

A customer-specified URI where Yesmail’s service can post the final status of the request.  See Tickets API documentation for more details.

responseRef 

 Optional

A customer-specified value that the customer may wish to use to track the ticket internally.  See Tickets API documentation for more details.

 

Parameters

Parameter

Required

Description

errorThreshold

Optional

Optional property specifying when to stop the import process due to failures. Default is 0 or no check.

  • integer – An integer value specifying an exact error count to trigger the stop. Set to 0 (zero) to attempt import of the entire source file.
  • percent – A percentage value between > 0% and < 100% indicating when to stop processing. Percentage values must be quoted. 

importType

Required

Required property indicating how existing records are treated during the import. New records are always added.

  • ignore – Ignore the input payload and preserve the existing email and profile information for the subscriber. Think of this as a PUT with a "If-None-Match" header.
  • update – replaces only the email and profile elements that are provided in the input payload.  For any profile key-value pair in the subscriber database where the key is specified in the payload, the payload value replaces the database value; any other key-values in the database are preserved.  Similarly, if the email is not provided in the input payload, the existing email is preserved.  This behaves like POST /v2/subscribers/{id}/update.
  • replace – Replaces the existing email and profile with the information provided in the input payload. This behaves like PUT /v2/subscribers/{id}.
setReferred Optional

Valid values are "newOnly" and "newOrNotSubscribed". The default if setReferred is not present is not to modify the referred status.

"setReferred" = "newOnly" sets "referred" to true for new subscribers and existing subscribers who are not subscribed to any divisions.

"setReferred" = "newOrNotSubscribed" sets “referred” to true for new subscribers and existing subscribers who are not subscribed to any divisions.

For existing subscribers , either “setReferred”=“newOnly” or “setReferred”=“newOrNotSubscribed” is ignored.

For dead subscribers, either  “setReferred”=“newOnly” or “setReferred”=“newOrNotSubscribed” results in a 400 error for the individual subscriber.

resubscribe Optional

Valid values are “false”, “true”.  The default is “false”.

This parameter describes how to handle subscribers in the input payload that already exist in the database and are unsubscribed to one or more of the subscriptions to which the payload is being subscribed, and they have a previous status of “subscribed” and a current status of “unsubscribed:

  • “false” – a subscription with a previous status of “subscribed” and a current status of “unsubscribed” cannot be changed to “subscribed” through this operation.
  • “true” – a subscription status of “unsubscribed” is changed to “subscribed” through this operation.
subscription Optional

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.

targetLists Optional 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).

 

HTTP Return Codes

 

Code

Description

202 Accepted

The request has been accepted.

400 Bad Request

The request could not be understood by the server due to malformed syntax at the request level.  Verify all emails are in lower case. If there are errors at the level of the individual member, but the syntax for one or more members can be understood, they will be processed correctly with a 200 OK return code, with the errors provided in the response payload as described above.

401 Unauthorized

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

413 Request Entity Too Large

 Payload is over 2 MB (2,000,000 bytes) in size.

Request Payload: 
{
  "defaults": {
    "resubscribe": false,
    "setReferred": "newOnly",
    "subscriptions": {
      "memberOf": [
        "division01",
        "division02"
      ],
      "add": [
        "division03",
        "division04"
      ],
      "remove": [
        "division05",
        "division06"
      ]
    },
    "targetLists": {
      "memberOf": [
        "campaign01",
        "campaign02"
      ],
      "add": [
        "campaign03",
        "campaign04"
      ],
      "remove": [
        "campaign05",
        "campaign06"
      ]
    }
  },
  "errorThreshold": 100,
  "importType": "update",
  "subscribers": [
    {
      "id": "john@smith.com",
      "email": "john@smith.com",
      "profile": {
        "userAttrs": [
          { "firstName": "John" },
          { "lastName": "Smith" }
        ]
      }
    },
    {
      "id": "jane@smith.com",
      "email": "jane@smith.com",
      "profile": {
        "userAttrs": [
          { "firstName": "Jane" },
          { "lastName": "Smith" }
        ]
      },
      "subscriptions": {
        "add": [
          "division03"
        ]
      }
    },
    {
      "id": "johnny@doe.com",
      "email": "johnny@doe.com",
      "profile": {
        "userAttrs": [
          { "firstName": "Johnny" },
          { "lastName": "Doe" }
        ]
      },
      "subscriptions": {
        "add": [
          "division04"
        ],
        "remove": [
          "*"
        ]
      },
      "targetLists": {
        "memberOf": [
          "campaignXYZ"
        ]
      }
    }
  ]
}
Response Payload: 
{
  "id": "654321",
  "state": "accepted",
  "message": "Import request of subscribers accepted.",
  "lastUpdate": "2014-03-03T17:33:12Z",
  "events": [
    {
      "state": "accepted",
      "message": "Import request of subscribers accepted.",
      "time": "2014-03-03T17:33:12Z"
    }
  ],
  "request" : {
    "id": "1234-4321-567890-098765",
    "user": "db-username",
    "time": "2014-03-03T17:33:01Z",
    "uri": "https://api.yesmail.com/v2/subscribers/import"
  },
  "response": {
    "uri": "http://callers.domain.com/path",
    "ref": "callers-ref-value"
  }
}
{
  "id": "987654",
  "lastUpdate": "2014-03-03T17:33:52Z",
  "counts": {
    "completed": 1238,
    "failed": 1,
    "ignored": 1,
    "total": 1240,
    "requested": 1240
  },
  "completed ": [
    {
      "index": 0,
      "time": "2014-03-03T17:33:22Z"
    },
    {
      "index": 2,
      "time": "2014-03-03T17:33:42Z"
    },
    {
      "index": 3,
      "time": "2014-03-03T17:33:52Z"
    },
    ...
    ...
    ...
  ],
  "failed": [
    {
      "index": 1,
      "time": "2014-03-03T17:33:32Z",
      "error": {
        "status": 400,
        "message": "Invalid email address."
      }
    }
  ],
  "ignored": [
    {
      "index": 4
    }
  ]
}