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

Value

Description

scheduled

The import has been scheduled and is waiting to start

downloading

The import is downloading its data from a URL (1)

splitting

The import is being prepared and analyzed

importing

The import is now being processed

paused

The import has been paused

finished

The import finished successfully

failed

There was an internal error during this import

cancelled

The import was permanently cancelled

Mapping Array

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

Key

Description

email

Required The email address for this subscriber record.

status

The status for this subscriber record. See the “Subscriber Statuses” table for a list of values.

email_format

The email format for this subscriber. Can be html, text or both. Only applies if the mailing list has the email format field enabled.

subscribe_time

The time at which the subscriber subscribed.

subscribe_ip

The IP from which the subscriber subscribed.

remove_time

The time at which the subscriber was removed from the list.

remove_ip

The IP from which the subscriber was removed from the list.

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 andPreferred Cars as a checkboxes field:

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.

begins_atdatetime

The time at which this import is scheduled to begin. Default: the current time

overwriteboolean

This import should overwrite existing subscribers with the same email address. Default: false

overwrite_whathash

custom_fieldsboolean

When overwriting existing subscribers, this import should overwrite the custom fields. Default: true.

autoresponderboolean

When overwriting existing subscribers, run autoresponders for the updated subscribers. Default: true.

confirmedboolean

When overwriting existing subscribers, this import should update the confirmed field. Default: false.

formatboolean

When overwriting existing subscribers, this import should update the format field. Default: false.

statusboolean

When overwriting existing subscribers, this import should update the status field. Default: false.

Pause or unpause a subscriber import

URL

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

Name

Description

added

Email addresses that were added

updated

Email addresses that were updated

failed

A CSV file of failed rows in the import – the last column is an error message

skipped_overwrite

Email addresses that were skipped because overwriting is not enabled

skipped_active

Email addresses that were skipped because this import does not update active subscribers

skipped_unsubscribed

Email addresses that were skipped because this import does not update unsubscribed subscribers

skipped_scomp

Email addresses that were skipped because this import does not update spam complaint subscribers

skipped_bounced

Email addresses that were skipped because this import does not update bounced subscribers

skipped_deactivated

Email addresses that were skipped because this import does not update deactivated subscribers

skipped_duplicate

Email addresses that were skipped because the record was a duplicate found earlier in the file

skipped_over_limit

Email addresses that were skipped because the organization subscriber limit was reached

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