Bulk Contact Management

Managing contacts is a tedious task if you need to do a call for each contact separately. Use the resources below to add, remove or unsubscribe multiple contacts with a single call.

post

Add, remove or unsubscribe a list of contacts to/from a selection of contact lists

post

Add, unsubscribe or remove the contacts present in a list to / from another list

post

Add, remove or unsubscribe a list of contacts to/from a specific contact list

post

Use an uploaded CSV list of contacts to manage their presence and subscription status in a contact list

post

/contact/managemanycontacts

Manage multiple contacts by adding, removing or unsubscribing them from multiple contact lists. Separate actions are set for each list and implemented for all contacts listed. Once you submit the `POST` request, it will return a `JobID`, which you can use to verify the success of the `POST` request, as well as see what kind of errors came up.

Full API path

https://api.mailjet.com/v3/REST/contact/managemanycontacts

Body parameters

ContactsLists

array

A JSON array, containing information about the contact lists and the actions performed on all contacts for each list. If the `ContactsList` is not specified, the contacts will be added to the global contact list.

ListID

integer

Unique numeric ID of the contact list.

Action

string

Action to be performed on the contacts for this list:

  • addforce - Add the contacts to this list and subscribe all of them. Any contacts already present in the list and unsubscribed from it will be forcibly subscribed once again.

  • addnoforce - Add the contacts to this list and subscribe them to it. Any contacts already present will retain their 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 this list.

  • unsub - Unsubscribe the contacts from this list.

Contacts

array, required

A JSON array, containing information about the contacts. Each contact is represented by its `Email`, `Name`, optional campaign exclusion state and `Properties`.

Email

string

The email address for the contact.

Name

string

User-selected name for the contact.

IsExcludedFromCampaigns

boolean

When true, the contact will be added to the exclusion list and will not be receiving any marketing emails.

Default value: false

Properties

object

A JSON object containing contact properties and their values. Each property is listed with its name as the parameter name, and the property value as the parameter value. The property objects must have been created beforehand via the /contactmetadata resource.

Responses

Note: You can find all the errors related to API in the error page

Count

integer

Data

array

JobID

integer

Unique numeric Job ID returned after a POST /contact/managemanycontacts request. Use it to monitor the progress and success of the request.

Total

integer

post

/contactslist/{list_ID or list_address}/importlist

Add, unsubscribe or remove the contacts present in a list to / from another list. The list ID specified in the body of the payload is the source, while ID in the path specifies the destination list.

Full API path

https://api.mailjet.com/v3/REST/contactslist/{list_ID}/importlist

Path parameters

list_ID

integer, required

Unique numeric ID assigned to the destination contact list.

list_address

Unique email address generated by Mailjet for the destination list. This address which can be used only via Mailjet's SMTP server to reach all contacts in it. It is displayed in the Address property of the list. The full email address will be {list_address}@lists.mailjet.com.

Body parameters

Action

string

Action to be performed on the destination list:

  • addforce - Add the contacts to this list and subscribe all of them. If the contact is already present in the list and unsubscribed from, it will be forcibly subscribed once again.
  • addnoforce - Add the contacts to this 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.
  • unsub - Unsubscribe the contacts from this list
  • duplicate-override - Add the contacts and duplicate their subscription status from the source list to the destination list. E.g. if in the source list a contact is unsubscribed and in the destination list the same contact is subscribed, the contact will be marked as unsubscribed in the destination list.
  • duplicate-no-override - Add the contacts without duplicating their subscription status. E.g. if in the source list a contact is unsubscribed and in the destination list the same contact is subscribed, the contact will remain subscribed in the destination list.

ListID

integer

Unique numeric ID of the source contact list.

Responses

Note: You can find all the errors related to API in the error page

Count

integer

Data

array

JobID

integer

Job ID assigned to a POST /contactslist/{list_id}/importlist request. Use it to monitor the progress and success of the request.

Total

integer

post

/contactslist/{list_ID or list_address}/managemanycontacts

Manage multiple contacts by adding, removing or unsubscribing them from a specific contact list. Once you submit the `POST` request, it will return a `JobID`, which you can use to verify the success of the `POST` request, as well as see what kind of errors came up.

Full API path

https://api.mailjet.com/v3/REST/contactslist/{list_ID}/managemanycontacts

Path parameters

list_ID

integer, required

Unique numeric ID assigned to this contact list.

list_address

Unique email address generated by Mailjet for this contact list. This address which can be used only via Mailjet's SMTP server to reach all contacts in it. It is displayed in the Address property of the list. The full email address will be {list_address}@lists.mailjet.com.

Body parameters

Action

string

Action to be performed on the contacts for this list:

  • addforce - Add the contacts to this list and subscribe all of them. If the contact is already present in the list and unsubscribed from, it will be forcibly subscribed once again.
  • addnoforce - Add the contacts to this 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 this list
  • unsub - Unsubscribe the contacts from this list

Contacts

array

A JSON array, containing information about the contacts. Each contact is represented by its `Email`, `Name`, an optional exclusion state and `Properties`.

Email

string

The email address for this contact.

Name

string

User-selected name for this contact.

Properties

object

A JSON object containing contact properties and their values. Each property is listed with its name as the parameter name, and the property value as the parameter value. The properties must have been created beforehand.

IsExcludedFromCampaigns

boolean

When true, the contact will be added to the exclusion list and will not be receiving any marketing emails.

Default value: false

Responses

Note: You can find all the errors related to API in the error page

Count

integer

Data

array

JobID

integer

Job ID assigned to a POST /contactslist/{list_id}/managemanycontacts request. Use it to monitor the progress and success of the request.

Total

integer

post

/csvimport

Add, remove or unsubscribe a list of contacts to/from a specific contact list by using a CSV uploaded to the Mailjet Data server. The CSV needs to be uploaded via the `/contactslist/{list_id}/CSVData/text:plain` endpoint.

Full API path

https://api.mailjet.com/v3/REST/csvimport

Body parameters

ErrTreshold

integer

Maximum number of errors allowed during the processing of the contacts, before the import job is aborted.

ImportOptions

string

A string with a JSON structure describing the import options in effect.

Method

string

Action to be performed on the contacts in the CSV data for this list:

  • addforce - Add the contacts to this list and subscribe all of them. If the contact is already present in the list and unsubscribed from, it will be forcibly subscribed once again.
  • addnoforce - Add the contacts to this 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 this list
  • unsub - Unsubscribe the contacts from this list

ContactsListID

integer, required

Unique numeric ID of the list, where you want to use the uploaded CSV data. Interchangeable with ContactsListAlt.

DataID

integer, required

Unique numeric ID of the CSV data you want to use.

Responses

Note: You can find all the errors related to API in the error page

Count

integer

Data

array

ErrTreshold

integer

Maximum number of errors allowed during the processing of the contacts, before the import job is aborted.

ImportOptions

string

A string with a JSON structure describing the import options in effect.

Method

string

Action to be performed on the contacts in the CSV data for this list:

  • addforce - Add the contacts to this list and subscribe all of them. If the contact is already present in the list and unsubscribed from, it will be forcibly subscribed once again.
  • addnoforce - Add the contacts to this 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 this list
  • unsub - Unsubscribe the contacts from this list

AliveAt

string

Timestamp indicating when the CSV import background job reported a status. Returns an empty value upon initial POST request.

ContactsListID

integer

Unique numeric ID of the list, where you want to use the uploaded CSV data.

Count

integer

Number of contacts detected in the CSV file. Returns 0 value upon initial POST request.

Current

integer

Number of processed contacts so far. Returns 0 value upon initial POST request.

DataID

integer

Unique numeric ID of the CSV data used for this request.

Errcount

integer

Number of errors encountered while processing the contacts in the CSV file. Returns 0 value upon initial POST request.

ID

integer

Unique numeric ID of this import job.

JobEnd

string

Timestamp indicating when the import job has ended. Returns an empty value upon initial POST request.

JobStart

string

Timestamp indicating when the import job was started. Returns an empty value upon initial POST request.

RequestAt

string

Timestamp indicating when the import job was requested. Returns an empty value upon initial POST request.

Status

string

Current status of this import job. During POST, the only allowed value is Upload. During PUT, the only allowed value is Abort.

Possible values:

  • Upload
  • Completed
  • Abort

Total

integer