Working with Lists in VerticalResponse

Overview

The following operations allow you to work with lists. Click an operation name to see details on how to use it.

For a sample proxy service that illustrates how to work with lists, see Sample configuration.

Operation	Description
createList	Creates a list.
updateList	Updates list attributes.
getList	Returns list details.
addContactToList	Adds a contact to a list.
removeContactFromList	Removes a contact from a list.

Operation details

This section provides details on the operations.

Creating a list

The createList operation creates a list.

createList

<verticalresponse.createList>
	<name>{$ctx:name}</name>
    <isPublic>{$ctx:isPublic}</isPublic>
</verticalresponse.createList>

Properties

name: Required - The name of the list.
isPublic: Optional - Whether the list is public. By default, lists are private (false).

Sample request

Following is a sample REST request that can be handled by the createList operation.

Sample Request for createList

{
	"accessToken":"4hvyvuhw7dfgujcaesq9sw5xkw9",
	"apiUrl":"https://vrapi.verticalresponse.com/api/v1", 
	"name":"TestList",
	"isPublic":"false"
}

Updating a list

The updateList operation updates a list's name and privacy status.

updateList

<verticalresponse.updateList>
	<listId>{$ctx:listId}</listId>
    <name>{$ctx:name}</name>
	<isPublic>{$ctx:isPublic}</isPublic>
</verticalresponse.updateList>

Properties

listId: Required - The ID of the list to update.
name: Required - A new name for the list. Note that you must give the list a new name, and that entering the list's current name or any other name that already exists will result in an error.
isPublic: Optional - Privacy status of the list. Lists are private by default (Boolean value).

Sample request

Following is a sample REST request that can be handled by the updateList operation.

Sample Request for updateList

{
	"accessToken":"4hvyvuhw7ujcsdaesq9sw5xkw9",
	"apiUrl":"https://vrapi.verticalresponse.com/api/v1", 
	"listId":"1099511635532",
	"name":"updatedListName",
	"isPublic":"false"
}

Retrieving list details

The getList operation returns details about a given list.

getList

<verticalresponse.getList>
	<listId>{$ctx:listId}</listId>
	<type>{$ctx:type}</type>
</verticalresponse.getList>

Properties

listId: Required - The ID of the list to be retrieved.
type: The type of attributes to return: basic, standard, or all. If set to all, it returns the list attributes as well as lists of contacts who are a part of the given list and a list of messages sent to the given list. Default is basic.

Sample request

Following is a sample REST request that can be handled by the getList operation.

Sample Request for getList

{
	"accessToken":"4hvyvuhw7ujchg3aesq9sw5xkw9",
	"apiUrl":"https://vrapi.verticalresponse.com/api/v1",
	"listId":"1099511635539",
	"type":""
}

Adding a contact to a list

The addContactToList operation 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 list.

This operation requires the contentType header to be included in init.

addContactToList

<verticalresponse.addContactToList>
	<email>{$ctx:email}</email>
	<listId>{$ctx:listId}</listId>
</verticalresponse.addContactToList>

Properties

email: Required - Email address of the contact to be added to the list.
listId: Required - The ID of the list to which the contact will be added.

This operation will not update a contact. If an existing contact email address and other attributes are provided, the API will only add the contact to the specific list and will skip any update operation.

Sample request

Following is a sample REST request that can be handled by the addContactToList operation.

Sample Request for addContactToList

{
	"accessToken":"4hvyvghuhw7ujcaesq9sw5xkw9",
	"apiUrl":"https://vrapi.verticalresponse.com/api/v1", 
	"email":"user@gmail.com",
	"listId":"1099511635510"
}

Removing a contact from a list

The removeContactFromList operation removes the subscription relationship between a contact and a list. The contact continues to exist in other lists it belongs to as well as in the “All Contacts” list. This operation does not delete a contact.

removeContactFromList

<verticalresponse.removeContactFromList>
	<contactId>{$ctx:contactId}</contactId>
    <listId>{$ctx:listId}</listId>
</verticalresponse.removeContactFromList>

Properties

contactId: Required - The contact ID of the user to be removed from the list.
listId: Required - The ID of the list from which the user will be removed.

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 only be removed from the master list by being deleted.

Sample request

Following is a sample REST request that can be handled by the removeContactFromList operation.

Sample Request for removeContactFromList

{
	"accessToken":"4hvyvuhw7ujcdfgaesq9sw5xkw9",
	"apiUrl":"https://vrapi.verticalresponse.com/api/v1",
	"listId":"1099511635510",
	"contactId":"1099513099158"
}

Sample configuration

Following is a sample proxy service that illustrates how to connect to VerticalResponse with the init operation and use the createList operation. The sample request for this proxy can be found in createList sample request. You can use this sample as a template for using other operations in this category.

As a best practice, create a separate sequence for handling the response payload for errors. In the following sample, this sequence is "faultHandlerSeq". For more information, see Configuring the VerticalResponse Fault Handler Sequence.

Sample Proxy

<?xml version="1.0" encoding="UTF-8"?>
<proxy xmlns="http://ws.apache.org/ns/synapse" name="verticalresponse_createList" transports="https,http" statistics="disable" trace="disable" startOnLoad="true">
	 <target>
	 <inSequence  onError="faultHandlerSeq">
      <property name="accessToken" expression="json-eval($.accessToken)"/>
      <property name="apiUrl" expression="json-eval($.apiUrl)"/>
      <property name="name" expression="json-eval($.name)"/>
      <property name="isPublic" expression="json-eval($.isPublic)"/>
      <verticalresponse.init>
         <accessToken>{$ctx:accessToken}</accessToken>
         <apiUrl>{$ctx:apiUrl}</apiUrl>
      </verticalresponse.init>
      <verticalresponse.createList>
         <name>{$ctx:name}</name>
         <isPublic>{$ctx:isPublic}</isPublic>
      </verticalresponse.createList>
	  <filter source="$axis2:HTTP_SC" regex="^[^2][0-9][0-9]">
            <then>
               <switch source="$axis2:HTTP_SC">
                 <case regex="401">
                     <property name="ERROR_CODE" value="600401"/>	 
					 <property name="ERROR_MESSAGE" expression="json-eval($.error.message)"/>
                     <property name="error_description" expression="json-eval($.error.url)"/>
                  </case>
                  <case regex="404">
                     <property name="ERROR_CODE" value="600404"/>					  
					 <property name="ERROR_MESSAGE" expression="json-eval($.error.message)"/>
                     <property name="error_description" expression="json-eval($.error.url)"/>
                  </case>
				  <case regex="403">
                     <property name="ERROR_CODE" value="600403"/>
					 <property name="ERROR_MESSAGE" expression="json-eval($.error.message)"/>
                     <property name="error_description" expression="json-eval($.error.url)"/>
                  </case> 			  
                  <case regex="400">
                     <property name="ERROR_CODE" value="600400"/>			 
					 <property name="ERROR_MESSAGE" expression="json-eval($.error.message)"/>
                     <property name="error_description" expression="json-eval($.error.url)"/>
                  </case>
                  <case regex="500">
                     <property name="ERROR_CODE" value="600500"/>  
					 <property name="ERROR_MESSAGE" expression="json-eval($.error.message)"/>
                     <property name="error_description" expression="json-eval($.error.url)"/>
                  </case>
                  <default> 
				     <property name="ERROR_CODE" expression="$axis2:HTTP_SC"/>
					 <property name="ERROR_MESSAGE" expression="json-eval($.error.message)"/>
                     <property name="error_description" expression="json-eval($.error.url)"/>
                  </default>
               </switch> 
			   <sequence key="faultHandlerSeq"/>
            </then>
         </filter> 
	   <respond/>
	 </inSequence>
	  <outSequence>
	    <send/>
	  </outSequence>
	 </target>
   <description/>
  </proxy>

WSO2 ESB Connectors Documentation

Working with Lists in VerticalResponse

Overview

Operation details

Creating a list

Properties

Sample request

Related VerticalResponse documentation

Updating a list

Properties

Sample request

Related VerticalResponse documentation

Retrieving list details

Properties

Sample request

Related VerticalResponse documentation

Adding a contact to a list

Properties

Sample request

Related VerticalResponse documentation

Removing a contact from a list

Properties

Sample request

Related VerticalResponse documentation

Sample configuration