List Import

The list import service is to allow the import of large amounts of data into existing lists.


fetchRecent

array list_import.fetchRecent( int listId )

Fetch information about recent list imports.

Parameters

listId

ID of the list.

Return Values

Returns an indexed array of associative arrays for each import. The index is returned in reverse chronological order.

Key

Type

Comment

import_id

string

unique identifier for the import

status

string

status of the import

record_type

string

one of 'campaign', 'seed', 'both'

progress

int

list import percentage complete

total_rows

string

total rows in the CSV

processed_rows

string

number of records that have been processed

successful_rows

string

number of new records that were successfully imported

duplicate_rows

int

number of recipients that already existed in the list

failed_rows

int

number of rows that failed to import

started_ts

timestamp

datetime that the import was started

finished_ts

timestamp

datetime that the import completed

Note the difference between rows and records in the row count values.
A row is a line in the text of a CSV file.
A record is a single line of CSV data.

processed_rows = successful_rows + duplicate_rows + failed_rows
However, if a record contains a field with line-breaks, then even when progress == 100 :
total_rows != processed_rows



importUploadedFile

int list_import.importUploadedFile( int listId, string uploadKey, array importMapping, array importOptions, string type )

This method enables you to import a file based on an uploaded file key.

Parameters

listId

ID of the list to which you're importing.

uploadKey

The upload key of the file to import, see File_Upload.

importMapping

Associative array of column to profile field mapping.

If passing an empty array, the system will attempt to auto-detect the import mapping based on the CSV header row. Headers must be enabled in the CSV options for this to work. All fields must be mapped, unless setting the autodetect.ignore_missing option to true.


Type

Description

Key

int

CSV column ID (0-indexed)

Value

int/string

Profile field ID or keyword

Not all columns must be mapped, but there must be one column mapped to the special keyword email in order to specify which column contains the recipient email address

It is also possible to specify one of the keywords subscribed or unsubscribed to map a boolean column to the list's subscription status column, in the manner implied by the keyword. If neither of these keywords is mapped, each recipient added to the list will be subscribed. Please also see the overrideSubscribed import option to understand how the subscription status of recipients that already exist on the list will be affected.

importOptions

An associative array specifying additional options for the import process. Various options are available:

Key

Required

Type

Description

csv

Yes

array

See below

override

No

boolean

Default true.
When true, if the recipient is already on the list, override their existing recordType with the value specified for this import's type parameter

overrideSubscribed

No

boolean

Default true.
When true, if the recipient is already on the list, mark them as subscribed (or use the value defined in the importMapping), regardless of their current list-subscription status.
This only affects this list's subscription flag for this recipient. It will not affect other lists, or remove them from either the Master Bounce or Master Unsubscribe lists

truncate

No

boolean

Default false.
When true, recipients subscribed to this list will be removed.
Recipients on the list that are NOT subscribed will be left untouched, to preserve their list unsubscribe state.

notify

No

array

See below

autoDetect

No

array

See below

csv

An associative array of CSV options:

Key

Required

Type

Description

has_headers

Yes

boolean

Specifies whether the first row describes the columns

delimiter

No

char

The CSV data's field separator character. Defaults to comma

enclosure

No

char

The CSV data's text enclosing character. Defaults to double quote

notify

An associative array of notification options. Does not need to be set, but if defined must include both keys described below.

Key

Type

Description

type

string

'all' or 'error'. Defines the types of notification to send.

email

string

Comma-separated list of email addresses

autoDetect

An associative array of auto-detect options. All keys are optional.

Key

Type

Description

ignore_missing

boolean

true to ignore CSV columns which are not mapped to a valid profile field. Default false.

type

The type of records being imported. This can be one of three possible values:

Name

Description

campaign

Recipients will be sent the live campaign only

seed

Recipients won't be sent emails as part of a live campaign send, but are available to receive seed test emails

both

Both live campaign sends and seed tests available

Return Values

Returns unique identifier for the import process.



getProgress

string list_import.getProgress( int importId )

Returns a range of information about any current or complete import progress. Information includes percent complete, standard statistics, timestamps of the start and end of the import and the estimated time of arrival.

Parameters

importId

ID of the import of which you want to retrieve the progress.

Return Values

Returns an array of available and calculated information. See below for an example.

array(
    'percent'    => float,
    'statistics' => array(
        'total_rows'      => integer,
        'processed_rows'  => integer,
        'successful_rows' => integer,
        'failed_rows'     => integer,
        'duplicate_rows'  => integer
    ),
    'timestamps' => array(
        'unix' => array(
            'started'  => integer,
            'finished' => integer
        ),
        'database' => array(
            'started'  => string,
            'finished' => string
        )
    ),
    'eta'        => array(
        'seconds'   => integer,
        'breakdown' => array(
            'days'    => integer,
            'hours'   => integer,
            'minutes' => integer,
            'seconds' => integer
        )
    )
)



Service

list_import

Methods