Lists

Contents

Overview

Create a List

Update a List

Delete a List

List : Stats

Add a Contact to a List

Remove a Contact from a List

Remove Contacts from a List in Batch

List all Lists

Messages send to a given List

Overview

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

Create

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/lists

Method

POST

Sample Request

 

Update

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

Delete

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


Read

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

List : Stats

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

List: Add Contact

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

List: Remove Contact

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

Lists: list

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

Lists: Messages

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