Subscriber Imports API

• Table of Contents
• Remote Lists
• Definitions
  • Subscriber Import States
  • Mapping Array
  • Default Custom Fields
  • Date/Time Fields
• Get a list of subscriber imports
  • URL
  • Request Parameters
  • Pagination
  • Order
  • Response
  • Example
• Get expanded details about a subscriber import
  • URL
  • Response
  • Example
• Create a new subscriber import
  • URL
  • Request
  • Response
  • Example
• Pause or unpause a subscriber import
  • URL
  • Response
• Cancel a subscriber import
  • URL
  • Response
• Read import logs
  • URL
  • Types of logs
  • Response

Remote Lists

Subscriber Imports are not available on Remote Lists. API calls to these endpoints will return an error message if attempted on a Remote List.

Definitions

Subscriber Import States

Mapping Array

The mapping array declares how each column of the CSV import maps to the subscriber record.

Custom Fields can be mapped to columns in the import file using their name. For example, for a CSV file that contains four columns (Email, Subscribe Time, Subscribe IP and data for a custom field First Name).

"mapping": [
  "email",
  "subscribe_time",
  "subscribe_ip",
  "First Name"
]

Default Custom Fields

The default_custom_fields on a subscriber import are values that are set for each new subscriber in the import.

If overwrite_custom_fields is set, then these values will also be applied to updated subscribers.

The default_custom_fields values should be set as a hash of custom field names to values.

Here is an example, with Subscriber Name as a text field and Preferred Cars as a checkboxes field:

"default_custom_fields": {
  "Subscriber Name": "Bob Example",
  "Preferred Cars": [ "Toyota", "Kia" ]
}

Date/Time Fields

Custom field import data can include date/times for the following fields:

• Date Custom Fields
• Day of Year Custom Fields
• Subscribe Time
• Remove Time
• Confirm Time

The following date/time formats are accepted for these values.

• 1994-03-11T14:30:47-06:00
• March 11, 1994 14:30
• March 11, 1994
• 11 March 1994
• 03-11-1994 2:30:47pm
• 03-11-1994 14:30:47
• 03-11-1994 2:30pm
• 03-11-1994 14:30
• 03-11-1994
• 03/11/1994 2:30:47pm
• 03/11/1994 14:30:47
• 03/11/1994 2:30pm
• 03/11/1994 14:30
• 03/11/1994
• 1994-03-11 14:30
• 1994-03-11

Note: Other formats may be parsed successfully, but we recommend that you stick to this list of accepted formats.

Note: The ambiguous date formats (for example, should 5/11/2014 be May 11, 2014 or November 5, 2014) are clarified by the date_format field. See the documentation below for details on how to set it.

Get a list of subscriber imports

Get a list of subscriber imports, filterable by state.

URL

GET /ga/api/v2/subscriber_imports

GET /ga/api/v2/subscriber_imports?scope=active

GET /ga/api/v2/subscriber_imports?scope=finished

GET /ga/api/v2/subscriber_imports?scope=all

To get the subscriber imports for a specific mailing list:

GET /ga/api/v2/mailing_lists/:mailing_list_id/subscriber_imports

GET /ga/api/v2/mailing_lists/:mailing_list_id/subscriber_imports?scope=:scope

Request Parameters

Provide a scope parameter to filter the subscriber imports returned.

This API returns the first 100 records by default and supports pagination.

Pagination

To query additional records, provide page and per_page parameters. The page parameter starts at 0. The per_page parameter defaults to 100 and the maximum allowed is 500.

For example to get the second page:

GET /ga/api/v2/subscriber_imports?scope=all&page=1&per_page=100

The response will also contain the following extra parameters:

Order

Imports are returned in this order:

1. Non-finished/cancelled imports with the soonest scheduled time first (oldest begins_at first)
2. Finished/cancelled imports with the most recently completed first (newest finished_at first)

Response

The response will be a JSON array where each element contains the following keys.

Example

> GET /ga/api/mailing_lists/1/subscriber_imports HTTP/1.1
> Authorization: Basic MToyMTk5MzY2YTAzYWM3OWE1N2YwYTRlNzYwZWQyZTNkOGJkNzBjOWYw
> Accept: application/json
> Content-Type: application/json

< Content-Type: application/json; charset=utf-8
< X-UA-Compatible: IE=Edge
< ETag: "d64fa2907baedf9f003a3dc9c5f6c483"
< Cache-Control: max-age=0, private, must-revalidate
< Set-Cookie: _session_id=f1e4a07566f9b284bd84cac355afde56; path=/; HttpOnly
< X-Request-Id: 2478536084b570ad8c223c0f3ad11010
< X-Runtime: 0.023404
< Connection: close
< Server: thin 1.5.0 codename Knife

{
  "success": true,
  "error_code": null,
  "error_message": null,
  "page": 0,
  "per_page": 100,
  "data": [
    {
      "id": 15,
      "mailing_list_id": 1,
      "mailing_list_name": "Default Mailing List",
      "created_at": "2015-01-15T20:53:18Z",
      "state": "finished",
      "begins_at": "2015-01-15T20:53:18Z",
      "finished_at": "2015-01-15T20:53:20Z",
      "stats": {
        "number_of_records": 2,
        "records_imported": 2
      },
      "file_source": {
        "type": "json",
        "filename": "data"
      }
    },
    {
      "id": 14,
      "mailing_list_id": 1,
      "mailing_list_name": "Default Mailing List",
      "created_at": "2015-01-15T20:51:31Z",
      "state": "finished",
      "begins_at": "2015-01-15T20:51:31Z",
      "finished_at": "2015-01-15T20:51:33Z",
      "stats": {
        "number_of_records": 1,
        "records_imported": 1
      },
      "file_source": {
        "type": "json",
        "filename": "data"
      }
    }
  ],
  "num_records": 2,
  "num_pages": 1
}

Get expanded details about a subscriber import

Get details about a single subscriber import, with more details than the index provides.

URL

GET /ga/api/v2/subscriber_imports/:id

Response

The response will be a JSON object with the following keys.

Example

> GET /ga/api/mailing_lists/1/subscriber_imports/15 HTTP/1.1
> Authorization: Basic MToyMTk5MzY2YTAzYWM3OWE1N2YwYTRlNzYwZWQyZTNkOGJkNzBjOWYw
> Accept: application/json
> Content-Type: application/json

< Content-Type: application/json; charset=utf-8
< X-UA-Compatible: IE=Edge
< ETag: "d36e7bf33aa83b076d172cce7cd19e0e"
< Cache-Control: max-age=0, private, must-revalidate
< Set-Cookie: _session_id=a023e6220d8d6929013c6035f8a0ae5c; path=/; HttpOnly
< X-Request-Id: 42b255c3d98d4a86928afd5bd87deb69
< X-Runtime: 0.020476
< Connection: close
< Server: thin 1.5.0 codename Knife

{
  "success": true,
  "data": {
    "id": 15,
    "mailing_list_id": 1,
    "mailing_list_name": "Default Mailing List",
    "created_at": "2015-01-15T20:53:18Z",
    "state": "finished",
    "begins_at": "2015-01-15T20:53:18Z",
    "finished_at": "2015-01-15T20:53:20Z",
    "stats": {
      "number_of_records": 2,
      "records_imported": 2,
      "subscribers": {
        "added": 1,
        "updated": 1,
        "failed": 0,
        "skipped_overwrite": 0,
        "skipped_active": 0,
        "skipped_unsubscribed": 0,
        "skipped_scomp": 0,
        "skipped_bounced": 0,
        "skipped_deactivated": 0,
        "skipped_duplicate": 0,
        "skipped_over_limit": 0
      }
    },
    "autoresponders": {
      "subscription": {
        "trigger": true,
        "also_trigger_on_updated_subscribers": false,
      },
      "api": {
        "trigger_new": null,
        "trigger_updated": null
      }
    },
    "file_source": {
      "type": "json",
      "filename": "data"
    },
    "file_format": {
      "character_set": "utf-8",
      "csv_has_headers": true,
      "csv_field_enclosure": "\"",
      "csv_field_separator": ",",
      "date_format": "mdy"
    },
    "subscriber_defaults": {
      "status": "active"
    },
    "overwrite": true,
    "overwrite_when_status": {
      "active": true,
      "unsubscribed": false,
      "bounced": false,
      "deactivated": false,
      "scomp": false
    },
    "column_mapping": [
      "email"
    ],
    "default_custom_fields": {
    },
    "overwrite_what": {
      "custom_fields": true,
      "confirmed": false,
      "format": false,
      "status": false
    }
  },
  "error_code": null,
  "error_message": null
}

Create a new subscriber import

Start a new subscriber import, providing all details needed to run.

Subscriber imports that retrieve data from a URL will attempt to download from that URL up to three times. The first retry will be 10 seconds after the first failure. The final retry will occur 50 seconds after the second failure. For these imports, the data will be loaded at the time the imports is scheduled to begin. This retry schedule does not apply if the URL did not finish sending after 15 minutes of downloading. In such cases, the URL will not be retried.

URL

POST /ga/api/v2/mailing_lists/:mailing_list_id/subscriber_imports

Request

The request should be a JSON object under the subscriber_import key with the keys listed below. See the example request below.

Response

The response will be a JSON object in the same format as the subscriber import show endpoint.

Example

> POST /ga/api/mailing_lists/1/subscriber_imports HTTP/1.1
> Authorization: Basic MTo0MDRhYzkzZTVjYmY4NzI4YjcyMzU5M2FmM2VkMTcwZDk0Yjc0Mjg4
> Accept: application/json
> Content-Type: application/json

{
  "subscriber_import": {
    "begins_at": "now",
    "column_mapping": [
      "email"
    ],
    "file_source": {
      "type": "json",
      "content": "email\[email protected]\[email protected]\n"
    },
    "autoresponders": {
      "subscription": {
        "trigger": true,
        "also_trigger_on_updated_subscribers": false,
      },
      "api": {
        "trigger_new": null,
        "trigger_updated": null
      }
    },
    "file_format": {
      "character_set": "iso-8859-1",
      "csv_has_headers": true,
      "csv_field_separator": ",",
      "csv_field_enclosure": "\"",
      "date_format": "mdy"
    },
    "overwrite": true,
    "overwrite_what": {
      "custom_fields": true,
      "confirmed": false,
      "format": false,
      "status": false
    },
    "overwrite_when_status": {
      "active": true,
      "unsubscribed": false,
      "bounced": false,
      "deactivated": false,
      "scomp": false
    },
    "subscriber_defaults": {
      "status": "active",
      "confirmed": true,
      "format": "html"
    },
    "default_custom_fields": {
      "First Name": "Bobbie"
    }
  }
}

< Content-Type: application/json; charset=utf-8
< X-UA-Compatible: IE=Edge
< ETag: "ad1f04869c6928097908511b2b7333e0"
< Cache-Control: max-age=0, private, must-revalidate
< Set-Cookie: _session_id=09d7790d36289b7d7ab61dd863c14514; path=/; HttpOnly
< X-Request-Id: 5963b6949c36a75cf0c5c93d845c3af8
< X-Runtime: 0.122245
< Connection: close
< Server: thin 1.5.0 codename Knife

{
  "success": true,
  "data": {
    "id": 1,
    "mailing_list_id": 1,
    "mailing_list_name": "Default Mailing List",
    "created_at": "2015-01-15T21:07:30Z",
    "state": "scheduled",
    "begins_at": "2015-01-15T21:07:30Z",
    "finished_at": null,
    "stats": {
      "number_of_records": null,
      "records_imported": 0,
      "subscribers": {
        "added": 0,
        "updated": 0,
        "failed": 0,
        "skipped_overwrite": 0,
        "skipped_active": 0,
        "skipped_unsubscribed": 0,
        "skipped_scomp": 0,
        "skipped_bounced": 0,
        "skipped_deactivated": 0,
        "skipped_duplicate": 0,
        "skipped_over_limit": 0
      }
    },
    "autoresponders": {
      "subscription": {
        "trigger": true,
        "also_trigger_on_updated_subscribers": false,
      },
      "api": {
        "trigger_new": null,
        "trigger_updated": null
      }
    },
    "file_source": {
      "type": "json",
      "filename": "data"
    },
    "file_format": {
      "character_set": "iso-8859-1",
      "csv_has_headers": true,
      "csv_field_enclosure": "\"",
      "csv_field_separator": ",",
      "date_format": "mdy"
    },
    "subscriber_defaults": {
      "status": "active"
    },
    "overwrite": true,
    "overwrite_when_status": {
      "active": true,
      "unsubscribed": false,
      "bounced": false,
      "deactivated": false,
      "scomp": false
    },
    "column_mapping": [
      "email"
    ],
    "default_custom_fields": {
      "First Name": "Bobbie"
    },
    "overwrite_what": {
      "custom_fields": true,
      "confirmed": false,
      "format": false,
      "status": false
    }
  },
  "error_code": null,
  "error_message": null
}

Pause or unpause a subscriber import

Subscriber imports that are in progress can be paused and later unpaused.

URL

POST /ga/api/v2/subscriber_imports/:id/pause

POST /ga/api/v2/subscriber_imports/:id/unpause

Response

The response will be a JSON object in the same format to the subscriber import show endpoint.

If the subscriber import cannot be paused (or unpaused), this endpoint will return a validation_failed error.

Cancel a subscriber import

Subscriber imports that haven’t yet finished can be cancelled.

URL

POST /ga/api/v2/subscriber_imports/:id/cancel

Response

The response will be a JSON object in the same format to the subscriber import show endpoint.

If the subscriber import cannot be cancelled (because it has finished), this endpoint will return a validation_failed error.

Read import logs

Subscriber imports generate a variety of logs. These logs can be accessed at the included URLs below.

URL

GET /ga/api/v2/subscriber_imports/:id/logs/added

GET /ga/api/v2/subscriber_imports/:id/logs/updated

GET /ga/api/v2/subscriber_imports/:id/logs/failed

GET /ga/api/v2/subscriber_imports/:id/logs/skipped_overwrite

GET /ga/api/v2/subscriber_imports/:id/logs/skipped_active

GET /ga/api/v2/subscriber_imports/:id/logs/skipped_unsubscribed

GET /ga/api/v2/subscriber_imports/:id/logs/skipped_scomp

GET /ga/api/v2/subscriber_imports/:id/logs/skipped_bounced

GET /ga/api/v2/subscriber_imports/:id/logs/skipped_deactivated

GET /ga/api/v2/subscriber_imports/:id/logs/skipped_duplicate

GET /ga/api/v2/subscriber_imports/:id/logs/skipped_over_limit

Types of logs

Response

For the log_failed endpoint, the response will be a CSV file. The last row will be the errors that prevented the subscriber record from being saved.

For the rest of the endpoints, the response will be a flat list of email addresses, separated by newlines, that meet the description listed above.

If the log file cannot be found, a not_found error will be returned. This can be the case in any of the following situations:

• The import hasn’t yet started
• The import has no logs for that classification, because no items in that classification were generated
• The import has had its logs purged

Note: Logs are purged 7 days after the import finished running.