Lists
Contents
Remove Contacts from a List in Batch
VerticalResponse allows users to create lists to efficiently manage their contacts. Users can create multiple lists and organize their contacts within these lists. Lists are helpful while sending email campaigns. If contacts are organized into lists, it is easy to send more targeted campaigns. Each VR account has a Master List, which contains all of the contacts for that account. When creating a contact, the user has the option to create the contact within a particular list or create the contact under the master list, then add the contact to lists later. The Master List referred to as “All Contacts” cannot be deleted.
VR provides APIs to create, update, delete, list, and read lists. Users can also add and remove contacts from lists via the API. Similar to a batch contact create, there is also a remove contacts in batch , which will remove "n" contacts from a given list. Also, there is an API that returns the messages sent to a particular list.
| Attributes | Description | Rules |
|---|---|---|
| name | Name of the list | Required to create list |
| is_public | Privacy status of the list | Optional to create list |
| size | Number of contacts in the list | |
| reach | Number of mailable contacts in the list |
Every list in VR has a privacy status. They are set to private by default. If a list’s status is turned to public, end users who wish to unsubscribe from lists can see it. If the list remains private, end users cannot see those lists while exercising their unsubscribe options.
Lists also use the type (basic, standard, all ) parameters for all GET API calls. This will determine the data returned.
| Type | Attributes |
|---|---|
| basic | id |
| name | |
| is_public | |
| created_at | |
| last_sent_at | |
| standard | id |
| name | |
| is_public | |
| public_name | |
| created_at | |
| last_sent_at | |
| updated_at | |
| size | |
| reach | |
| all | type=all returns the same attributes as type=standard |
The Create API creates a list given a list name and an optional is_public parameter. Lists are private by default. is_public parameter if present must be a Boolean value. On success the API returns the URI of the newly created list.If the is_public flag is true, then the public_name attribute cannot be empty. With the public_name attribute, the user has the ability to provide a public name to their lists which is what their contacts will see when updating preferences from an email.
Error
If the list name already exists, the API returns an error.
URL
https://vrapi.verticalresponse.com/api/v1/listsMethod
POST
Sample Request
The update API updates list attributes like name, is_public. The list name cannot be empty or null. On success the URI of the updated list is returned. Trying to update a list with a name that already exists will result in error.
URL
https://vrapi.verticalresponse.com/api/v1/lists/:id
Method
PUT
Sample Request
This API will delete the given list. The contacts in the list will not be deleted. On success, the API will return the appropriate message.
Error
The “All Contacts” list cannot be deleted. If its list id is used, then the API returns an error.
URL
https://vrapi.verticalresponse.com/api/v1/lists/:id
Method
DELETE
Sample Request
Sample Response
The list read API returns details about a given list. It takes in a type attribute and returns list attributes depending on that. For the attributes returned by different type parameters, refer to the lists overview section . The type parameter when set to "all" will return in addition to the list attributes ,lists of contacts who are a part of the given list and a list of messages sent to the given list .If no type parameter is passed in, the default type is basic.
URL
https://vrapi.verticalresponse.com/api/v1/lists/:id
Method
GET
Sample Request
The API returns stats for a given list. The following stats are returned for a list.
| Attribute | Description |
|---|---|
| id | id of the list |
| name | Name of the list |
| is_public | Privacy status of the list |
| size | Size of the given list. |
| reach | Number of mailable contacts in the given list. |
| inactive_contacts | Number of non mailable contacts in the given list. |
| on_hold_contacts | Number of contacts that are on hold in the given list. |
| unsubscribed | Number of contacts that unsubscribed from the given list. |
| bounced | Number of contacts that bounced from the given list. |
| created_at | Timestamp when the list was created. |
| updated_at | Timestamp when the list was updated |
URL
https://vrapi.verticalresponse.com/api/v1/lists/:id/stats
Method
GET
Sample Request
Sample Response
The Add Contact API adds an existing contact to the specified list. The API expects an email address of the contact to be added to the list. If the email address of the contact is unique and does not exist in the user’s account, the contact will be created and added to the specified list as well as the master’s list. Like the contact create API, only the email address is required, other contact attributes are optional.
Note: This API will not update a contact. If an existing contact email address plus other attributes are provided, the API will only add the contact to the specific list and will skip any update operation.
On Success, URI of the contact in the list is returned.
URL
https://vrapi.verticalresponse.com/api/v1/lists/13885/contacts
Method
POST
Sample Request
The remove contact removes the subscription relationship between a contact and a list. The contact continues to exist in other lists it is a part of as well as the “All Contacts” list. This API does not delete a contact. On success, the API returns the appropriate message.
Error
If the list id specified is the master list,the API returns an error. A contact cannot be removed from the master list. Contacts can be removed from the master list by deleting them.
URL
https://vrapi.verticalresponse.com/api/v1/lists/list_id/contacts/contact_id
Method
DELETE
Sample Request
Sample Response
List: Remove Contacts in Batch
This API removes a list of contacts from the specified list. The API takes in an array of contacts and the list id from which they should be removed. These contacts are removed from the list, they are not deleted. The contact continues to exist in other lists it is a part of as well as the “All Contacts” list. On success, the API returns the appropriate message.
Error
If the list id specified is the master list,the API returns an error. A contact cannot be removed from the master list. Contacts can be removed from the master list by deleting them.
URL
https://vrapi.verticalresponse.com/api/v1/lists/list_id/contacts
Method
DELETE
Sample Request
Sample Response
This API returns an array of lists present in a user’s account in addition to its attributes depending on the type attribute. For details on the data returned by the type attributes, check the lists overview section. The default type is basic.
URL
https://vrapi.verticalresponse.com/api/v1/lists
Method
GET
Sample Request
Sample Response
This API returns details of the emails that were sent to the given list. The API like other GET requests will accept a type parameter with “basic”, “standard” or “all” values. The URI of emails sent to the list along with other attributes are returned. To see what basic, standard and all parameters return, check the Messages section. The default type is basic. Emails are returned in the order of most recently sent.If no emails were sent to the given list, an empty array will be returned.
URL
https://vrapi.verticalresponse.com/api/v1/lists/<list_id>/messages
Method
GET
Sample Request
Sample Response
