Manage contacts via CSV Upload

To do a CSV upload, you need to complete the following three steps:

1. Create the CSV content in a format compatible with the Mailjet API.
2. Upload the CSV content to a Mailjet server via an API call.
3. Import the CSV file using the /csvimport content

The first row must include the names of the different properties included in the CSV - e.g. "email", "first_name", "age". If there is no /contactmetadata object with the respective property name, if will be created automatically by the API with DataType: string.

The data for each contact should be included on a new line.

"email","age"
"foo@example.org",42
"bar@example.com",13
"sam@ple.co.uk",37

"foo@example.org",2018/10/12
"bar@example.com",2016/10/12
"sam@ple.co.uk",2017/10/12

To upload the CSV you need to specify the target contact list ID and, of course, the CSV content.

# Import the CSV file through the DATA API
curl -s \
-X POST \
--user "$MJ_APIKEY_PUBLIC:$MJ_APIKEY_PRIVATE" \
https://api.mailjet.com/v3/DATA/contactslist/$ID_CONTACTLIST/CSVData/text:plain \
-H "Content-Type: text/plain" \
--data-binary "@./test.csv"

Save the ID - it’s used to specify the Data ID during POST /csvimport.

You now need to use the uploaded data to manage the contacts in a specific contact list using the /csvimport resource.

The actions you can perform are:

• addforce : Add the contacts to the list and subscribe all of them. If the contact is already present in the list as unsubscribed, it will be forcibly subscribed once again.
• addnoforce : Add the contacts to the list and subscribe them to it. If the contact is already present, it will retain its subscription status, i.e. if a contact is part of the list, but unsubscribed, it will not be forcibly subscribed again.
• remove : Remove the contacts from the list
• unsub: Unsubscribe the contacts from the list

Select the action / method, the list ID and the data ID in the payload:

curl -s \
	-X POST \
	--user "$MJ_APIKEY_PUBLIC:$MJ_APIKEY_PRIVATE" \
	https://api.mailjet.com/v3/REST/csvimport \
	-H 'Content-Type: application/json' \
	-d '{
      "ErrTreshold":"1",
      "ImportOptions":"",
      "Method":"addnoforce",
      "ContactsListID":"123456",
      "DataID":"98765432123456789"
	}'

{
	"Count": 1,
	"Data": [
		{
			"ErrTreshold": 1,
			"ImportOptions": "",
			"Method": "addnoforce",
			"AliveAt": "2018-01-01T00:00:00",
			"ContactsListID": 123456,
			"Count": 12,
			"Current": 10,
			"DataID": 98765432123456780,
			"Errcount": 0,
			"ID": 987654,
			"JobEnd": "2018-01-01T00:00:00",
			"JobStart": "2018-01-01T00:00:00",
			"RequestAt": "2018-01-01T00:00:00",
			"Status": "Upload"
		}
	],
	"Total": 1
}

The ID returned is the ID of the import job - use it to monitor the import progress.

When trying to import contact data with type datetime, you should define an additional property in the payload - ImportOptions. Its value should be passed as a string, containing the following options:

• DateTimeFormat : it shows the format of the datetime in the CSV file. It can be represented as any combination of the acronyms for year (yy), month (mm), day (dd), hour (hh), minute (nn), second (ss). The date is separated from the time with an empty space. The separators for the dates could be a dash(-), slash (/) or dot (.). The separator for the time is a colon (:). The RFC3339 format is also supported (e.g. 'yyyy-mm-ddThh:nn:ss+01:00').

• TimezoneOffset : used to select timezone offset. The value is an integer in the -12 to 12 range.

• FieldNames : specifies the names of the fields that are going to be imported. This corresponds to the first row of the CSV, when you import contacts without datetime contact data. All properties that will be modified should be added to the import options, following the exact same order as the columns in the CSV.

# Create: A wrapper for the CSV importer
curl -s \
	-X POST \
	--user "$MJ_APIKEY_PUBLIC:$MJ_APIKEY_PRIVATE" \
	https://api.mailjet.com/v3/REST/csvimport \
	-H 'Content-Type: application/json' \
	-d '{
		"ContactsListID":"$ID_CONTACTLIST",
		"DataID":"$ID_DATA",
		"Method":"addnoforce",
		"ImportOptions":"{\"DateTimeFormat\": \"yyyy/mm/dd\",\"TimezoneOffset\": 2,\"FieldNames\": [\"email\",\"birthday\"]}"
	}'

You can now make sure the task is completed successfully. You might need multiple checks as a huge amount of data may take some time to be processed (several hours are not uncommon). Using the JobID returned in the previous step, you can retrieve the job status.

curl -s \
	-X GET \
	--user "$MJ_APIKEY_PUBLIC:$MJ_APIKEY_PRIVATE" \
	https://api.mailjet.com/v3/REST/csvimport/$importjob_ID \

{
	"Count": 1,
	"Data": [
		{
			"ErrTreshold": 1,
			"ImportOptions": "",
			"Method": "addnoforce",
			"AliveAt": "2018-01-01T00:00:00",
			"ContactsListID": 123456,
			"Count": 12,
			"Current": 10,
			"DataID": 98765432123456780,
			"Errcount": 0,
			"ID": 987654,
			"JobEnd": "2018-01-01T00:00:00",
			"JobStart": "2018-01-01T00:00:00",
			"RequestAt": "2018-01-01T00:00:00",
			"Status": "Upload"
		}
	],
	"Total": 1
}

If the ErrCount in the response of the GET /csvimport/$job_ID request is different than 0, you can retrieve a file with information about the errors that occurred during the import.

curl --user "$MJ_APIKEY_PUBLIC:$MJ_APIKEY_PRIVATE" \
https://api.mailjet.com/v3/DATA/BatchJob/$job_id/CSVError/text:csv

The returned file will be a copy of your original file with an added column describing the error for each line in error.

File uploaded with error:

"email","age"
"foo@example.org",42
"bar@example.com"
"sam@ple.co.uk",37

Error file content:

email,age,error
"bar@example.com", ###Too few columns at line