Adding, updating and removing customer’s mailing lists

This guide helps you to understand how to manage mailing lists of customers manually with Custobar’s api.

Custobar manages automatically mailing lists for your customers based on subscription and unsubscription events. To manage the mailing lists of your customers manually, you may use the customer data import api to set the mailing lists of a customer.

The following examples use email addresses to identify the customers. Note that multiple customers may share an email address, thus multiple customers may be updated with a single record. To identify the customers exactly, provide the individual customer’s id.

Add customers to mailing lists

To add mailing lists for a customer send an update to customer data api, with the following JSON or CSV document.

The mailing_lists property of a customer is a list of mailing list names, that can be set, added to or removed from. To add names to the list, suffix the property with .add, i.e. mailing_lists.add.

JSON example

[
  { "email": "jane@example.org", "mailing_lists.add": ["vip"] },
  { "email": "joe@example.org", "mailing_lists.add": ["vip"] }
]

CSV example

email;mailing_lists.add
jane@example.com;vip
joe@example.com;vip

Set mailing lists of customers

To set the mailing lists of customers to exactly ones defined by you, update the customer’s mailing_lists property, with the example below.

In the example, the first customer’s mailing lists will be set to “price_group_1” and “vip”, whereas the second customer’s mailing lists are set to “price_group_3”.

JSON example

[
  { "email": "jane@example.org", "mailing_lists": ["price_group_1", "vip"] },
  { "email": "joe@example.org", "mailing_lists": ["price_group_3"] }
]

CSV example

email;mailing_lists
jane@example.com;price_group_1,vip
joe@example.com;price_group_3

Remove customers from mailing lists

To remove customers from mailing lists, update the customer’s mailing_lists property, with the example below. The example below, will remove “vip” group from the customer.

JSON example

[
  { "email": "jane@example.org", "mailing_lists.remove": ["vip"] }
]

CSV example

email;mailing_lists.remove
jane@example.com;vip

New customers and default values

If you supply an email address that does not exist in the Custobar, a new customer will be created for the address. These created customers do not have email marketing permission turned on by default and thus won’t be receiving messages sent to a mailing list.

To simultaneously to turn on the email marketing permission, set also the default value to customer’s can_email property as shown below.

JSON example

[
  { "email": "jane@example.org", "mailing_lists.add": ["vip"], "can_email.default": true },
  { "email": "joe@example.org", "mailing_lists.add": ["vip"], "can_email.default": true }
]

CSV example

email;mailing_lists.add;can_email.default
jane@example.com;vip;true
joe@example.com;vip;true

Setting the default value for can_email property works as follows.

If the customer exists and does not have the email marketing permission defined, set it as the imported default; otherwise leave it unchanged. If no customers exist with the supplied email address, create a new one and set the email marketing permission to the imported value.