POST subscribers/file-import

Overview

This method is useful for integrations where the source data is recieved as a flat file or is very large in size, greater than one hundered thousand subscribers. The file must contain the customer defined id, usually email, and may include any profile attributes. Only those columns/attributes defined in the mapping will be imported. All other columns will be ignored. This flexibility eases the integration challenges when source file exports cannot be modified.

This requests supports importing of subscribers, their attributes, mapping of those attributes, subscriptions, list membership, and a user defined error threshold. To determine which attributes are defined use GET /v2/subscribers?view=schema

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/file-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

defaults Optional

Optional sections where default subscriptions and target list memberships can be defined. Any values defined in this section will be added to all subscribers in the source file.

  • resubscribe – Optional boolean with default value false. Must be set to true for any subscriptions to be added to a subscriber that has previously unsubscribed.
  • setReferred – Optional property controlling whether a subscriber can be marked as "referred".
    • "newOnly" – Set "setReferred" to "newOnly" to only mark new subscribers as "referred". Existing subscribers, regardless of current subscription state is ignored.
    • "newOrNotSubscribed" – Set "setReferred" to "newOrNotSubscribed" to mark any new or currently globally unsubscribed subscribers as "referred". Existing subscribers with one or more subscriptions are ignored.
  • subscriptions – Optional section to control subscription updates. If "memberOf" is present it will ensure only the listed subscriptions (divisions) are subscribed, all others will be unsubscribed. "add" and "remove" will be ignored if "memberOf" is present, otherwise "add" lists subscriptions to add (ignored if already subscribed) and "remove" lists subscriptions to remove ("*" will remove all subscriptions). "remove" is applied before "add".
    • add – Optional list of subscriptions to add. Any existing subscriptions will be ignored. Subscribe events will be added for new subscriptions.
    • remove – Optional list of subscriptions to remove; use "*" to remove all existing subscriptions. Unsubscribe events will be added for any subscriptions that are removed.
    • memberOf – Optional list of subscriptions for the subscriber. This list overrides any "add" and "remove" lists for the same subscriber. Subscribe and unsubscribe events will be added for any subscription changes.
  • targetLists – Optional section to control target lists memberships. If "memberOf" is present it will ensure the subscriber is only a member of the listed target lists. "add" and "remove" will be ignored if "memberOf" is present, otherwise "add" lists the target lists to add the subscriber to (ignored if already a member) and "remove" lists the target lists to remove the subscriber from ("*" will remove all memberships). "remove" is applied before "add".
    • add – Optional list of target lists to add the subscriber to. Any existing memberships will be ignored.
    • remove – Optional list of target lists to remove the subscriber from; use "*" to remove all existing memberships.
    • memberOf – Optional list of target lists for the subscriber. This list overrides any "add" and "remove" lists for the same subscriber.

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

Optional

Optional property indicating how existing records are treated during the import, default value is update. New records are always added.

  • ignore – Skip source records if the destination list load table already has the same email address, inserts the source record if no match is found. Think of this as a PUT with a "If-None-Match" header.
  • update – Will update existing records with the data available, or insert new records if no match is found. Think of this as a PUT when there is no match and as a POST (partial) for a match.
  • replace – Will replace existing records and insert new records with no match. Think of this as a straight PUT request.

source

Required headers – Optional property, defaults to false if not present. Indicates whether there is a header row in the source files.
  • key – The key must match a column name in the destination list load table. The request will fail if the name in the map does not exists in the list load table.
    •  "," – Comma is the default value, matching a standard CSV format.
    • "\t" - Tab is used to separate column values in the source file.
    •  "|" – A pipe symbol is used to separate column values in the source file.
    • ";" – A semi-colon is used to separate column values in the source file.
  • uri – Required URI for where the source data file is located. Allowed protocols are HTTP, HTTPS and FTP. Basic authentication embedded in the URI is supported. Examples:​
    • http://my.host.com/path/data.csv
    • https://username:password@my.host.com/path/data.txt
    • ftp://username:password@ftp.host.com/path/data.csv

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.

If number of failed requests exceeds the error threshold, then no records will be updated or added.

401 Unauthorized

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

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",
  "source": {
    "headers": false,
    "mappings": [
      { "id": 0 },
      { "email": 1 },
      { "FirstName": 2 },
      { "LastName": 3 }
    ],
    "separator": "\t",
    "uri": "http://my.host.com/path/file.txt"
  }
}
Response Payload: 
{
  "id": "654321",
  "state": "accepted",
  "message": "File import of subscribers accepted.",
  "lastUpdate": "2014-03-03T17:33:12Z",
  "events": [
    {
      "state": "accepted",
      "message": "File import 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/file-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
    }
  ]
}