Back to main menu


More contact actions, more endpoints

We are excited to announce that we've released more Contact List API endpoints that will make managing individual contacts and listing subscriptions faster.

God with glasses drilling into hard drive with colorful background



Following our API team’s hard work on the 'Newsletter' action endpoints, we are excited to announce that we've released more API endpoints that will make managing individual contacts and listing subscriptions faster.

We've extended the Contact and the Contactslist resources to include five new actions:






Check out also our guides about contact subscription and bulk contact management.

Let's look at some of this in action (excuse the pun):


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:


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 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!

Popular posts

Hermes rides a firework next to a Goddess in front of a night sky with more fireworks

Top email marketing trends for 2022

To the outsiders, it can sometimes feel like email hasn't changed that much since it was created. Maybe this is why some are so persistent in...

Read more

Hermes on a moped delivering mail to a mailbox

Reducing email’s carbon footprint

When it comes to protecting our planet, every step toward cleaner practices – small and big – counts. So, what if we told you that emailing, as clean and green as it seems...

Read more

Mother's day gift for Hera

Marketing calendar 2024: Dates you shouldn’t miss this year

We finally got through 2023 (phew!) and Q1 is just around the corner. It’s time for you to start scribbling down your New Year’s Resolutions to make sure we start the year with a bang. If you’ve found your way here, we’re guessing that’s because creating a winning...

Read more

It's never been easier to build connected experiences. Start sending with Mailjet today.Get started on your path
CTA icon