Get a Newsletter API 3.0

Importing contacts from CSV

This function allows you to import multiple contacts with their attributes and subscribe them to specific lists in a simple two-step process. The data should be in the form of a raw or zipped CSV(comma separated values) file.

This is a two-step process:

Specify the import parameters
Upload your file

Step 1. Specify the import parameters.

Choose which list(s) you want the contacts to subscribe to.
Specify the mapping for your column headers, this includes both email and possible attributes, if you don´t want to import any attributes you can remove the attribute object.
Specify mode, delimiter, quotechar and escapechar. See "Default values" further down this page if you dont want to specify.

POST `/contacts/import/file/`

Possible parameters are:

lists: <array>
mapping: <array>
mode: <int 0|1|2>
delimiter: <char>
quotechar: <char>
escapechar: <char>

Example:

{
    "lists": [
        "NW3T9uQs4FJwckm",
        "ZWvs8NjJNew92yVt3s"
    ],
    "mapping": {
        "contact": {
            "email": "email column",
            "first_name": "First name",
            "last_name": "Last name"
        },
        "attributes": {
            "city": "City",
            "age": "Age"
        }
    },
    "mode": 1,
    "delimiter": ";",
    "quotechar": "\"",
    "escapechar": "\\"
}

Response 202:

{
    "url": "https://api.getanewsletter.com/v3/contacts/import/file/82Y0lPCe/",
    "hash": "82Y0lPCe",
    "lists": [
        "NW3T9uQs4FJwckm",
        "ZWvs8NjJNew92yVt3s"
    ],
    "mapping": {
        "attributes": {
            "city": "City",
            "age": "Age"
        },
        "contact": {
            "first_name": "First name",
            "last_name": "Last name",
            "email": "email column"
        }
    },
    "mode": 1,
    "delimiter": ";",
    "quotechar": "\"",
    "escapechar": "\\",
    "file": null,
    "status": 0,
    "errors_file": null
}

Step 2. Upload your file

The second step is to upload the file. When you POST the import parameters you will receive a URL in response. This is the URL you´re going to POST to in order to import your contacts. Both zipped and plain CSV files are supported.

POST `https://api.getanewsletter.com/v3/contacts/import/file/82Y0lPCe/`

Example in curl

curl -iv -F file=@$1 https://api.getanewsletter.com/v3/contacts/import/file/82Y0lPCe/
-H 'Authorization: Token ABCDEFGHIJKLMNOPQRSTUVXYZ'

If everything went ok your contacts should start uploading. To confirm this you can navigate to the URL you posted to and hopefully receive the following result:

{
    "url": "https://api.getanewsletter.com/v3/contacts/import/file/79M6PkWI1plvP/",
    "hash": "79M6PkWI1plvP",
    "lists": [
        "2Tj209dfCHt"
    ],
    "mapping": {
        "contact": {
            "first_name": "First name",
            "last_name": "Last name",
            "email": "email"
        }
    },
    "mode": 0,
    "delimiter": ";",
    "quotechar": "\"",
    "escapechar": "\\",
    "file": "protected/csv_files/contacts3_7.csv",
    "status": 30,
    "errors_file": "https://api.getanewsletter.com/v3/contacts/import/file/79M6PkWI1plvP/errors_file/"
}

You can see that the only real difference is the values for file, errors_file and status. The file parameter returns the name of the .csv file you uploaded. The errors_file parameter returns a link to a file containing possible errors. The status parameter returns the status for your upload. Possible statuses are:

Statuses

0: Waiting for file - the metadata for the import has been created and now it is waiting for the file to be uploaded
5: File uploaded - File has been uploaded successfully
10: In queue - File is in the queue and waits for processing
20: Processing - we are currently processing the uploaded file, please have in mind that this process can take long for large files
30: Completed - the file processing is completed, you can download the errors raise during the processing from the link provided in the errors_file attribute

The first step is optional so you can directly upload the file. In this case the following default values are used:

Default values

mapping: "email", "first_name" and "last_name" are matched to the respectively named columns if such exists. The "email" column is required. The rest of the column names are matched to the names of the existing attributes
mode: 0
delimiter: ;
quotechar: "
escapechar: \

The attribute mode defines the action performed if contacts with the same email address already exists. Possible values are:

0: overwrite(default) - Overwrites the object totally (like a PUT)
1: leave - Does nothing to the object (like a POST but without the error)
2: update - Updates the object with the input parameters (just like a PATCH)

Possible issues / Error messages explanation:

Message: You can not provide both file and metadata with one request. Explanation: The metadata and the file can not be provided in a single request. If you want to specify the import metadata send it first and then upload the file.

Message: Unable to find email column. Explanation: There is not a column with label matching the "email" or the provided value if using custom mapping.