This guide helps you to understand how to manage mailing lists of customers manually with Custobar's api. If you want to update mailing lists manually with the Data import function in Custobar, then read this guide about manual import.
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.