More contact actions, more endpoints

CONTACT

Manage contact subscription in lists

The /managecontactslists action makes it easier to manage (add, remove or unsubscribe) a contact from one or multiple lists in one call:

Here, we can select the contact by $ID (this can be numerical ID of the contact from the API or email address) and then use the “managecontactlists” action to actually manage the contact list. Let's have a quick look at the properties in that array:

•  ListID : the numerical ID of the contact list that you want to manage

•  Action : What you want to do with the contact and the list:

• addforce: add the contact to the list and subscribe them if not already

  • addnoforce: add the contact to the list, but do not change the status of subscribe / unsubscribe from it's current value

  • remove: remove the contact from the lis

  •  unsub: leave the contact on the list, but unsubscribe them from future campaigns

Managing and uploading multiple contacts (asynchronous action)

Applying the /managemanycontacts action to contact allows us to upload a nice big lump of JSON with our contacts and subscribe them to lists. It looks like a big call, so let's split it up.

• ContactsList - This is entirely optional (but useful!), allowing you to add contacts en masse to lists and follows the structure above

• Contacts - Mandatory, the actual contacts only need an email for the call to be valid. 'Name' a global property and the 'Properties' object can contain any custom properties set by /contactmetadata

This call to the API is asynchronous to efficiently deal with this large volume of email. It will provide you a response immediately and continue the job in the background. The returned data will look like this:

The JobID helps track the progress and result of an upload with the following call:

Sometimes things might not go as expected and that’s okay. Possible error messages include:

• **Error: If there are any errors (for instance incorrectly formatted JSON), it will be noted here. (More comprehensive details about the error can be found in the URL given in the ‘Errorfile’ property)**

• Status: The background job’s current status. Possible values are: Prepare, Importing, Completed or Error.

Getting contact subscriptions

Now you that know how to manage individual contact subscriptions within lists and how to bulk upload contacts, you might also want to know how to identify which lists an individual contact is subscribed to. You can do this with the /getcontactslists action:

CONTACTSLIST

On the other hand, you might want to add a new contact to an existing contact list (i.e. from a form capture):

After identifying the list to be added to with $ID being the ID of the list, it's a case of specifying the Contact email. As with the example above, Name and Properties are optional, only 'Email' and 'Action' are mandatory.

Let's look at managing multiple contacts (in one call):

Just like /managemanycontacts for the /contact endpoint, we specify the action to be taken (in this case 'addnoforce') and array of contacts. As before, 'email' is mandatory, with the option to add 'Name' and custom properties. As with /managemanycontacts for the /contact endpoint, the result is a job ID to track the progress of the underlying background job.

Need to check which contacts are on a list?

Here, we can add 'contactslist' as a param with it's ID - setting the limit to -1 just displays all contacts on the list, if you want a specific sample (say 100), then you can use that value instead.

Wrapping things up

That’s a quick run down of the extra functionality and the improved methods for working with multiple contacts lists using the API. For a deeper dive, check out our developer documentation at dev.mailjet.com. In particular, check out our guides about contact subscription and bulk contact management to start. We’ve also updated our PHP and Ruby wrappers to include the added functionality.

Happy coding!