VerticalResponse Partner API Methods

addListMember

The addListMember() method adds a single member to the specified list. If the new list member fails validation, an exception is thrown. Method should not be used to add more than one list member record at a time. Please refer to appendFileToList() or appendFileToListBackground() methods instead.

Input [vrtypens:addListMemberArgs]

session_id [xsd:string] (required)
Your API session id.

list_member [vrtypens:ListMember] (required)
The list member argument must contain a list_id. The list_name and list_type fields are not used. The member_data must at least contain an entry for email_address.

validate_postal_address [xsd:boolean]
This parameter is deprecated and is not supported in future releases

Output [vrtypens:ListMember]

The output is the newly-added list member.

Examples

Java Perl PHP Ruby C#.NET

Map memberData = new HashMap();
memberData.put( "email_address", "your@company.com" ) );
memberData.put( "first_name", "API" );
memberData.put( "last_name", "Customer" );
ListMember listMember = new ListMember();
listMember.setList_id( listId );
listMember.setMember_data( buildNVDictionary( memberData ) );
AddListMemberArgs addListMemberArgs = new AddListMemberArgs( sessionId, listMember, Boolean.FALSE );
vrapi.addListMember( addListMemberArgs )

$vrapi->addListMember( {
    session_id => $sid,
    list_member => {
        list_id     => $lid,
        member_data => [
            {
                name  =>'email_address',
                value => $email,
            },
            {
                name  => 'first_name',
                value => 'Allen',
            },
            {
                name  => 'last_name',
                value => 'Corona'
            },
        ],
    },
} );

$vrapi->addListMember( array(
    'session_id'  => $sid,
    'list_member' => array(
        'list_id'     => $lid,
        'member_data' => array(
            array(
                'name'  =>'email_address',
                'value' => $email,
            ),
            array(
                'name'  => 'first_name',
                'value' => 'Allen',
            ),
            array(
                'name'  => 'last_name',
                'value' => 'Corona',
            ),
        ),
    ),
) );

 vr.addListMember({
    'session_id'  => sid
    'list_member' => {
         'list_id'     => lid,
         'member_data' =>  [ 
                {
                 'name'  => 'email_address',
                 'value' => email
                },
                {
                 'name'  => 'first_name',
                 'value' => 'Allen'
                }
})

NVPair[] member_data = new NVPair[3];

NVPair email = new NVPair();
email.name = "email_address";
email.value = "user@company.com";
member_data[0] = email;

NVPair first_name = new NVPair();
first_name.name = "first_name";
first_name.value = "allen";
member_data[1] = first_name;

NVPair last_name = new NVPair();
last_name.name = "last_name";
last_name.value = "corona";
member_data[1] = last_name;

ListMember list_member = new ListMember();
list_member.list_id = listId;
list_member.member_data = member_data;

addListMemberArgs objAddListMember = new addListMemberArgs();
objAddListMember.session_id = _sSessionId;
objAddListMember.list_member = list_member;

ListMember response = vr.ddListMember(objAddListMember);

appendFileToList

The appendFileToList() method adds the members listed in the specified file to the specified list. For the file argument, provide a filename and contents. For PHP, Perl, Ruby, .NET, there is no need to base64-encode the list. Records that fail validation are returned to the user with an explanation, and the location of a file containing the rejected records is returned for downloading as well.

Input [vrtypens:appendFileToListArgs]

session_id [xsd:string] (required)
Your API session id.

list_id [xsd:int] (required)
The ID of the list to add new recipients to

file [vrtypens:FileSpec] (required)
A FileSpec containing the contents of the file to append. The "delimiter" must be set here, and either the "location" or "contents" field must be set.

fields [vrtypens:ArrayOfString] (required)
A list of the fields represented by the columns in the file. Any column in the file whose field name is given as "_ignore_" is ignored when recipients are being created.

validate_postal_addresses [xsd:boolean]
If this is set to true and the list member's postal address is invalid, then a fault will be thrown.

favor_existing_values [xsd:boolean]
For uploaded list members that are already in the account, if there's a conflict between the uploaded list member's fields and the existing list member fields, then the uploaded list member's fields win the conflict, and the existing list member's fields are updated. Set this to a true value for the existing list member's fields to win the conflict such that the existing list member's fields are not updated. This argument only applies to calls made by an account with "Master List" list data storage.

overwrite_non_nulls_with_nulls_ok [xsd:boolean]
Normally a non-null value would never get overwritten during an upload process. Set this to a true value to override this default behavior. This argument only applies to calls made by an account with "Master List" list data storage.

overwrite_partial_postal_addresses_ok [xsd:boolean]
Postal address fields are: first_name, last_name, address_1, address_2, city, state, postalcode. Normally these are treated as one big field during the upload process and no individual piece is updated without the other being updated. Set this to a true value to override this default behavior. This will have the effect of causing any updated list member to no longer be considered postcard mailable. This argument only applies to calls made by an account with "Master List" list data storage.

ignore_first_line [xsd:boolean]
Set this to a true value if the first line in the uploaded file should be ignore (i.e., if it's some sort of header row). This argument only applies to calls made by an account with "Master List" list data storage.

notification_email_address [xsd:string]
This is required for the background version of this method. When the result is ready, this email address will receive a notification that includes a link that can be used to download the result.

Output [vrtypens:appendFileToListResult]

The output describes new statistics for the list that the recipients were added to.

Examples

Java Perl PHP Ruby C#.NET

          
            // Load file into FileSpec
            int listId = 5555;
            File file = new File( "list_data.csv" );
            byte[] fileContents = new byte[(int)file.length()];
            new FileInputStream( file ).read( fileContents );
            FileSpec fileSpec = new FileSpec( "list_data.csv", "csv", null, fileContents );
            
            // add file contents to new list
            // fileFieldNames contains the fields that each column in the file represents - in order
            String[] fileFieldNames = { "customer_id", "email_address", "first_name", "last_name", "product" };
            AppendFileToListResult result = vrapi.appendFileToList( new AppendFileToListArgs(
                sessionId,
                listId,
                fileSpec,
                fileFieldNames,
                Boolean.FALSE,
            null ) );


use File::Slurp;

my $fcontents   = read_file($location);
my $filename = 'list_2010.csv';

$ap_file_resp = $vrapi->appendFileToList( {
    session_id => $sid,
    list_id    => $lid,
    file       => {
       filename => $filename,
       delimiter=> 'csv',
       contents => $fcontents,
    },
    fields => [
        'email_address',
        'first_name',
        'last_name',
    ],
} );

$file_name = "list_2019.csv";
if (file_exists($file_name)) {
    $handle = fopen($file_name,'rb');                
    $fcontents = fread($handle,filesize($file_name));
    fclose($handle);
    
    $ap_file_resp = $vrapi->appendFileToList( array(
        'session_id' => $sid,
        'list_id'    => $lid,
        'file'       => array(
            'filename'  => $file_name,
            'delimiter' => 'csv',
            'contents'  => $fcontents,
        ),
        'fields' => array(
            'email_address',
            'first_name',
            'last_name',
        ),
    ) );
}

filename  = 'list_2019.csv'
fcontents = File.new(filename)

vr.appendFileToList({
      'session_id' => sid,
      'delimiter'  => 'tab',
      'list_id'    =>  lid,
      'file'       => {
          'filename' => filename,
           'delimiter' => 'tab',
            'contents' => filename.read
  },
  'fields'     => [ "email_address", "first_name", "last_name"]
})

byte[] FileContents = new System.Text.ASCIIEncoding().GetBytes(fileData);

FileSpec fsFileCotents = new FileSpec();
fsFileCotents.filename = "list_2010.csv";
fsFileCotents.delimiter = "csv";
fsFileCotents.contents = FileContents;

string[] arrFields = new string[] { "first_name", "email_address", "last_name" };

appendFileToListArgs objAppendFileToList = new appendFileToListArgs();
objAppendFileToList.session_id = _sSessionId;
objAppendFileToList.list_id = iListId;
objAppendFileToList.file = fsFileCotents;
objAppendFileToList.fields = arrFields;

appendFileToListResult results = vr.appendFileToList(objAppendFileToList);

appendFileToListBackground

The appendFileToListBackground() method performs the same tasks as the appendFileToList() method, but does so after detaching and running as a background process. As a result, no meaningful data is returned to the caller (unless a fault is thrown during the data validation stage).

Input [vrtypens:appendFileToListArgs]

session_id [xsd:string] (required)
Your API session id.

list_id [xsd:int] (required)
The ID of the list to add new recipients to

file [vrtypens:FileSpec] (required)
A FileSpec containing the contents of the file to append. The "delimiter" must be set here, and either the "location" or "contents" field must be set.

validate_postal_addresses [xsd:boolean]
If this is set to true and the list member's postal address is invalid, then a fault will be thrown.

Output [xsd:int]

The output is the ID of the background task.

Examples

Java Perl PHP Ruby C#.NET

File file = new File( "list_data.csv" );
byte[] fileContents = new byte[(int)file.length()];
new FileInputStream( file ).read( fileContents );
FileSpec fileSpec = new FileSpec( "list_data.csv", "csv", null, fileContents );
           
// add file contents to new list
// fileFieldNames contains the fields that each column in the file represents - in order
String[] fileFieldNames = { "customer_id", "email_address", "first_name", "last_name", "product" };
int result = vrapi.appendFileToListBackground( new AppendFileToListArgs(
    sessionId,
    listId,
    fileSpec,
    fileFieldNames,
    Boolean.FALSE,
    "yourname@company.com"
) );

$bg_id = $vrapi->appendFileToListBackground( {
    session_id => $sid,
    list_id    => $lid,
    file       => {
        filename   => 'list_2019.csv',
        delimiter  => 'csv',
        contents   => $fcontents,
    },
    fields => [
        'email_address',
        'first_name',
        'last_name',
    ],
    notification_email_address => 'yourname@company.com',
} );

$bg_id = $vrapi->appendFileToListBackground( array(
    'session_id' => $sid,
    'list_id'    => $lid,
    'file'       => array(
        'filename'  => 'list_2019.csv',
        'delimiter' => 'csv',
        'contents'  => $fcontents,
    ),
    'fields' => array(
        'email_address',
        'first_name',
        'last_name',
    ),
    'notification_email_address' => 'yourname@company.com',
) );

bg_id = vr.appendFileToList({
  'session_id' => sid,
  'delimiter'  => 'tab',
  'list_id'    =>  lid,
  'file'       => {
       'filename' => filename,
       'delimiter' => 'tab',
        'contents' => list.read
  },
  'fields'     => [ "email_address", "first_name", "last_name"]
  'notification_email_address' => 'yourname@company.com'
})

byte[] FileContents = new System.Text.ASCIIEncoding().GetBytes(fileData);
FileSpec fsFileCotents = new FileSpec();
fsFileCotents.filename = "list_2010.csv";
fsFileCotents.delimiter = "csv";
fsFileCotents.contents = FileContents;

string[] arrFields = new string[] { "first_name", "email_address", "last_name" };

appendFileToListArgs objAppendFileToList = new appendFileToListArgs();
objAppendFileToList.session_id = _sSessionId;
objAppendFileToList.list_id = iListId;
objAppendFileToList.file = fsFileCotents;
objAppendFileToList.fields = arrFields;
objAppendFileToList.notification_email_address = "user@company.com"

int backTaskId = vr.appendFileToListBackground(objAppendFileToList);

appendTemplateCampaignModule

The appendTemplateCampaignModule() adds a module to the end of a template campaign's list of modules.

Input [vrtypens:appendTemplateCampaignModuleArgs]

session_id [xsd:string] (required)
Your API session id.

campaign_id [xsd:int] (required)
The ID of the campaign to add the module to.

module [vrtypens:TemplateCampaignModule] (required)
The module to append. You must provide a "template_id" field. Providing a "position" field is not allowed.

Output [xsd:boolean]

The output is always true.

Examples

Perl PHP

$vrapi->appendTemplateCampaignModule( {
    session_id => $sid,
    campaign_id => $cid,
    module => {
        template_id => 6,
        title => 'Upcoming Events',
        copy  => ' New Features!',
        redirect_url => 'http://www.verticalresponse.com',
        click_test => 'VerticalResponse',
        images => [
            {
            filename => 'VR_logo.jpg',
            contents => $fimage,
            },
        ],
    },
} };

$vrapi->appendTemplateCampaignModule( array(                                     
    'session_id'  => $sid,
    'campaign_id' => $cid,
    'module'  => array(
        'template_id' => 6,
        'title' => 'Upcoming Events',
        'copy'  => ' New Features!',
        'redirect_url' => 'http://www.verticalresponse.com',
        'click_test' => 'VerticalResponse',
        'images' => array(
            array(
                'filename' => 'VR_logo.jpg',
                'contents' => $fimage,
            ),
        ),
    ),
) );

calculateCampaignAudience

The calculateCampaignAudience() method determines the number of list members that will receive a given campaign, and provides details about the number of records rejected due to duplication, address validation failure, etc.

Input [vrtypens:calculateCampaignAudienceArgs]

session_id [xsd:string] (required)
Your API session id.

campaign_id [xsd:int] (required)
The ID of the campaign whose audience is to be determined.

Output [vrtypens:calculateCampaignAudienceResult]

Examples

Perl PHP Ruby C#.NET

$vrapi->calculateCampaignAudience( {
    session_id => $sid,
    campaign_id => $cid,
} );

$vrapi->calculateCampaignAudience( array(
    'session_id'  => $sid,
    'campaign_id' => $cid,
) );

vr.calculateCampaignAudience({
    'session_id'  => sid,
    'campaign_id' => cid,
})

calculateCampaignAudienceArgs objCalculateAudience = new calculateCampaignAudienceArgs();
objCalculateAudience.session_id  = _sSessionId;
objCalculateAudience.campaign_id = iCampaignId;

vr.calculateCampaignAudience(objCalculateAudience);

canCallMethod

The canCallMethod() method determines whether the current session is allowed to call the specified server method.

Input [vrtypens:canCallMethodArgs]

session_id [xsd:string] (required)
Your API session id.

method_name [xsd:string] (required)
The name of the method.

Output [xsd:boolean]

The output indicates whether you have permission to call the given method.

Examples

Java Perl PHP Ruby C#.NET

String methodName = "calculateCampaignAudience";
CanCallMethodArgs args = new CanCallMethodArgs();
args.setMethod_name(methodName);
args.setSession_id(sessionId);
boolean stuff = vrapi.canCallMethod(args);

$vrapi->canCallMethod( {
    session_id => $sid,
    method_name => 'calculateCampaignAudience',
} );

$vrapi->canCallMethod( array(
    'session_id' => $sid,
    'method_name' => 'calculateCampaignAudience',
) );

vr.canCallMethod({
    'session_id'  => sid,
    'method_name' => 'calculateCampaignAudience',
})

canCallMethodArgs objCanCall = new canCallMethodArgs();
objCanCall.session_id = _sSessionId;
objCanCall.method_name = "calculateCampaignAudience";

objVR.canCallMethod(objCanCall);

compileCampaignRecipientResults

The compileCampaignRecipientResults() method compiles a new mailing list based on the recipient responses to a given campaign. This new list can be pulled from all, or a subset, of the lists that were mailed in the campaign and/or to a subset of the recipient responses (OPEN, CLICK, SALE, NONE) of interest. In addition, the user may specify which standard or custom fields will be copied from the mailed list(s) into the compiled list.

Input [vrtypens:compileCampaignRecipientResultsArgs]

session_id [xsd:string] (required)
Your API session id.

campaign_id [xsd:int] (required)
The id of the campaign whose recipient results are being fetched.

list_name [xsd:string] (required)
The name of the new list that will be created

fields_to_include [vrtypens:ArrayOfString] (required)
An array of the names of list fields to include as fields in the result.

restrict_responses [vrtypens:ArrayOfString]
An array of the only response types that should be reported on. Valid items for this array are:

OPEN
CLICK
SALE
BOUNCE
UNSUBSCRIBE
NONE

restrict_lists [vrtypens:ArrayOfInteger]
An array of ids of the lists whose recipients the result should be restricted to.

Output [vrtypens:compileCampaignRecipientResultsResult]

The output contains the id of the new list and the size of that list.

Examples

Perl PHP Ruby C#.NET

$vrapi->compileCampaignRecipientResults( {
    session_id => $sid,
    campaign_id => $cid,
    list_name => 'new_list_name_to_be_created',
    restrict_responses => [ "OPEN", "CLICK" ],
} );

$vrapi->compileCampaignRecipientResults( array(
    'session_id' => $sid,
    'campaign_id' => $cid,
    'list_name' => 'new_list_name_to_be_created',
    'restrict_responses' => array( "OPEN", "CLICK" ),
) );

vr.compileCampaignRecipientResults({
    'session_id'  => sid,
    'campaign_id' => cid,
    'list_name'   => 'new_list_name_to_be_created',
    'restrict_responses' => [ 'OPEN', 'CLICK'],
})

compileCampaignRecipientResultsArgs objCompileRec = new compileCampaignRecipientResultsArgs();
objCompileRec.session_id = _sSessionId;k
objCompileRec.campaign_id = iCampaignId;
objCompileRec.list_name   = "new_list_name_to_be_created";
objCompileRec.restrict_responses = new string[] { "OPEN", "CLICK"}

vr.compileCampaignRecipientResults(objCompileRec);

compileCampaignRecipientResultsBackground

The asynchronous version of compileCampaignRecipientResults(). This method is invoked and the results are emailed to the caller.

Input [vrtypens:compileCampaignRecipientResultsArgs]

session_id [xsd:string] (required)
Your API session id.

campaign_id [xsd:int] (required)
The id of the campaign whose recipient results are being fetched.

list_name [xsd:string] (required)
The name of the new list that will be created

fields_to_include [vrtypens:ArrayOfString] (required)
An array of the names of list fields to include as fields in the result.

restrict_responses [vrtypens:ArrayOfString]
An array of the only response types that should be reported on. Valid items for this array are:

OPEN
CLICK
SALE
BOUNCE
UNSUBSCRIBE
NONE

restrict_lists [vrtypens:ArrayOfInteger]
An array of ids of the lists whose recipients the result should be restricted to.

Output [xsd:int]

The output is the ID of the background task.

Examples

Perl PHP Ruby C#.NET

$vrapi->compileCampaignRecipientResultsBackground( {
    session_id => $sid,
    campaign_id => $cid,
    list_name => 'new_list_name_to_be_created',
    restrict_responses => [ "OPEN", "CLICK" ],
    notification_email_address => 'api-support@verticalresponse.com'
} );

$vrapi->compileCampaignRecipientResultsBackground( array(
    'session_id' => $sid,
    'campaign_id' => $cid,
    'list_name' => 'new_list_name_to_be_created',
    'restrict_responses' => array( "OPEN", "CLICK" ),
    'notification_email_address' => 'api-support@verticalresponse.com',
) );

vr.compileCampaignRecipientResultsBackground({
    'session_id'  => sid,
    'campaign_id' => cid,
    'list_name'   => 'new_list_name_to_be_created',
    'restrict_responses' => [ 'OPEN', 'CLICK'],
    'notification_email_address' => 'api-support@verticalresponse.com",
})

compileCampaignRecipientResultsArgs objCompileRec = new compileCampaignRecipientResultsArgs();
objCompileRec.session_id = _sSessionId;k
objCompileRec.campaign_id = iCampaignId;
objCompileRec.list_name   = "new_list_name_to_be_created";
objCompileRec.restrict_responses = new string[] { "OPEN", "CLICK"}
objCompileRec.notification_email_address = "api-support@verticalresponse.com";

vr.compileCampaignRecipientResultsBackground(objCompileRec);

compileSegmentationQuery

The compileSegmentationQuery() method compiles one or more mailing lists based on the results of a given segmentation query.

Input [vrtypens:compileSegmentationQueryArgs]

session_id [xsd:string] (required)
Your API session id.

segmentation_query_id [xsd:int]

output_lists [vrtypens:ArrayOfSegmentationQueryOutputList]

notification_email_address [xsd:string]

Output [vrtypens:ArrayOfList]

compileSegmentationQueryBackground

The asynchronous version of compileSegmentationQuery(). This method is invoked and the results are emailed to the caller.

Input [vrtypens:compileSegmentationQueryArgs]

session_id [xsd:string] (required)
Your API session id.

segmentation_query_id [xsd:int]

output_lists [vrtypens:ArrayOfSegmentationQueryOutputList]

notification_email_address [xsd:string]

Output [xsd:boolean]

createCompany

The createCompany() method creates a new VerticalResponse account to which Users can be added. In order for an account to be both active and valid, one and only one user must be assigned to the created company. The best way to accomplish this is by immediately following the createCompany() call with a createUser() call, providing the company_id you received from the first method call to the User object in the second.

Input [vrtypens:createCompanyArgs]

session_id [xsd:string] (required)
Your API session id.

company [vrtypens:Company] (required)
The Company object containing the details for this company.

use_partner_credit_ledger [xsd:boolean]
Whether to associate the new company with the credit ledger used by the partner that's making this call.

Output [xsd:int]

The output is the id of the new company

Examples

Perl PHP Ruby

$vrapi->createCompany( {
    session_id => $sid,
    company    => {
        name => 'New Company, Inc',
        address_1 => '123 Anywhere ST',
        url => 'http://www.somecompany.com',
        support_email => 'email@address.com',
    },
} );

$vrapi->createCompany( array(
    'session_id' => $sid,
    'company'    => array(
        'name' => 'New Company, Inc',
        'address_1' => '123 Anywhere ST',
        'url' => 'http://www.somecompany.com',
        'support_email' => 'email@address.com',
    ),
) );

vr.createCompany({
    'session_id' => sid,
    'company'    => {
        'name' => 'New Company, Inc',
        'address_1' => '123 Anywhere ST',
        'url' => 'http://www.somecompany.com',
        'support_email' => 'email@address.com',
    },
})

createCreditCard

The createCreditCard() method adds a new credit card to a specific VerticalResponse user's account.

Input [vrtypens:createCreditCardArgs]

session_id [xsd:string] (required)
Your API session id.

credit_card [vrtypens:CreditCard] (required)

Output [xsd:int]

The output is the id of the new credit card object

Examples

Perl PHP Ruby

$vr->createCreditCard({
   session_id => $sid, 
   credit_card => {
     nickname  => "VR Bank",
     card_type =
 
   }
});

$vr->runSegmentationQuery(array(
   'session_id' => $sid,
   'segmentation_query_id' => $seg_id,
   'notification_email_address' = 'your@company.com'
));

vr.runSegmentationQuery({
   'session_id' => sid,
   'segmentation_query_id' => seg_id,
   'notification_email_address' = 'your@company.com'
})

createCustomListField

The createCustomListField() method creates a single custom list field in the VR mailing custom list fields. Optionally allows to set this custom list field size to "small", "medium" and "large"; assuming "medium" as default.

Input [vrtypens:createCustomListFieldArgs]

session_id [xsd:string] (required)
Your API session id.

field_name [xsd:string] (required)
The field name to create

width [xsd:string]
The field width to be created. Allowed widths "small", "medium", "large". Defaults to "medium"

Output [xsd:boolean]

The output is always true.

Examples

Perl PHP Ruby

$vrapi->createCustomListField( {
    session_id => $sid,
    field_name => $field_name
    },
} );

$vrapi->createCustomListField( array(
    'session_id' => $sid,
    'field_name' => $field_name
) );

vr.createCustomListField({
   'session_id'  => sid,
   'field_name' => field_name
})

createEmail

The createEmail() method creates the specified email.

Input [vrtypens:createEmailArgs]

session_id [xsd:string] (required)
Your API session id.

email [vrtypens:Email] (required)
An Email object representing the new email.

Output [xsd:int]

The output is the ID of the new email.

createEmailCampaign

The createEmailCampaign() method creates the specified email campaign.

Input [vrtypens:createEmailCampaignArgs]

session_id [xsd:string] (required)
Your API session id.

email_campaign [vrtypens:EmailCampaign] (required)
An EmailCampaign object representing the new campaign. You may provide the following fields at the time of creation:

name
type
template_id (for template campaigns)
from_label
send_friend
mail_date

Only name, type, and template_id (only for template campaigns) are required.
The "type" attribute can only be set to one of the following:

template
canvas
freeform
freeform_text

Campaign contents can also be provided here. See setEmailCampaignContent() for details regarding which content types are available for which email campaign types. For template campaigns, a list of template modules can be provided as well.

Output [xsd:int]

The output is the ID of the new campaign.

Examples

Java Perl PHP Ruby C#.NET

EmailCampaign campaign = new EmailCampaign();
campaign.setName( "API Lifecycle " + timestamp );
campaign.setType( "freeform" );
campaign.setSupport_email( System.getProperty( "com.verticalresponse.vrapi_login_email_address" ) );
campaign.setFrom_label( "VR API" );
       	
// required campaign contents
java.util.List contents = new ArrayList();
contents.add( new EmailCampaignContent( "subject", "Campaign created with VR API" ) );
contents.add( new EmailCampaignContent( "freeform_text", "Hello, {FIRST_NAME} {LAST_NAME}. " +
                                        "This campaign was created via the VerticalResponse API http://www.verticalresponse.com/labs/." ) );
contents.add( new EmailCampaignContent( "freeform_html", "Hello, {FIRST_NAME} {LAST_NAME}. " +
                                        "This campaign was created via the

$vrapi->createEmailCampaign( {
    session_id => $sid,
    email_campaign => {
        name => "campaign_" . time(),
        type => 'freeform',
        from_label => 'XYY_newsletter',
        support_email => 'email@address.com',
        send_friend => 'true',
        redirect_url => 'http://www.verticalresponse.com/labs',
        contents => [
            {
                type => 'freeform_html',
                copy => '<h1>Hello World</h1>Pretty original, huh?',
            },
            {
                type => 'freeform_text',
                copy => 'Hola World!',
            },
            {
                type => 'subject',
                copy => 'My original subject line',
            },
            {
                type => 'unsub_message',
                copy => 'You requested these emails, if you would like to be removed from the list?  ',
            },
        ],
    },
} );

$vrapi->createEmailCampaign( array(
    'session_id' => $sid,
    'email_campaign' => array(
        'name' => "campaign_" . time(),
        'type' => 'freeform',
        'from_label' => 'XYY_newsletter',
        'support_email' => 'email@address.com',
        'send_friend' => 'true',
        'redirect_url' => 'http://www.verticalresponse.com/labs',
        'contents' => array(
            array(
                'type' => 'freeform_html',
                'copy' => '<h1>Hello World</h1>Pretty original, huh?',
            ),
            array(
                'type' => 'freeform_text',
                'copy' => 'Hola World!',
            ),
            array(
                'type' => 'subject',
                'copy' => 'My original subject line',
            ),
            array(
                'type' => 'unsub_message',
                'copy' => 'You requested these emails, if you would like to be removed from the list?  ',
            ),
        ),
    ),
) );

vr.createEmailCampaign({
    'session_id' => sid,
    'email_campaign' => {
        'name' => "campaign" ,
        'type' => 'freeform',
        'from_label' => 'XYY_newsletter',
        'support_email' => 'email@address.com',
        'send_friend' => 'true',
        'redirect_url' => 'http://www.verticalresponse.com/labs',
        'contents' => [
            {
                'type' => 'freeform_html',
                'copy' => '<h1>Hello World</h1>Pretty original, huh?',
            },
            {
                'type' => 'freeform_text',
                'copy' => 'Hola World!',
            },
            {
                'type' => 'subject',
                'copy' => 'My original subject line',
            },
            {
                'type' => 'unsub_message',
                'copy' => 'You requested these emails, if you would like to be removed from the list?  ',
            },
        ],
    },
} );

EmailCampaignContent[] objCampaignContents = new EmailCampaignContent[4];

EmailCampaignContent html = new EmailCampaignContent();
html.type = "freeform_html";
html.copy = "<h1>Hello World</h1>Pretty original, huh?";
objCampaignContents[0] = html;

EmailCampaignContent text = new EmailCampaignContent();
text.type = "freeform_text";
text.copy = "Hello, World!";
objCampaignContents[1] = text;

EmailCampaignContent subject = new EmailCampaignContent();
subject.type = "subject";
subject.copy = "My original subject line";
objCampaignContents[2] = subject;

EmailCampaignContent unsub_message = new EmailCampaignContent();
unsub_message.type = "unsub_message";
unsub_message.copy = "If you want to unsubscribe, click ";
objCampaignContents[3] = unsub_message;

createEmailCampaignArgs objeCampaignArgs = new createEmailCampaignArgs();
EmailCampaign objeCampaign = new EmailCampaign();
objeCampaign.name = "Campaign Test";
objeCampaign.type = "freeform";
objeCampaign.from_label = "XYZ_Newsletter";
objeCampaign.mail_date = Convert.ToDateTime (DateTime.Now.ToString("s")); //Date should be in ISO 8601 format
objeCampaign.send_friend = true;
objeCampaign.redirect_url = "http://www.verticalresponse.com/labs";
objeCampaign.contents = objCampaignContent;
                   
objeCampaignArgs.session_id = _sSessionId;
objeCampaignArgs.email_campaign = objeCampaign;
                    
int iCampaignID = objVR.createEmailCampaign(objeCampaignArgs);

createFile

The createFile() method adds a file to your Library. If the new file will overwrite an existing file, the "force" argument must be provided in order to prevent a fault from being thrown.
The "file" argument must be a FileSpec with a "filename" specified and either its "contents" or "location" specified. If the "contents" are specified, they should be Base64-encoded. Alternately the URL of the file to upload can be given in the "location" part of the FileSpec.

Input [vrtypens:createFileArgs]

session_id [xsd:string] (required)
Your API session id.

file [vrtypens:FileSpec] (required)
A FileSpec describing the file to create.

force [xsd:boolean]
Whether to prevent a fault from being thrown when the new file would overwrite an existing file

Output [xsd:boolean]

Examples

Perl PHP

$vrapi->createFile( {
    session_id => $sid,
    file       => {
        media_library_directory => '/',
        filename                => 'vr_logo.gif',
        location                => 'https://img.verticalresponse.com/images/cobrand/vr/logo.gif',
    },
} );

$vrapi->createFile( array(
    'session_id' => $sid,
    'file'       => array(
        'media_library_directory' => '/',
        'filename'                => 'vr_logo.gif',
        'location'                => 'https://img.verticalresponse.com/images/cobrand/vr/logo.gif',
    ),
) );

createList

The createList() method creates a new email or mailing list in the VR system, but does not append any members to that list.

Input [vrtypens:createListArgs]

session_id [xsd:string] (required)
Your API session id.

name [xsd:string] (required)
The name of the new list.

type [xsd:string] (required)
The type of list to create. Valid values for this are:

email
postcard

custom_field_names [vrtypens:ArrayOfString]
A list of names for any non-standards fields that should be provided for this list.

custom_field_widths [vrtypens:ArrayOfString] (required)
An array of widths for the custom fields. This array should match 1 on 1 with the fields array. Allowed widths: "small", "medium", "large". Defaults to "medium"

Output [xsd:int]

The output is the ID of the new list.

Examples

Java Perl PHP Ruby C#.NET

String[] fieldNames = new String[] { "customer_id", "email_address", "first_name", "last_name", "product" };
String name = "1st Mailing List";
String type = "email";

CreateListArgs args = new CreateListArgs();
args.setName(name);
args.setSession_id(sessionId);
args.setType(type);
args.setCustom_field_names(fieldNames);
int stuff = vrapi.createList(args);

$vrapi->createList( {
    session_id => $sid,
    name => 'list_' . time(),
    type => 'email',
} );

$vrapi->createList( array (
    'session_id' => $sid,
    'name' => 'list_' . time(),
    'type' => 'email',
) );

vr.createList({
   'session_id' => sid,
   'name'       => 'list',
   'type'       => 'email'
})

createListArgs objcLArgs = new createListArgs();

objcLArgs.session_id = _sSessionId;
objcLArgs.name = "list";
objcLArgs.type = "email";

int iListID = vr.createList(objcLArgs);

createOptinForm

Input [vrtypens:createOptinFormArgs]

session_id [xsd:string] (required)
Your API session id.

optin_form [vrtypens:OptinForm]

Output [xsd:int]

The output is the ID of the new form.

Examples

Perl PHP Ruby

$vrapi->createOptinForm( {
    session_id => $sid,
    optin_form => {
        name => "Main_subscrition",
        redirect_url = >"http://www.verticalresponse.com/thankyou.html",
        confirmation_text => "Thank you for signing up to our newsletter",
        from_label => "VR_Newsletter",
        confirmation_html => "Thank you for signing up. You will receive our newsletter shortly",
        confirmation_text => "Thank you for signing up. You will receive our newsletter shortly",
        confirmation_from_email => "VR_Newsletter",
        border_color => "#FFFFF",
        field_text_color => "#000000",
        confirmation_redirect_url => "http://www.verticalresponse.com/thankyou.html",
        question_collection => [
            {
                name => 'first_name',
                type => 'TEXT',
                position => 1, 
                required => 0,
            },
            {
                name => 'last_name',
                type => 'TEXT',
                position => 2, 
                required => 0,
            },
            {
                name => 'address_1',
                type => 'TEXT',
                position => 3, 
                required => 0,
            },
        ]
}
}
);

$vrapi->createOptinForm( array(
    'session_id' => $sid,
    'optin_form' => array(
        'name' => "Main_subscrition",
        'redirect_url' => "http://www.verticalresponse.com/thankyou.html",
        'confirmation_text' => "Thank you for signing up to our newsletter",
        'from_label' => "VR_Newsletter",
        'confirmation_html' => "Thank you for signing up. You will receive our newsletter shortly",
        'confirmation_text' => "Thank you for signing up. You will receive our newsletter shortly",
        'confirmation_from_email' => "VR_Newsletter",
        'border_color' => "#FFFFF",
        'field_text_color' => "#000000",
        'confirmation_redirect_url' => "http://www.verticalresponse.com/thankyou.html",
        'question_collection' => array(
            array(
                'name' => 'First_Name',
                'type' => 'textbox',
                'position => 1,
                'required' => 0,
            ),
            array(
                'name' => 'Last_Name',
                'type' => 'textbox',
                'position' => 2,
                'required' => 0,
            ),
            array(
                'name' => 'Address',
                'type' => 'textbox',
                'position' => 3,
                'required' => 0,
            ),
        ),
    ),
) );

vr.createOptinForm({
    'session_id' => sid,
    'optin_form' => {
        'name' => "Main_subscrition",
        'redirect_url' => "http://www.verticalresponse.com/thankyou.html",
        'confirmation_text' => "Thank you for signing up to our newsletter",
        'from_label' => "VR_Newsletter",
        'confirmation_html' => "Thank you for signing up. You will receive our newsletter shortly",
        'confirmation_text' => "Thank you for signing up. You will receive our newsletter shortly",
        'confirmation_from_email' => "VR_Newsletter",
        'border_color' => "#FFFFF",
        'field_text_color' => "#000000",
        'confirmation_redirect_url' => "http://www.verticalresponse.com/thankyou.html",
        'question_collection' => [
            {
                'name' => 'First_Name',
                'type' => 'textbox',
                'position => 1,
                'required' => 0,
            },
            {
                'name' => 'Last_Name',
                'type' => 'textbox',
                'position' => 2,
                'required' => 0,
            },
            {
                'name' => 'Address',
                'type' => 'textbox',
                'position' => 3,
                'required' => 0,
            },
        ],
    },
})

createSegmentationQuery

The createSegmentationQuery() method creates a new database segmentation query.

Input [vrtypens:createSegmentationQueryArgs]

session_id [xsd:string] (required)
Your API session id.

segmentation_query [vrtypens:SegmentationQuery]

Output [xsd:int]

Examples

Perl PHP Ruby

$vr->createSegmentationQuery({
    session_id => $sid.
    segmentation_query => {
       name => 'All VR addresses',
       operation_type => 'union',
       description   => 'Get all VR email address for convention',
       inputs => {
           input_type   => 'list',
           ids         => { 32, 25},
           constraints => {
               constrained_entity => "list_member",
               constrained_field  => "email_address",
               constraint_operator=> "LIKE",
               constraint_values  => {"verticalresponse.com"},
               match_if_field_missing => 0
            }
        }
     }

});

$vr->createSegmentationQuery(array(
    'session_id' => $sid.
    'segmentation_query' => array(
       'name' => 'All VR addresses',
       'operation_type' => 'union',
       'description'   => 'Get all VR email address for convention',
       'inputs' => array(
           'input_type'  => 'list',
           'ids'         => array( 32, 25),
           'constraints' => array(
               'constrained_entity' => "list_member",
               'constrained_field'  => "email_address",
               'constraint_operator'=> "LIKE",
               'constraint_values'  => array("verticalresponse.com"),
               'match_if_field_missing' => 0
            )
        )
     )
));

vr.createSegmentationQuery({
    'session_id' => $sid.
    'segmentation_query' => {
       'name' => 'All VR addresses',
       'operation_type' => 'union',
       'description'   => 'Get all VR email address for convention',
       'inputs' => {
           'input_type'  => 'list',
           'ids'         => { 32, 25},
           'constraints' => {
               'constrained_entity' => "list_member",
               'constrained_field'  => "email_address",
               'constraint_operator'=> "LIKE",
               'constraint_values'  => {"verticalresponse.com"},
               'match_if_field_missing' => 0
            }
        }
     }

});

createUser

The createUser() method creates a new VerticalResponse User login account. To be valid, this account must be associated with a Company that does not already have a user associated with it. The best way to accomplish this is by immediately preceding the createUser() call with a createCompany() call and providing the resulting id to the User.company_id field.

Input [vrtypens:createUserArgs]

session_id [xsd:string] (required)
Your API session id.

user [vrtypens:User]
The User object containing the information for this specific user.

partner_integration [xsd:string]
The name of your partner integration (if any).

partner_integration_user_id [xsd:string]
The id by which you want to refer to this user through your partner integration (if you have one). Use this if you want to be able to refer to the user with your own id instead of email address.

send_activation_email [xsd:boolean]

Output [xsd:int]

deleteCampaign

The deleteCampaign() method soft deletes a campaign. This operation can be undone with a call to undeleteCampaign().

Input [vrtypens:deleteCampaignArgs]

session_id [xsd:string] (required)
Your API session id.

campaign_id [xsd:int] (required)
The id of the campaign to delete.

Output [xsd:boolean]

The output is always true.

Examples

Perl PHP Ruby

$vrapi->deleteCampaign( {
    session_id => $sid,
    campaign_id => $cid,
} );

$vrapi->deleteCampaign( array(
    'session_id'  => $sid,
    'campaign_id' => $cid,
) );

vr.deleteCampaign({
    'session_id'  => sid,
    'campaign_id' => cid,
})

deleteCreditCard

The deleteCreditCard() method deletes an existing credit card that is stored in a VerticalResponse user's account.

Input [vrtypens:deleteCreditCardArgs]

session_id [xsd:string] (required)
Your API session id.

credit_card_id [xsd:int] (required)
The ID of the credit card object to delete.

Output [xsd:boolean]

The return value should always be true. In the case of a failure, a SOAP fault will be thrown.

Examples

Perl PHP Ruby

$vr->runSegmentationQuery({
   session_id => $sid,
   segmentation_query_id => $seg_id,
   notification_email_address = 'your@company.com'
});

$vr->runSegmentationQuery(array(
   'session_id' => $sid,
   'segmentation_query_id' => $seg_id,
   'notification_email_address' = 'your@company.com'
));

vr.runSegmentationQuery({
   'session_id' => sid,
   'segmentation_query_id' => seg_id,
   'notification_email_address' = 'your@company.com'
})

deleteCustomListField

The deleteCustomListField() method deletes a single custom list field from the VR mailing custom list fields. The custom list field's name must be provided so that the member can be identified.

Input [vrtypens:deleteCustomListFieldArgs]

session_id [xsd:string] (required)
Your API session id.

field_name [xsd:string] (required)
The field name to delete

Output [xsd:boolean]

The output is always true.

Examples

Perl PHP Ruby

$vrapi->deleteCustomListField( {
    session_id => $sid,
    field_name => $field_name
    },
} );

$vrapi->deleteCustomListField( array(
    'session_id' => $sid,
    'field_name' => $field_name
) );

vr.deleteCustomListField({
   'session_id'  => sid,
   'field_name' => field_name
})

deleteFile

The deleteFile() method removes a file from your Library. If the file to delete is a non-empty directory, then the "force" argument must be present to avoid a fault being thrown.

Input [vrtypens:deleteFileArgs]

session_id [xsd:string] (required)
Your API session id.

file [xsd:string] (required)
Library path to file to delete (e.g., "/logos/fall.jpg")

move_to_trash [xsd:boolean]
Whether to just move the file to /Trash instead of deleting it outright

force [xsd:boolean]
Whether to prevent a fault from being thrown if the file to delete is a non-empty directory

Output [xsd:boolean]

Examples

Perl PHP

$vrapi->deleteFile( {
    session_id => $sid,
    files      => '/foo/bar',
    force      => 1,
} );

$vrapi->deleteFile( array(
    'session_id' => $sid,
    'files'      => '/foo/bar',
    'force'      => 1,
) );

deleteList

The deleteList() method deletes a single VR mailing list.

Input [vrtypens:deleteListArgs]

session_id [xsd:string] (required)
Your API session id.

list_id [xsd:int] (required)
The id of the list to delete.

Output [xsd:boolean]

The output is always true.

Examples

Perl PHP Ruby C#.NET

$vrapi->deleteList( {
    session_id => $sid,
    list_id => $lid, 
} );

$vrapi->deleteList( array(
    'session_id' => $sid,
    'list_id'    => $lid, 
) );

vr.deleteList({
  'session_id' => sid,
  'list_id'    => lid
})

deleteListArgs objDeleteList = new deleteListArgs();
objDeleteList.session_id = _sSessionId;
objDeleteList.list_id = iListId;

vr.deleteList(objDeleteList);

deleteListMember

The deleteListMember() method deletes a single member from a VR mailing list. The list member's hash must be provided inside its member_data so that the member can be identified.

Input [vrtypens:deleteListMemberArgs]

session_id [xsd:string] (required)
Your API session id.

list_member [vrtypens:ListMember] (required)
A ListMember object representing the member to delete. It must have its "list_id" attribute set. For email lists, the ListMember object must have a "hash" NVPair in its "member_data" dictionary. For postcard lists, the ListMember object must have an "address_hash" NVPair in its "member_data" dictionary.

delete_from_master [xsd:boolean] (required)
Set this flag to true to indicate if you want to remove member from your master list also.

Output [xsd:boolean]

The output is always true.

Examples

Perl PHP Ruby C#.NET

$vrapi->deleteListMember( {
    session_id => $sid,
    list_member => {
        list_id => $lid,
        member_data => [
            {
                name => 'hash',
                value=> '99e3cf416f',
                },
        ],
    },
} );

$vrapi->deleteListMember( array(
    'session_id' => $sid,
    'list_member' => array(
        'list_id' => $lid,
        'member_data' => array(
            array(
                name => 'hash',
                value => '99e3cf416f',
            ),
        ),
    ),
) );

vr.deleteListMember({
   'session_id'  => sid,
   'list_member' => {
        'list_id'     => lid,
        'member_data' => 
             [{
              'name'  => 'hash',
              'value' => '99e3cf416f'               
             }]
         }
})

NVPair member_data = new NVPair();
member_data.name = "hash";
member_data.value= "99e3cf416f";

ListMember list_member = new ListMember();
list_member.list_id = iListId;
list_member.member_data = member_data;

deleteListMemberArgs objDLMember = new deleteListMemberArgs();
objDLMember.session_id = _sSessionId;
objDLMember.list_member = list_member;

objVR.deleteListMember(objDLMember);

deleteSegmentationQuery

The deleteSegmentationQuery() method deletes an existing database segmentation query.

Input [vrtypens:deleteSegmentationQueryArgs]

session_id [xsd:string] (required)
Your API session id.

segmentation_query_id [xsd:int]

Output [xsd:boolean]

Examples

Perl PHP Ruby

$vr->deleteSegmentationQuery({
  session_id => $sid,
  segmentation_query_id => $seg_id
});

$vr->deleteSegmentationQuery( array(
  'session_id' => $sid,
  'segmentation_query_id' => $seg_id
));

vr.deleteSegmentationQuery({
  session_id => sid,
  segmentation_query_id = seg_id
})

deleteTemplateCampaignModule

The deleteTemplateCampaignModule() method removes a module (specified by position) from a template campaign's list of modules. Any module whose position is higher than the given module will be shifted down in the list.

Input [vrtypens:deleteTemplateCampaignModuleArgs]

session_id [xsd:string] (required)
Your API session id.

campaign_id [xsd:int] (required)
The id of the email campaign whose template module is being removed.

position [xsd:int] (required)
The position of the template module being removed.

Output [xsd:boolean]

The output is always true.

Examples

Perl PHP

$vrapi->deleteTemplateCampaignModule ( {
    session_id => $sid,
    campaign_id => $cid,
    position => 1,
} );


$vrapi->deleteTemplateCampaignModule ( array(
    'session_id' => $sid,
    'campaign_id' => $cid,
    'position' => 1,
) );

downloadCampaignRecipientResults

The downloadCampaignRecipientResults() method creates a downloadable file containing the results of each recipient a given campaign. This file can be restricted to a subset of the lists that were mailed in the campaign and/or to a subset of the recipient responses (SALE, BOUNCE, UNSUBSCRIBE, CLICK, OPEN, NONE) of interest. In addition, the user may specify which fields will be included in the downloaded file. The response indicates the location of the generated file.

Input [vrtypens:downloadCampaignRecipientResultsArgs]

session_id [xsd:string] (required)
Your API session id.

campaign_id [xsd:int] (required)
The id of the campaign whose recipient results are being fetched.

delimiter [xsd:string] (required)
The type of result file to create: either "csv" or "tab".

remove_duplicates [xsd:boolean]
Whether to report just one event per recipient or all events per recipient (default is false).

fields_to_include [vrtypens:ArrayOfString] (required)
An array of the names of list fields to include as columns in the result.

restrict_responses [vrtypens:ArrayOfString]
An array of the only response types that should be reported on. Valid items for this array are:

OPEN
CLICK
SALE
BOUNCE
UNSUBSCRIBE
NONE

restrict_lists [vrtypens:ArrayOfInteger]
An array of ids of the lists whose recipients the result should be restricted to.

start_date [xsd:string]
If specified, no events before this date will be included in the result. This date/time should be specified in ISO 8601 format.

end_date [xsd:string]
If specified, no events after this date will be included in the result. This date/time should be specified in ISO 8601 format.

Output [vrtypens:downloadCampaignRecipientResultsResult]

Examples

Perl PHP Ruby C#.NET

$vrapi->downloadCampaignRecipientResults( {
    session_id => $sid,
    campaign_id => $cid,
    delimiter => 'tab',
    remove_duplicates => 1,
    fields_to_include => [
        'email_address',
        'first_name',
        'last_name',
        'zip',
    ],
} );

$vrapi->downloadCampaignRecipientResults( array(
    'session_id' => $sid,
    'campaign_id' => $cid,
    'delimiter' => 'tab',
    'remove_duplicates' => 1,
    'fields_to_include' => array(
        "email_address",
        "first_name",
        "last_name",
        "zip",
    ),
) );

vr.downloadCampaignRecipientResults({
    'session_id'  => sid,
    'campaign_id' => cid,
    'delimiter'   => 'tab',
    'remove_duplicates' => 1,
    'fields_to_include' => [
        'email_address',
        'first_name',
        'last_name',
        'zip',
    ]
})

downloadCampaignRecipientResultsArgs objDownloadCampaignRecipients = new downloadCampaignRecipientResultsArgs();
objDownloadCampaignRecipients.session_id = _sSessionId;
objDownloadCampaignRecipients.fields_to_include = new string[] {"email_address", "first_name", "last_name", "zip"};
objDownloadCampaignRecipients.campaign_id = iCampaignId;
objDownloadCampaignRecipients.delimiter = "tab";
objDownloadCampaignRecipients.remove_duplicates = false;
objDownloadCampaignRecipients.notification_email_address = "user@company.com";

objVR.downloadCampaignRecipientResults(objDownloadCampaignRecipients);

downloadCampaignRecipientResultsBackground

The asynchronous version of downloadCampaignRecipientResults(). This method is invoked and the results are emailed to the caller.

Input [vrtypens:downloadCampaignRecipientResultsArgs]

session_id [xsd:string] (required)
Your API session id.

campaign_id [xsd:int] (required)
The id of the campaign whose recipient results are being fetched.

delimiter [xsd:string] (required)
The type of result file to create: either "csv" or "tab".

remove_duplicates [xsd:boolean]
Whether to report just one event per recipient or all events per recipient (default is false).

fields_to_include [vrtypens:ArrayOfString] (required)
An array of the names of list fields to include as columns in the result.

restrict_responses [vrtypens:ArrayOfString]
An array of the only response types that should be reported on. Valid items for this array are:

OPEN
CLICK
SALE
BOUNCE
UNSUBSCRIBE
NONE

restrict_lists [vrtypens:ArrayOfInteger]
An array of ids of the lists whose recipients the result should be restricted to.

start_date [xsd:string]
If specified, no events before this date will be included in the result. This date/time should be specified in ISO 8601 format.

end_date [xsd:string]
If specified, no events after this date will be included in the result. This date/time should be specified in ISO 8601 format.

Output [xsd:int]

The output is the ID of the background task.

Examples

Perl PHP Ruby C#.NET

$vrapi->downloadCampaignRecipientResultsBackground( {
    session_id => $sid,
    campaign_id => $cid,
    delimiter => 'tab',
    remove_duplicates => 1,
    fields_to_include => [
        'email_address',
        'first_name',
        'last_name',
        'zip',
    ],
    notification_email_address => 'notification@yourcompany.com',
} );

$vrapi->downloadCampaignRecipientResultsBackground( array( 
    'session_id' => $sid,
    'campaign_id' => $cid,
    'delimiter' => 'tab',
    'remove_duplicates' => 1,
    'fields_to_include' => array(
        "email_address",
        "first_name",
        "last_name",
        "zip",
    ),
    'notification_email_address' => 'notification@yourcompany.com',
) );

vr.downloadCampaignRecipientResultsBackground({
    'session_id'  => sid,
    'campaign_id' => cid,
    'delimiter'   => 'tab',
    'remove_duplicates' => 1,
    'fields_to_include' => [
        'email_address',
        'first_name',
        'last_name',
        'zip',
    ],
    'notification_email_address' => 'notification@yourcompany.com',
})

downloadCampaignRecipientResultsArgs objDownloadCampaignRecipients = new downloadCampaignRecipientResultsArgs();
objDownloadCampaignRecipients.session_id = _sSessionId;
objDownloadCampaignRecipients.fields_to_include = new string[] {"email_address", "first_name", "last_name", "zip"};
objDownloadCampaignRecipients.campaign_id = iCampaignId;
objDownloadCampaignRecipients.delimiter = "tab";
objDownloadCampaignRecipients.remove_duplicates = true;
objDownloadCampaignRecipients.notification_email_address = "user@company.com";

objVR.downloadCampaignRecipientResultsBackground(objDownloadCampaignRecipients);

downloadCompanyUnsubscribesAndBounces

The downloadCompanyUnsubscribesAndBounces() method creates a file containing all the unsubscribe and bounce records available for the company calling it. This file is returned as a FileSpec in which the location field indicates a URL pointing to the generated file. To return only unsubscribe events that are not related to any campaign, set the "exclude_campaign_unsubs" argument to true. If your unsubscribes and bounces are linked to other companies within your organization, set the "include_org_linked_unsubs" argument to true to include unsubscribes and bounces from those other companies as well. The downloaded file will contain the email address, the event (UNSUBSCRIBE or BOUNCE), and the event date. If the "exclude_campaign_unsubs" argument is not used, the file will also contain a campaign id for those records that are associated with any campaign.

Input [vrtypens:downloadCompanyUnsubscribesAndBouncesArgs]

session_id [xsd:string] (required)
Your API session id.

delimiter [xsd:string] (required)
The type of result file to create: either "csv" or "tab".

include_org_linked_unsubs [xsd:boolean]
Whether to include unsubscribes from other companies who share unsubscribes with the caller's company through an organization (default is false).

exclude_campaign_unsubs [xsd:boolean]
Whether to exclude unsubscribes that exist as the result of a recipient clicking the "unsubscribe" link in a campaign (default is false).

start_date [xsd:string]
If specified, no unsubscribes or bounces before this date will be included in the result. This date/time should be specified in ISO 8601 format.

end_date [xsd:string]
If specified, no unsubscribes or bounces after this date will be included in the result. This date/time should be specified in ISO 8601 format.

UTC_date [xsd:boolean]
If specified, the unsubscribe/bounce date won't be converted to the user's timezone (recommended for faster response).

Output [vrtypens:downloadCompanyUnsubscribesAndBouncesResult]

Examples

Perl PHP Ruby C#.NET

$vrapi->downloadCompanyUnsubscribesAndBounces( {
    session_id => $sid,
    delimiter => 'tab',
} );

$vrapi->downloadCompanyUnsubscribesAndBounces( array(
    'session_id' => $sid,
    'delimiter' => 'tab',
) );

vr.downloadCompanyUnsubscribesAndBounces({
    'session_id' => sid,
    'delimiter' => 'tab',
})

downloadCompanyUnsubscribesAndBouncesArgs objGetBouncesUnsubscribes = new downloadCompanyUnsubscribesAndBouncesArgs();
objGetBouncesUnsubscribes.session_id = _sSessionId;
objGetBouncesUnsubscribes.delimiter = strDelimiter;
objGetBouncesUnsubscribes.start_date = strStartDate;
objGetBouncesUnsubscribes.end_date = strEndDate;

objVR.downloadCompanyUnsubscribesAndBounces(objGetBounceUnsubscribes);

downloadList

The downloadList() method downloads a single member list, optionally restricting the download to members who have unsubscribed and/or bounced. To specify such restrictions, include "bounces" or "unsubs" (or both) in the restrict_to argument. The fields_to_include argument can be filled with the names of fields in the specified list. A delimiter or "csv" or "tab" must be provided. The resulting file will be available for download, and its location will be provided in the result.

Input [vrtypens:downloadListArgs]

session_id [xsd:string] (required)
Your API session id.

list_id [xsd:int] (required)
The id of the list to download.

delimiter [xsd:string] (required)
The type of result file to create: either "csv" or "tab".

fields_to_include [vrtypens:ArrayOfString]
An array of the names of list fields to include as columns in the result.

restrict_to [vrtypens:ArrayOfString]
An array of record types to restrict the result to (default is an empty array). Valid items for this array are:

bounces
unsubs

Output [vrtypens:downloadListResult]

Examples

Perl PHP Ruby C#.NET

$vrapi->downloadList ( {
    session_id => $sid,
    list_id => $lid,
    delimiter => 'csv',
    fields_to_include => [ email_address, first_name, last_name ],
} );

$vrapi->downloadList ( array(
    'session_id' => $sid,
    'list_id' => $lid,
    'delimiter' => 'csv',
    'fields_to_include' => array( 'email_address', 'first_name', 'last_name' ),
) );

vr.downloadList({
  'session_id' => sid,
  'list_id'    => lid,
  'delimiter'  => 'csv',
  'fields_to_include' => [ 'email_address', 'first_name', 'last_name']
})

downloadListArgs objDownloadList = new downloadListArgs();
objDownloadList.session_id = _sSessionId;
objDownloadList.list_id = iListId;
objDownloadList.fields_to_include = new string[] {"email_address", "first_name"};
objDownloadList.delimiter = "csv";

objVR.downloadList(objDownloadList);

downloadListBackground

The asynchronous version of downloadList(). The method is invoked and the results are emailed to the caller.

Input [vrtypens:downloadListArgs]

session_id [xsd:string] (required)
Your API session id.

list_id [xsd:int] (required)
The id of the list to download.

delimiter [xsd:string] (required)
The type of result file to create: either "csv" or "tab".

fields_to_include [vrtypens:ArrayOfString]
An array of the names of list fields to include as columns in the result.

restrict_to [vrtypens:ArrayOfString]
An array of record types to restrict the result to (default is an empty array). Valid items for this array are:

bounces
unsubs

Output [xsd:int]

The output is the ID of the background task.

Examples

Perl PHP Ruby

$vrapi->downloadListBackground( {
    session_id => $sid,
    list_id => $lid,
    delimiter => 'csv',
    fields_to_include => [ email_address, first_name, last_name, _ignore_ ],
    notification_email_address => 'notification@yourcompany.com',
} );

$vrapi->downloadListBackground( array(
    'session_id'        => $sid,
    'list_id'           => $lid,
    'delimiter'         => 'csv',
    'fields_to_include' => array( 'email_address', 'first_name', 'last_name', '_ignore_' ),
    'notification_email_address' => 'notification@yourcompany.com',
) );

vr.downloadListBackground({
  'session_id' => sid,
  'list_id'    => lid,
  'delimiter'  => 'csv'
  'fields_to_include' => array('email_address', 'first_name', 'last_name', '_ignore')
})

editCompany

The editCompany() method updates the specified Company object.

Input [vrtypens:editCompanyArgs]

session_id [xsd:string] (required)
Your API session id.

company [vrtypens:Company] (required)
An object specifying the company's new data. The id of the company must be provided. Company fields that cannot be modified via this method are:

status
creation_date
hash

Output [xsd:boolean]

The output is always true.

Examples

Perl PHP Ruby

$vrapi->editCompany( {
    session_id => $sid,
    company => {
        name => 'VerticalResponse',
        address_1 => '501 2nd St, Suite 700',
        city => 'San Francisco',
        state => 'CA',
        postalcode => '94107',
        country => 'USA',
        url => 'http://www.verticalresponse.com',
        support_email => 'api-support@verticalresponse.com',  
    },
} );

$vrapi->editCompany( array(                      
    'session_id' => $sid,
    'company' => array(
        'name'          => 'VerticalResponse',
        'address_1'     => '501 2nd St, Suite 700',
        'city'          => 'San Francisco',
        'state'         => 'CA',
        'postalcode'    => '94107',
        'country'       => 'USA',
        'url'           => 'http://www.verticalresponse.com',
        'support_email' => 'api-support@verticalresponse.com',  
    ),
) );

vr.editCompany({                      
    'session_id' => sid,
    'company' => {
        'name'          => 'VerticalResponse',
        'address_1'     => '501 2nd St, Suite 700',
        'city'          => 'San Francisco',
        'state'         => 'CA',
        'postalcode'    => '94107',
        'country'       => 'USA',
        'url'           => 'http://www.verticalresponse.com',
        'support_email' => 'api-support@verticalresponse.com',  
    },
})

editCreditCard

The editCreditCard() method modifies an existing credit card that is stored in a VerticalResponse user's account.

Input [vrtypens:editCreditCardArgs]

session_id [xsd:string] (required)
Your API session id.

credit_card [vrtypens:CreditCard] (required)
The credit card object to edit.

Output [xsd:boolean]

The return value should always be true. In the case of a failure, a SOAP fault will be thrown.

Examples

Perl PHP Ruby

$vr->runSegmentationQuery({
   session_id => $sid,
   segmentation_query_id => $seg_id,
   notification_email_address = 'your@company.com'
});

$vr->runSegmentationQuery(array(
   'session_id' => $sid,
   'segmentation_query_id' => $seg_id,
   'notification_email_address' = 'your@company.com'
));

vr.runSegmentationQuery({
   'session_id' => sid,
   'segmentation_query_id' => seg_id,
   'notification_email_address' = 'your@company.com'
})

editCustomListField

The editCustomListField() method updates a single custom list field from the VR mailing custom list fields. Optionally allows to set this custom list field size to "small", "medium" and "large"; Optionally, truncate data is used along with the custom list field width when decreasing a custom list field size. One of the two arguments should be present in the method call.

Input [vrtypens:editCustomListFieldArgs]

session_id [xsd:string] (required)
Your API session id.

field_name [xsd:string] (required)
The field name to edit

new_width [xsd:string]
The field new width to be updated. Allowed widths "small", "medium", "large"

truncate_data [xsd:boolean]
Truncate data is used along with the custom list field width when decreasing a custom list field size. It is ignored when increasing the custom list field width.

Output [xsd:boolean]

The output is always true.

Examples

Perl PHP Ruby

$vrapi->editCustomListField( {
    session_id => $sid,
    field_name => $field_name
    new_width => 'large'
    },
} );


$vrapi->editCustomListField( {
    session_id => $sid,
    field_name => $field_name
    new_width => 'small'
    truncate_data => true
    },
} );

$vrapi->editCustomListField( array(
    'session_id' => $sid,
    'field_name' => $field_name
    'new_width' => 'large'
) );


$vrapi->editCustomListField( array(
    'session_id' => $sid,
    'field_name' => $field_name
    'new_width' => 'small'
    'truncate_data' => true
) );

vr.editCustomListField({
   'session_id'  => sid,
   'field_name' => field_name
   'new_width' => 'large'
})

vr.editCustomListField({
   'session_id'  => sid,
   'field_name' => field_name
   'new_width' => 'small'
   'truncate_data => true
})

editListAttribute

The editListAttribute() method edits one attribute an existing list. Currently supported attributes are "name" and "form_id".

Input [vrtypens:editListAttributeArgs]

session_id [xsd:string] (required)
Your API session id.

list_id [xsd:int] (required)
The id of the list whose attribute is being updated.

attribute_name [xsd:string] (required)
The name of the attribute that's being updated. This must be either "name" or "form_id".

attribute_value [xsd:string]
The new attribute value. If the "name" argument was set to "name", the lists new name will be changed to this. If the "name" argument was set to "form_id", and this list doesn't already have an opt-in form associated with it, then the list will be attached to the opt-in form specified by this value.

Output [xsd:boolean]

Examples

Perl PHP Ruby C#.NET

$vrapi->editListAttribute( {
    session_id => $sid,
    list_id => $lid,
    attribute_name => 'Q2 resp',
    attribute_value => 'Q2 Responders',
} );

$vrapi->editListAttribute( array(
    'session_id'      => $sid,
    'list_id'         => $lid,
    'attribute_name'  => 'Q2 resp',
    'attribute_value' => 'Q2 Responders',
) );

vr.editListAttribute({ 
  'session_id' => sid,
  'list_id'    => lid, 
  'attribute_name'  => 'Q2 resp',
  'attribute_value' => 'Q2 Responders' 
})

editListAttributeArgs objELAttributes = new editListAttributeArgs();
objELAttributes.session_id = _sSessionId;
objELAttributes.list_id = iListId;
objELAttributes.attribute_name = "Q2 resp";
objELAttributes.attribute_value = "Q2 Responders";

objVR.editListAttribute(objELAttributes);

editListMember

The editListMember() method edits a single list member. If the new list member values fail validation, an exception is thrown. The list member's hash must be provided inside its member_data so that the member can be identified. Note that the list member's hash will change if its email address changes.

Input [vrtypens:editListMemberArgs]

session_id [xsd:string] (required)
Your API session id.

list_member [vrtypens:ListMember] (required)
A ListMember object representing the member to edit. It must have its "list_id" attribute set. For email lists, the ListMember object must have a "hash" NVPair in its "member_data" dictionary. For postcard lists, the ListMember object must have an "address_hash" NVPair in its "member_data" dictionary.

validate_postal_address [xsd:boolean]
This parameter is deprecated and is not supported in future releases

Output [vrtypens:ListMember]

The output is always true.

Examples

Perl PHP Ruby C#.NET

$vrapi->editListMember( {
    session_id => $sid,
    list_member => {
        list_id => $lid,
        list_type => 'email',
        member_data => [
            {
                name => 'email_address',
                value => 'new_address@domain.com',
            },
            {
                name => 'hash',
                value => '99e3cf416f',
            },
            {
                name => 'state',
                value => 'NY'
            }
        ],
    },
} );

$vrapi->editListMember( array(
    'session_id'  => $sid,
    'list_member' => array(
        'list_id'     => $lid,
        'list_type'   => 'email',
        'member_data' => array(
            array(
                'name'  => 'email_address',
                'value' => 'new_email_address',
            ),
            array(
                'name'  => 'hash',
                'value' => '99e3cf416f',
            ),
            array(
                'name'  => 'state',
                'value' => 'NY',
            ),
        ),
    ),
) );

vr.editListMember({
  'session_id'  => sid,
  'list_member' => {
       'list_id'     => lid,
       'list_type'   => 'email',
       'member_data' => [
              { 
               'name' => 'email_address',
               'value'=> 'new_address@domain.com',
              },
              {
               'name'  => 'hash',
               'value' => '99e3cf416f'
              },
              {
               'name' => 'state',
               'value'=> 'ny'
               }
  }           
})

NVPair[] member_data = new NVPair[3];

NVPair email = new NVPair();
email.name = "email_address";
email.value= "new_address@company.com";
member_data[0] = email;

NVPair hash = new NVPair();
hash.name = "hash";
hash.value= "99e3cf416f";
member_data[1] = hash;

NVPair state = new NVPair();
state.name = "state";
state.value= "NY";
member_data[2] = state;

ListMember list_member = new ListMember();
list_member.list_type = "email";
list_member.list_id   = iListId;
list_member.member_data = member_data;

editListMemberArgs objeLMArgs = new editListMemberArgs();
objeLMArgs.session_id = _sSessionId;
objeLMArgs.list_member = list_member;
                    
objVR.editListMember(objeLMArgs);

editSegmentationQuery

The editSegmentationQuery() method edits an existing database segmentation query.

Input [vrtypens:editSegmentationQueryArgs]

session_id [xsd:string] (required)
Your API session id.

segmentation_query [vrtypens:SegmentationQuery]

Output [xsd:boolean]

Examples

Perl PHP Ruby

$vr->editSegmentationQuery({
    session_id => $sid.
    segmentation_query => {
       name => 'All VR addresses',
       operation_type => 'union',
       description   => 'Get all VR email address for convention',
       inputs => {
           input_type   => 'list',
           ids         => { 32, 25},
           constraints => {
               constrained_entity => "list_member",
               constrained_field  => "email_address",
               constraint_operator=> "LIKE",
               constraint_values  => {"verticalresponse.com"},
               match_if_field_missing => 0
            }
        }
     }

});

$vr->editSegmentationQuery(array(
    'session_id' => $sid.
    'segmentation_query' => array(
       'name' => 'All VR addresses',
       'operation_type' => 'union',
       'description'   => 'Get all VR email address for convention',
       'inputs' => array(
           'input_type'  => 'list',
           'ids'         => array( 32, 25),
           'constraints' => array(
               'constrained_entity' => "list_member",
               'constrained_field'  => "email_address",
               'constraint_operator'=> "LIKE",
               'constraint_values'  => array("verticalresponse.com"),
               'match_if_field_missing' => 0
            )
        )
     )
));

vr.editSegmentationQuery({
    'session_id' => $sid.
    'segmentation_query' => {
       'name' => 'All VR addresses',
       'operation_type' => 'union',
       'description'   => 'Get all VR email address for convention',
       'inputs' => {
           'input_type'  => 'list',
           'ids'         => { 32, 25},
           'constraints' => {
               'constrained_entity' => "list_member",
               'constrained_field'  => "email_address",
               'constraint_operator'=> "LIKE",
               'constraint_values'  => {"verticalresponse.com"},
               'match_if_field_missing' => 0
            }
        }
     }

});

editUser

The editUser() method updates the specified User object.

Input [vrtypens:editUserArgs]

session_id [xsd:string] (required)
Your API session id.

user [vrtypens:User] (required)
An object specifying the user's new data. The id of the user must be provided. User fields that cannot be modified via this method are:

cookie
creation_date
created_by
last_updated
last_activity_date

Output [xsd:boolean]

The output is always true.

Examples

Perl PHP Ruby

$vrapi->editUser( {
    session_id => $sid,
    user => {
        email_address => 'api-support@verticalresponse.com',
        url => 'http://www.verticalresponse.com/labs',
    },
} );

$vrapi->editUser( array(
    'session_id' => $sid,
    'user'       => array(
        'email_address => 'api-support@verticalresponse.com',
        'url' => 'http://www.verticalresponse.com/labs',
    ),
) );

vr.editUser({
    'session_id' => sid,
    'user'       => {
        'email_address => 'api-support@verticalresponse.com',
        'url' => 'http://www.verticalresponse.com/labs',
    }
})

emptyTrash

The emptyTrash() method removes all the files from the /Trash directory in the Library.

Input [vrtypens:emptyTrashArgs]

session_id [xsd:string] (required)
Your API session id.

Output [xsd:boolean]

Examples

Perl PHP

$vrapi->emptyTrash( { } );

$vrapi->deleteFile( array() );

enumerateCompanies

The enumerateCompanies() method returns an array of zero or more VerticalResponse accounts (companies) belonging to the current partner.

Input [vrtypens:enumerateCompaniesArgs]

session_id [xsd:string] (required)
Your API session id.

include_users [xsd:boolean]
Whether to include all the users per company in the result (default is false).

Output [vrtypens:ArrayOfCompany]

The output is an array of a partner's companies.

Examples

Perl PHP Ruby

$vrapi->enumerateCompanies( {
    session_id => $sid,
} );

$vrapi->enumerateCompanies( array (
     'session_id' => $sid,
) );

vr.enumerateCompanies({
     'session_id' => $sid,
})

enumerateCreditCards

The enumerateCreditCards() method lists all of the existing credit cards stored in a VerticalResponse user's account. If credit_card_id is specified, only the specified credit card is returned. Note that the actual credit card numbers are masked in the returned data; to perform credit card charges you must call makePurchase() or addSubscription().

Input [vrtypens:enumerateCreditCardsArgs]

session_id [xsd:string] (required)
Your API session id.

credit_card_id [xsd:int] (required)
If specified, the ID of the specific credit card to retrieve

Output [vrtypens:ArrayOfCreditCard]

The credit card(s) from the user's account, with the actual credit card number hidden for security purposes

Examples

Perl PHP Ruby

$vr->runSegmentationQuery({
   session_id => $sid,
   segmentation_query_id => $seg_id,
   notification_email_address = 'your@company.com'
});

$vr->runSegmentationQuery(array(
   'session_id' => $sid,
   'segmentation_query_id' => $seg_id,
   'notification_email_address' = 'your@company.com'
));

vr.runSegmentationQuery({
   'session_id' => sid,
   'segmentation_query_id' => seg_id,
   'notification_email_address' = 'your@company.com'
})

enumerateEmailCampaigns

The enumerateEmailCampaigns() method provides a way to list email campaigns. To restrict the listed campaigns to a set of particular statuses, provide those statuses in the statuses argument. Valid statuses are "active", "deleted", and "sent". A list of campaign ids can also be provided to restrict the listing to a particular set. By default campaign contents and template campaign modules are not included in the listing unless the include_content argument is set. The limit and offset arguments can be used to specify a "window" of matching campaigns. By default, deleted campaigns will not be included in the result. Set the include_deleted argument to true if you want to see deleted campaigns.

Input [vrtypens:enumerateEmailCampaignsArgs]

session_id [xsd:string] (required)
Your API session id.

campaign_ids [vrtypens:ArrayOfInteger]
A list of campaign ids to restrict output to.

statuses [vrtypens:ArrayOfString]
A list of campaign statuses to restrict output to. If provided, only campaigns with these statuses are returned.

include_content [xsd:boolean]
Whether to include contents array and template modules for each campaign in output. Warning: setting this to true when enumerating many campaigns can lead to very large responses.

include_deleted [xsd:boolean]
Whether to include deleted campaigns in the output. By default deleted campaigns are not returned.

include_lists [xsd:boolean]
Whether to include info about lists attached to each campaign. For each attached list, only the id, name, and size will be provided. Asking for list info is not allowed unless the output is limited to 100 campaigns or less (either specifying 100 campaign ids or a limit of 100).

order_by_fields [vrtypens:ArrayOfOrderByField]
An array of fields and directions that specify an ordering for the returned campaigns.

limit [xsd:int]
The maximum number of records to return.

offset [xsd:int]
Only records on or beyond this index are included in the result.

Output [vrtypens:ArrayOfEmailCampaign]

Examples

Perl PHP Ruby

$vrapi->enumerateEmailCampaigns( {
    session_id => $sid,
    limit => 2,
    order_by_fields => [
        {
            field_name => 'last_updated',
            direction => 'asc',
        },
        {
            field_name => 'mail_date',
            direction => 'asc',
        },
    ],
} );

$vrapi->enumerateEmailCampaigns( array(
    'session_id'      => $sid,
    'limit'           => 2,
    'order_by_fields' => array(
        array(
            'field_name' => 'last_updated',
            'direction'  => 'asc',
        ),
        array(
            'field_name' => 'mail_date',
            'direction' => 'asc',
        ),
    ),
) );

vr.enumerateEmailCampaigns({
    'session_id'      => sid,
    'limit'           => 2,
    'order_by_fields' => [
        {
            'field_name' => 'last_updated',
            'direction'  => 'asc',
        },
        {
            'field_name' => 'mail_date',
            'direction' => 'asc',
        },
    ],
})

enumerateEmailLayoutCategories

The enumerateEmailLayoutCategories() method enumerates all email layout categories.

Input [vrtypens:enumerateEmailLayoutCategoriesArgs]

session_id [xsd:string] (required)
Your API session id.

restrict_to_users_cobrand [xsd:string]
When present, the categories returned will be only those belonging to the callers cobrand. When not present, those layouts belonging to the users cobrand plus those with no cobrand restriction will be returned.

Output [vrtypens:ArrayOfEmailLayoutCategory]

Examples

Perl PHP

$vrapi->enumerateEmailLayoutCategories( {
    session_id => $sid,
} );

$vrapi->enumerateEmailCampaignCategories( array(
    'session_id'      => $sid,
) );

enumerateEmailLayouts

The enumerateEmailLayouts() method provides a way to list all layouts within a given layout category. Multiple layout categories can be specified.

Input [vrtypens:enumerateEmailLayoutsArgs]

session_id [xsd:string] (required)
Your API session id.

categories [vrtypens:ArrayOfInteger]
A set of category IDs as returned by enumerateEmailCategories to which the returned layouts should belong. Use an empty array or no value to indicate that layouts from all categories should be returned.

Output [vrtypens:ArrayOfEmailLayout]

Examples

Perl PHP

$vrapi->enumerateEmailLayouts( {
    session_id => $sid,
    categories => [ 1, 40, 260 ]
} );

$vrapi->enumerateEmailCampaigns( array(
    'session_id'      => $sid,
    'categories' => array( 1, 40, 260 )
) );

enumerateEmails

The enumerateEmails() method provides a way to list emails. To restrict the listed campaigns to a set of particular statuses, provide those statuses in the statuses argument. Valid statuses are "active", "deleted", and "sent". A list of campaign ids can also be provided to restrict the listing to a particular set. By default freeform_html and freeform_text are not included unless the include_content argument is set. The limit and offset arguments can be used to specify a "window" of matching campaigns. By default, deleted campaigns will not be included in the result. Set the include_deleted argument to true if you want to see deleted campaigns.

Input [vrtypens:enumerateEmailsArgs]

session_id [xsd:string] (required)
Your API session id.

campaign_ids [vrtypens:ArrayOfInteger]
A list of campaign ids to restrict output to.

statuses [vrtypens:ArrayOfString]
A list of campaign statuses to restrict output to. If provided, only campaigns with these statuses are returned.

include_content [xsd:boolean]
Whether to include freeform_html and freeform_text for each email in output. Warning: setting this to true when enumerating many emails can lead to very large responses.

include_deleted [xsd:boolean]
Whether to include deleted emails in the output. By default deleted emails are not returned.

order_by_fields [vrtypens:ArrayOfOrderByField]
An array of fields and directions that specify an ordering for the returned campaigns.

limit [xsd:int]
The maximum number of records to return.

offset [xsd:int]
Only records on or beyond this index are included in the result.

Output [vrtypens:ArrayOfEmail]

Examples

Perl PHP Ruby

$vrapi->enumerateEmails( {
    session_id => $sid,
    limit => 2,
    order_by_fields => [
        {
            field_name => 'last_updated',
            direction => 'asc',
        },
        {
            field_name => 'mail_date',
            direction => 'asc',
        },
    ],
} );

$vrapi->enumerateEmails( array(
    'session_id'      => $sid,
    'limit'           => 2,
    'order_by_fields' => array(
        array(
            'field_name' => 'last_updated',
            'direction'  => 'asc',
        ),
        array(
            'field_name' => 'mail_date',
            'direction' => 'asc',
        ),
    ),
) );

vr.enumerateEmails({
    'session_id'      => sid,
    'limit'           => 2,
    'order_by_fields' => [
        {
            'field_name' => 'last_updated',
            'direction'  => 'asc',
        },
        {
            'field_name' => 'mail_date',
            'direction' => 'asc',
        },
    ],
})

enumerateFiles

The enumerateFiles() method provides a way to list files and directories in your Library.

Input [vrtypens:enumerateFilesArgs]

session_id [xsd:string] (required)
Your API session id.

base_directory [xsd:string]
Directory within your Library whose files are to be listed (defaults to root Library directory "/", known as "My Images" in the web application).

recurse_subdirectories [xsd:boolean]
Whether to recurse subdirectories in listing (defaults to false).

Output [vrtypens:ArrayOfFileSpec]

Examples

Perl PHP

$vrapi->enumerateFiles( {
    session_id             => $sid,
    base_directory         => '/logos',
    recurse_subdirectories => 1,
} );

$vrapi->enumerateFiles( array(
    'session_id'             => $sid,
    'base_directory'         => '/logos',
    'recurse_subdirectories' => 1,
) );

enumerateLists

The enumerateLists() method returns an array of zero or more VerticalResponse mailing lists that belong to the current user. Provide the list_id argument to retrieve just one list. Provide the type argument to limit the response to only lists of that type. The name argument can be used to search lists for one with a particular name. Provide a campaign_id argument to find the lists that have been associated with the given campaign for mailing. Provide a form_id argument to find the list that's associated with a given opt-in form. The limit and offset arguments can be used to specify a "window" of matching lists.

Input [vrtypens:enumerateListsArgs]

session_id [xsd:string] (required)
Your API session id.

list_id [xsd:int]
The id of a list to restrict output to.

type [xsd:string]
The type of lists to restrict output to (e.g., "email", "optin").

name [xsd:string]
The name of a list to restrict output to.

campaign_id [xsd:int]
When specified, only lists that are associated with this campaign are returned.

form_id [xsd:int]
When specified, only the list associated with this opt-in form is returned.

include_field_info [xsd:boolean]
Whether to include the names of the fields for each list. Warning: setting this to true when enumerating many lists can lead to very large responses.

include_deleted_lists [xsd:boolean]
Whether to include deleted lists in the output. By default deleted lists are not returned.

order_by [xsd:string]
The field to sort results by.

limit [xsd:int]
The maximum number of records to return.

offset [xsd:int]
Only records on or beyond this index are included in the result.

is_master [xsd:boolean]
When set to true, only the master list is returned. When set to false, all the user lists (except for the master list) are returned. When not specified, all lists that match other input parameters are returned, whether master or not.

order_direction [xsd:string]
Optional attribute to indicate the order_by direction. Possible values 'DESC' or 'ASC', default is 'ASC'.

Output [vrtypens:ArrayOfList]

Examples

Perl PHP Ruby C#.NET

$vrapi->enumerateLists( {
    session_id         => $sid, 
    type               => 'email',
    include_field_info => 1,
    order_by           => 'size',
    limit              => 2,
} );

$vrapi->enumerateLists( array(
    'session_id'         => $sid, 
    'type'               => 'email',
    'include_field_info' => 1,
    'order_by'           => 'size',
    'limit'              => 2,
) );

vr.enumerateLists({
  'session_id' => sid,
  'type'       => 'email',
  'order_by'   => 'size',
  'limit'      => 2,
  'include_field_info' => 1
})

enumerateListsArgs objELists = new enumerateListsArgs();
objELists.session_id = _sSessionId;
objELists.type = "email";
objELists.include_field_info = true;
objELists.include_field_infoSpecified = true;

Lists[] emailLists = vr.enumerateLists(objELists);

enumerateSegmentationQueries

The enumerateSegmentationQueries() method returns an array of zero or more database segmentation queries that belong to the current user. Provide the segmentation_query_id argument to retrieve just one segmentation query object. Use the include_query_detail argument (set to true) to retrieve the full detail of of the SegmentationQuery object.

Input [vrtypens:enumerateSegmentationQueriesArgs]

session_id [xsd:string] (required)
Your API session id.

segmentation_query_id [xsd:int]

include_query_detail [xsd:boolean]

Output [vrtypens:ArrayOfSegmentationQuery]

Examples

Perl PHP Ruby

$vr->enumerateSegmentationQuery({
   session_id => $sid,
   segmentation_query_id => $seg_id,
   include_query_detail  => 0
});

$vr->enumerateSegmentationQuery(array(
   'session_id' => $sid,
   'segmentation_query_id' => $seg_id,
   'include_query_detail'  => 0
));

vr.enumerateSegmentationQuery({
   'session_id' => sid,
   'segmentation_query_id' => seg_id,
   'include_query_detail'  => 0
})

enumerateSubscriptions

The enumerateSubscriptions() method retrieves the subscriptions (active, cancelled and expired) for the current user. If subscription_id is specified, only the specified subscription is retrieved.

Input [vrtypens:enumerateSubscriptionsArgs]

session_id [xsd:string] (required)
Your API session id.

subscription_id [xsd:int]

Output [vrtypens:ArrayOfSubscription]

eraseListMembers

The eraseListMembers() deletes all of the members from a list permanently, but leaves the list (now with zero members) intact.

Input [vrtypens:eraseListMembersArgs]

session_id [xsd:string] (required)
Your API session id.

list_id [xsd:int] (required)
The id of the list whose members are to be removed

Output [xsd:boolean]

The output is always true.

Examples

Perl PHP Ruby C#.NET

$vrapi->eraseListMembers( {
    session_id => $sid,
    list_id => $lid,
} );

$vrapi->eraseListMembers( array(
    'session_id' => $sid,
    'list_id'    => $lid,
) );

vr.eraseListMembers( {
    'session_id' => sid,
    'list_id'    => lid,
} );

eraseListMembersArgs objELMembers = new eraseListMembersArgs();
objELMembers.session_id = _sSessionId;
objELMembers.list_id = iListId;

objVR.eraseListMembers(objELMembers);

fetchAppendFileToListBackgroundResult

The fetchAppendFileToListBackgroundResult() method returns the results of appendFileToListBackground() method call that has since completed. If a fault occurred during the asynchronous execution of the appendFileToListBackground() method, that fault will be returned to the caller of fetchAppendFileToListBackgroundResult(). Otherwise, the return value of this method will be structured the same as the value returned by a successful call to the appendFileToList() method. If the method has not yet completed, a fault will be thrown. The status a appendFileToListBackground() call can be checked using the getBackgroundTaskStatus() method.

Input [vrtypens:fetchBackgroundResultArgs]

session_id [xsd:string] (required)
Your API session id.

background_task_id [xsd:int]

Output [vrtypens:appendFileToListResult]

Examples

Perl PHP Ruby

$vrapi->fetchAppendFileToListBackgroundResult( {
    session_id => $sid,
    background_task_id => $bg_id,
} );

$vrapi->fetchAppendFileToListBackgroundResult( array(
    'session_id' => $sid,
    'background_task_id' => $bg_id
) );

vr.fetchAppendFileToListBackgroundResult( {
    'session_id' => sid,
    'background_task_id' => bg_id,
} )

fetchCompileCampaignRecipientResultsBackgroundResult

The fetchCompileCampaignRecipientResultsBackgroundResult() method returns the results of compileCampaignRecipientResultsBackground() method call that has since completed. If a fault occurred during the asynchronous execution of the compileCampaignRecipientResultsBackground() method, that fault will be returned to the caller of fetchCompileCampaignRecipientResultsBackgroundResult(). Otherwise, the return value of this method will be structured the same as the value returned by a successful call to the compileCampaignRecipientResults() method. If the method has not yet completed, a fault will be thrown. The status a compileCampaignRecipientResultsBackground() call can be checked using the getBackgroundTaskStatus() method.

Input [vrtypens:fetchBackgroundResultArgs]

session_id [xsd:string] (required)
Your API session id.

background_task_id [xsd:int]

Output [vrtypens:compileCampaignRecipientResultsResult]

Examples

Perl PHP Ruby

$vr->fetchCompileCampaignRecipientResultsBackgroundResult({
    session_id => $sid,
    background_task_id => $btid,
});

$vr->fetchCompileCampaignRecipientResultsBackgroundResult( array(
    'session_id' => $sid,
    'background_task_id' => $btid,
) );

vr.fetchCompileCampaignRecipientResultsBackgroundResult({
    session_id => sid,
    background_task_id => btid,
});

fetchDownloadCampaignRecipientResultsBackgroundResult

The fetchDownloadCampaignRecipientResultsBackgroundResult() method returns the results of downloadCampaignRecipientResultsBackground() method call that has since completed. If a fault occurred during the asynchronous execution of the downloadCampaignRecipientResultsBackground() method, that fault will be returned to the caller of fetchDownloadCampaignRecipientResultsBackgroundResult(). Otherwise, the return value of this method will be structured the same as the value returned by a successful call to the downloadCampaignRecipientResults() method. If the method has not yet completed, a fault will be thrown. The status a downloadCampaignRecipientResultsBackground() call can be checked using the getBackgroundTaskStatus() method.

Input [vrtypens:fetchBackgroundResultArgs]

session_id [xsd:string] (required)
Your API session id.

background_task_id [xsd:int]

Output [vrtypens:downloadCampaignRecipientResultsResult]

Examples

Perl PHP Ruby C#.NET

$vrapi->fetchDownloadCampaignRecipientResultsBackgroundResult( {
    session_id => $sid,
    background_task_id => $btid,
} );

$vrapi->fetchDownloadCampaignRecipientResultsBackgroundResult( array(
    'session_id' => $sid,
    'background_task_id'  => $btid,
) );

vr.fetchDownloadCampaignRecipientResultsBackgroundResult({
    'session_id' => sid,
    'background_task_id'  => bg_id
})

fetchBackgroundResultArgs objFetchBGResults = new fetchBackgroundResultArgs();
objFetchBGResults.session_id = _sSessionId;
objFetchBGResults.background_task_id = iBackgroundTaskId;

objVR.fetchDownloadCampaignRecipientResultsBackgroundResult(objFetchBGResults);

fetchDownloadListBackgroundResult

The fetchDownloadListBackgroundResult() method returns the results of downloadListBackground() method call that has since completed. If a fault occurred during the asynchronous execution of the downloadListBackground() method, that fault will be returned to the caller of fetchDownloadListBackgroundResult(). Otherwise, the return value of this method will be structured the same as the value returned by a successful call to the downloadListBackgroundResult() method. If the method has not yet completed, a fault will be thrown. The status a downloadListBackground() call can be checked using the getBackgroundTaskStatus() method.

Input [vrtypens:fetchBackgroundResultArgs]

session_id [xsd:string] (required)
Your API session id.

background_task_id [xsd:int]

Output [vrtypens:downloadListResult]

Examples

Perl PHP Ruby C#.NET

$vrapi->fetchDownloadListBackgroundResult( {
    session_id => $sid,
    background_task_id => $bg_id,
} );

$vrapi->fetchDownloadListBackgroundResult( array(
    'session_id' => $sid,
    'background_task_id' => $bg_id,
) );

vr.fetchDownloadListBackgroundResult( {
    'session_id' => sid,
    'background_task_id' => bg_id,
} )

fetchBackgroundResultArgs objFBResult = new fetchBackgroundResultArgs();
objFBResult.session_id = _sSessionId;
objFBResult.background_task_id = iBackgroundTaskId;

objVR.fetchDownloadListBackgroundResult(objFBResult);

fetchRunSegmentationQueryBackgroundResult

The fetchRunSegmentationQueryBackgroundResult() method returns the results of runSegmentationQueryBackground() method call that has since completed. If a fault occurred during the asynchronous execution of the runSegmentationQueryBackground() method, that fault will be returned to the caller of fetchRunSegmentationQueryBackgroundResult(). Otherwise, the return value of this method will be structured the same as the value returned by a successful call to the runSegmentationQuery() method. If the method has not yet completed, a fault will be thrown. The status of a runSegmentationQueryBackground() call can be checked using the getBackgroundTaskStatus() method.

Input [vrtypens:fetchBackgroundResultArgs]

session_id [xsd:string] (required)
Your API session id.

background_task_id [xsd:int]

Output [xsd:int]

Examples

Perl PHP Ruby

$vr->fetchRunSegmentationQueryBackgroundResult({
   session_id => $sid,
   background_task_id => $bg_id
});

$vr->fetchRunSegmentationQueryBackgroundResult(array(
   'session_id' => $sid,
   'background_task_id' => $bg_id
));

vr.fetchRunSegmentationQueryBackgroundResult({
   'session_id' => sid,
   'background_task_id' => bg_id
});

getBackgroundTaskStatus

The getBackgroundTaskStatus() method returns status information about a background task that was started with one of the <MethodName>Background() methods. The information returned includes the current status of the task (running, completed, or failed); the starting timestamp of the task; the ending timestamp (if any) of the task, and the percent complete (in cases where this information is available). Once a task has a status of 'completed' (or 'failed') the corresponding fetch<MethodName>BackgroundResult() method can be called to retrieve the result (or fault) of the method call, respectively. The return value of the fetch<MethodName>BackgroundResult will be the datatype that is documented for the <MethodName> function.

Input [vrtypens:getBackgroundTaskStatusArgs]

session_id [xsd:string] (required)
Your API session id.

background_task_id [xsd:int]

Output [vrtypens:BackgroundTaskStatus]

Examples

Perl PHP Ruby C#.NET

$vrapi->getBackgroundTaskStatus( {
    session_id => $sid,
    background_task_id => $bg_id
} );

$vrapi->getBackgroundTaskStatus( array(
    'session_id' => $sid,
    'background_task_id'  => $bg_id
) );

vr.getBackgroundTaskStatus({
    'session_id' => sid,
    'background_task_id'  => bg_id,
})

getBackgroundTaskStatusArgs objGetBGStatus = new getBackgroundTaskStatusArgs();
objGetBGStatus.session_id = _sSessionId;
objGetBGStatus.background_task_id = iBackgroundTaskId;

BackgroundTaskStatus objTaskStatus = objVR.getBackgroundTaskStatus(objGetBGStatus);

getCampaignDomainCount

The getCampaignDomainCount() method retrieves the number of recipients for a specified email campaign, by domain (optionally limited to the top N results or to a specified set of domains)

Input [vrtypens:getCampaignDomainCountArgs]

session_id [xsd:string] (required)
Your API session id.

campaign_id [xsd:int] (required)
The campaign whose recipient domains are being counted.

max_domains [xsd:int]
An amount to limit the results by.

restrict_domains [vrtypens:ArrayOfString]
An array of domains to limit the result by.

Output [vrtypens:getCampaignDomainCountResult]

The output is an array of domains with the count of recipients for each one.

Examples

Perl PHP Ruby

$vrapi->getCampaignDomainCount( {
    session_id => $sid,
    campaign_id => $cid,
    max_domains => 10,
} );

$vrapi->getCampaignDomainCount( array(
    'session_id'  => $sid,
    'campaign_id' => $cid,
    'max_domains' => 10,
) );

vr.getCampaignDomainCount({
    'session_id'  => sid,
    'campaign_id' => cid,
    'max_domains' => 10,
})

getCompany

The getCompany() method returns the specified company. Please note that if User information is requested, this method will never provide any User's password.

Input [vrtypens:getCompanyArgs]

session_id [xsd:string] (required)
Your API session id.

company_id [xsd:int] (required)
The id of the company to retrieve.

include_users [xsd:boolean]
Whether to include the company's users in the result (default is false).

Output [vrtypens:Company]

The output is the specified company.

Examples

Perl PHP Ruby

$vrapi->getCompany( {
    session_id => $sid,
    company_id => $comp_id,
} );

$vrapi->getCompany( array(
    'session_id' => $sid,
    'company_id' => $comp_id,
) );

vr.getCompany({
    'session_id' => sid,
    'company_id' => comp_id,
})

getCompanySummary

The getCompanySummary() method reports various summary statistics such as list count and campaign count for a company.

Input [vrtypens:getCompanySummaryArgs]

session_id [xsd:string] (required)
Your API session id.

company_id [xsd:int]
The id of the company whose statistics are to be retrieved. Defaults to the id of the calling company.

categories [vrtypens:ArrayOfString] (required)
A list of categories of statistics requested. Available categories are:

lists
campaigns

Category names are case-sensitive.

Output [vrtypens:NVDictionary]

The output is an NVDictionary containing the company's statistics.

If "lists" is included in the categories argument, then the following statistics will be included in the result:

"total lists": number of lists that haven't been deleted
"email lists": number of email lists that haven't been deleted
"optin lists": number of opt-in lists that haven't been deleted
"postcard lists": number of postcard lists that haven't been deleted
"total deleted lists": total number of lists that have been deleted
"deleted email lists": number of email lists that have been deleted
"deleted optin lists": number of opt-in lists that have been deleted
"deleted postcard lists": number of postcard lists that have been deleted

If "campaigns" is included in the categories argument, then the following statistics will be included in the result:

"total email campaigns": total number of email campaigns that haven't been deleted
"launched email campaigns": number of email campaigns that have been launched and not deleted
"not launched email campaigns": number of email campaigns that have not yet been launched and have not been deleted
"total deleted email campaigns": total number of deleted email campaigns
"deleted launched email campaigns": number of campaigns that have been launched and have been deleted
"deleted not launched email campaigns": number of campaigns that have not yet been launched and have been deleted

Examples

Perl PHP Ruby

$vrapi->getCompanySummary( {
    session_id => $sid,
    categories => [ 'lists', 'campaigns' ],
} );

$vrapi->getCompanySummary( array(
    'session_id' => $sid,
    'categories' => array( 'lists', 'campaigns' ),
) );

vr.getCompanySummary({
    'session_id' => sid,
    'categories' => ['lists', 'campaigns'],
})

getEmailCampaignDeclineHistory

The getEmailCampaignDeclineHistory() method returns a list of instances when a launched campaign has been declined for mailing by VerticalResponse staff (e.g., an email campaign is declined because it lacks a postal address). The decline history is provided as a list of timestamps and decline reasons.

Input [vrtypens:getEmailCampaignDeclineHistoryArgs]

session_id [xsd:string] (required)
Your API session id.

campaign_id [xsd:int] (required)
The campaign whose decline history is being checked.

Output [vrtypens:ArrayOfEmailCampaignDecline]

An array representing all the times this campaign has been declined including the date and reason for each one.

Examples

Perl PHP Ruby

$vrapi->getEmailCampaignDeclineHistory( {
    session_id => $sid,
    campaign_id => $cid,
} );

$vrapi->getEmailCampaignDeclineHistory( array(
    'session_id'  => $sid,
    'campaign_id' => $cid,
) );

vr.getEmailCampaignDeclineHistory({
    'session_id'  => sid,
    'campaign_id' => cid,
})

getEmailCampaignResponseHistograms

The getEmailCampaignResponseHistorgrams() method provides campaign response stats such as opens, clicks, bounces, and unsubscribes in histogram form suitable for input into graphing tools.

Input [vrtypens:getEmailCampaignResponseHistogramsArgs]

session_id [xsd:string] (required)
Your API session id.

campaign_ids [vrtypens:ArrayOfInteger] (required)
The ids of the campaigns whose stats are to be retrieved.

response_types [vrtypens:ArrayOfString] (required)
An array of response types to include. Valid values are:

OPEN
CLICK
SALE
BOUNCE
UNSUBSCRIBE

bins [xsd:int]
The number of intervals that will be represented in the result (default is 2).

min_minutes_since_launch [xsd:int]
The number of minutes after launch where the reporting of events should begin (default is 0).

max_minutes_since_launch [xsd:int]
The number of minutes after launch where the reporting of events should end (default is 2).

Output [vrtypens:ArrayOfEmailCampaignResponseHistogram]

The output is a variety of response stats for the given campaign.

Examples

Perl PHP Ruby C#.NET

$vrapi->getEmailCampaignResponseHistogram( {
    session_id => $sid,
    campaign_ids => [ $cid ],
    bins => 12,
} );

$vrapi->getEmailCampaignResponseHistogram( array(
    'session_id' => $sid,
    'campaign_ids' => array( $cid ),
    'bins' => 12,
) );

vr.getEmailCampaignResponseHistogram({
    'session_id' => sid,
    'campaign_ids' => [cid],
    'bins' => 12,
})

getEmailCampaignResponseHistogramsArgs objGetHistogram = new getEmailCampaignResponseHistogramsArgs();
objGetHistogram.session_id = _sSessionId;
objGetHistogram.campaign_ids = new string[] { campaignId };
objGetHistogram.bins = 12;

objVR.getEmailCampaignResponseHistograms(objGetHistogram);

getEmailCampaignStats

The getEmailCampaignStats() method provides a variety of statistical information for a given campaign specified by id.

Input [vrtypens:getEmailCampaignStatsArgs]

session_id [xsd:string] (required)
Your API session id.

campaign_id [xsd:int] (required)
The id of the campaign whose stats are to be retrieved.

include_link_stats [xsd:boolean]
Whether to include click-through statistics in the result (default is false).

include_domain_stats [xsd:boolean]
Whether to include per-domain statistics in the result (default is false).

include_list_stats [xsd:boolean]
Whether to include per-list statistics in the result (default is false).

Output [vrtypens:EmailCampaignStats]

The output is a variety of stats for the given campaign.

Examples

Perl PHP Ruby C#.NET

$vrapi->getEmailCampaignStats( {
    session_id   => $sid,
    campaign_id  => $cid,
    include_link_stats => 1,
} );

$vrapi->getEmailCampaignStats( array(
    'session_id'         => $sid,
    'campaign_id'        => $cid,
    'include_link_stats' => 1,
) );

vr.getEmailCampaignStats({
    'session_id'         => sid,
    'campaign_id'        => cid,
    'include_link_stats' => 1,
})

getEmailCampaignStatsArgs objCampaignStats = new getEmailCampaignStatsArgs();
objCampaignStats.campaign_id = iCampaignID;
objCampaignStats.session_id = _sSessionId;
objCampaignStats.include_domain_stats = true;
objCampaignStats.include_link_stats = true;

EmailCampaignStats objCampaignStatsResults = objVR.getEmailCampaignStats(objCampaignStats);

getEmailCampaignsRecipients

The getEmailCampaignsRecipients() method builds a downloadable csv file containing recipient information for campaigns that have mailed out. Specify either a number of days back into the past to look for mailed campaigns or campaign ids themselves, and recipients for those campaigns end up in the csv file. If campaign ids are specified, then only the ids of campaigns that have actually been mailed out are considered. Each line of the csv file contains a campaign id and the email address of one of the recipients of that campaign.

Input [vrtypens:getEmailCampaignsRecipientsArgs]

session_id [xsd:string] (required)
Your API session id.

sent_in_last_days [xsd:int]
Campaigns sent in the last <sent_in_last_days> will be included in the result. Only integers between 1 and 50 (inclusive) are allowed. If this is specified, then campaign_ids cannot also be specified.

campaign_ids [vrtypens:ArrayOfInteger]
The specified campaigns will be included in the result. Specifying more than 100 campaign ids is not allowed. If this is specified, then sent_in_last_days cannot also be specified. Any ids that don't correspond to campaigns that have been mailed out for the calling company will be ignored.

Output [vrtypens:FileSpec]

The output points to a URL where the csv file can be downloaded. Each line of the csv file contains a campaign id and the email address of one of the recipients of that campaign.

getEmailCreditBalance

The getEmailCreditBalance() method returns the email credit balance of the specified company.

Input [vrtypens:getEmailCreditBalanceArgs]

session_id [xsd:string] (required)
Your API session id.

company_id [xsd:int]

Output [xsd:int]

Examples

Perl PHP Ruby

my $credits_available = $vrapi->getEmailCreditBalance( {
    session_id => $sid, 
    company_id => 1234,
} );

$credits_available = $vrapi->enumerateLists( array(
    'session_id'          => $sid, 
    'company_id'          => 1234,
) );

credits_available = vr.enumerateLists({
    'session_id'          => sid, 
    'company_id'          => 1234,
})

getListDomainCount

The getListDomainCount() method retrieves the number of recipients on a specified list, by domain (optionally limited to the top N results or to a specified set of domains).

Input [vrtypens:getListDomainCountArgs]

session_id [xsd:string] (required)
Your API session id.

list_id [xsd:int] (required)
The list whose domains are being counted.

max_domains [xsd:int]
An amount to limit the results by.

restrict_domains [vrtypens:ArrayOfString]
An array of domains to limit the result by.

Output [vrtypens:getListDomainCountResult]

Examples

Perl PHP Ruby

$vrapi->getListDomainCount( {
    session_id => $sid,
    list_id => $lid,
    max_domains => 10,
} );

$vrapi->getListDomainCount( array(
    'session_id'  => $sid,
    'list_id'     => $lid,
    'max_domains' => 10
) );

vr.getListDomainCount({
    'session_id'  => sid,
    'list_id'     => lid,
    'max_domains' => 10
})

getListMemberByAddressHash

The getListMemberByAddressHash() method retrieves exactly one member with the specified address_hash from a specified list.

Input [vrtypens:getListMemberByAddressHashArgs]

session_id [xsd:string] (required)
Your API session id.

list_id [xsd:int] (required)
The id of the list being searched.

address_hash [xsd:string] (required)
The value of the "address_hash" NVPair in the desired ListMember's dictionary of fields.

Output [vrtypens:ListMember]

The output is the list member.

Examples

Perl PHP Ruby

$vrapi->getListMemberByAddressHash( {
    session_id => $sid,
    list_id => $lid,
    address_hash => 'f3f2f0f3a3',
} );

$vrapi->getListMemberByAddressHash( array(
    'session_id'   => $sid,
    'list_id'      => $lid,
    'address_hash' => 'f3f2f0f3a3',
) );

vr.getListMemberByAddressHash({
    'session_id'   => sid,
    'list_id'      => lid,
    'address_hash' => 'f3f2f0f3a3',
})

getListMemberByEmailAddress

The getListMemberByEmailAddress() method retrieves exactly one member with the specified email address from a specified list.

Input [vrtypens:getListMemberByEmailAddressArgs]

session_id [xsd:string] (required)
Your API session id.

list_id [xsd:int] (required)
The id of the list being searched

email_address [xsd:string] (required)
The email address of the list member being searched for

Output [vrtypens:ListMember]

The output is the list member.

Examples

Perl PHP Ruby

$vrapi->getListMemberByEmailAddress( {
    session_id => $sid,
    list_id => $lid,
    email_address => 'username@company.com'
} );

$vrapi->getListMemberByEmailAddress( array(
    'session_id'    => $sid,
    'list_id'       => $lid,
    'email_address' => 'username@company.com',
) );

vr.getListMemberByEmailAddress({
    'session_id'    => sid,
    'list_id'       => lid,
    'email_address' => 'username@company.com',
})

getListMemberByHash

The getListMemberByHash() method retrieves exactly one member with the specified hash from a specified list.

Input [vrtypens:getListMemberByHashArgs]

session_id [xsd:string] (required)
Your API session id.

list_id [xsd:int] (required)
The id of the list being searched

hash [xsd:string] (required)
The hash of the list member being searched for

Output [vrtypens:ListMember]

The output is the list member.

Examples

Perl PHP Ruby

$vrapi->getListMemberByHash( {
    session_id => $sid,
    list_id => $lid,
    hash => 'f3f2f0f3a3'
} );

$vrapi->getListMemberByHash( array(
    'session_id' => $sid,
    'list_id'    => $lid,
    'hash'       => 'f3f2f0f3a3',
) );

vr.getListMemberByHash({
    'session_id' => sid,
    'list_id'    => lid,
    'hash'       => 'f3f2f0f3a3',
})

getListMembers

The getListMembers() method retrieves a fixed number of members from a specified list. Ordering and offset information can be used to created "windowed" views of list member data.

Input [vrtypens:getListMembersArgs]

session_id [xsd:string] (required)
Your API session id.

list_id [xsd:int] (required)
The id of the list whose members are being retrieved.

max_records [xsd:int]
The maximum number of records to return.

offset [xsd:int]
Only records on or beyond this index are included in the result.

order_by_fields [vrtypens:ArrayOfOrderByField]
An array of fields and directions that specify an ordering for the returned campaigns.

first_order_by_field_start_at [xsd:string]
When order_by_fields is provided, this specifies a value for the first field that output should start at.

Output [vrtypens:ArrayOfListMember]

The output is an array of members that are in the specified list.

Examples

Perl PHP Ruby

$vrapi->getListMembers( {
    session_id => $sid,
    list_id => $lid,
} );

$vrapi->getListMembers( array(
    'session_id'=> $sid,
    'list_id'   => $lid,
) );

vr.getListMembers({
    'session_id'=> sid,
    'list_id'   => lid,
})

getPartnerIntegrationUser

The getPartnerIntegrationUser() method retrieves one VerticalResponse user with the specified partner integration and partner integration id. Please note that this method will never provide any User's password.

Input [vrtypens:getPartnerIntegrationUserArgs]

session_id [xsd:string] (required)
Your API session id.

partner_integration [xsd:string] (required)
The name of your partner integration.

partner_integration_user_id [xsd:string] (required)
The id used for this user in your own side of the partner integration (the value of the "partner_integration_user_id" argument you supplied to createUser when creating this User).

Output [vrtypens:User]

The user whose partner user integration id was specified if that user exists.

getPricingStructure

The getPricingStructure() method returns the pricing "tiers" for purchasing the specified type of credits. The "product_type" can be "email" or "postcard". The "product_details" field should be undefined for "email" and either "4x6" or "6x9" for "postcard".

Input [vrtypens:getPricingStructureArgs]

session_id [xsd:string] (required)
Your API session id.

product_type [xsd:string]

product_details [xsd:string]

Output [vrtypens:ArrayOfPricingStructureTier]

getPurchaseQuotation

The getPurchaseQuotation() method returns the quoted price for a given number of email or postcard credits.

Input [vrtypens:getPurchaseQuotationArgs]

session_id [xsd:string] (required)
Your API session id.

product_type [xsd:string]

product_details [xsd:string]

quantity [xsd:int]

promotion_code [xsd:string]

Output [vrtypens:getPurchaseQuotationResult]

getSentEmailCampaignsSummary

The getSentEmailCampaignsSummary() method returns a paginated window of campaign stats along with the total number of sent campaigns.

Input [vrtypens:getSentEmailCampaignsSummaryArgs]

session_id [xsd:string] (required)
Your API session id.

order_by [vrtypens:OrderByField]
The field and direction to sort by. Valid field_name values are:

campaign_id
campaign_name
campaign_type
status
sent_date
emails_sent
open_count
reopen_count
click_count
sale_count
purchase_total
bounce_count
unsub_count
responder_count

If no ordering is specified, then an ordering by descending sent_date is used by default.

limit [xsd:int]
The maximum number of records to return. Specifying a limit greater than 50 is not allowed. This is also the default limit that is used if none is provided.

offset [xsd:int]
Only records on or beyond this index are included in the result.

Output [vrtypens:getSentEmailCampaignsSummaryResult]

The output is a variety of stats for a set of sent email campaigns along with the total number of sent email campaigns. For each campaign, the info provided is:

campaign_id
campaign_name
campaign_type
status
sent_date
emails_sent
open_count
reopen_count
click_count
sale_count
purchase_total
bounce_count
unsub_count
responder_count

getSessionIDFromOauth

The getSessionIDFromOauth() method authenticates a 3rd party application linked to VerticalResponse based on Oauth credentials and returns a session_id token that can be used for subsequent VRAPI calls. The maximum allowed session length is 120 minutes. Third party app can impersonate linked accounts by specifying their application consumer key, user access token and additionally providing the impersonate access token for linked account that wants to access.

Input [vrtypens:getSessionIDFromOauthArgs]

consumer_key [xsd:string] (required)
Your VerticalResponse 3rd party application oauth consumer key

user_access_token [xsd:string] (required)
Your VerticalResponse oauth user access token (this account should be the 3rd party app owner)

session_duration_minutes [xsd:integer]
The session will close after this many minutes have elapsed since the last API call.

impersonate_access_token [xsd:string]
Log in as this account. Account should be linked to your 3rd party application through oauth. The value is the subaccount's access token.

Output [xsd:string]

The output is a session id - a token that uniquely identifies your new session (e.g., "92cf2c60a9eb1c50a73c4361d0543105").

Examples

Perl PHP Ruby C#.NET

my $sid = $vr->getSessionIDFromOauth( {
    consumer_key                 => 'your_app_consumer_key',
    user_access_token                 => 'your_secret_access_token',
    session_duration_minutes => 15,
} );
print "session id: $sessionId\n";

$sid = $vr->getSessionIDFromOauth( array( 
    'consumer_key'                 => 'your_app_consumer_key',
    'user_access_token'                 => 'your_secret_access_token',
    'session_duration_minutes' => 15,
) );
echo "session id: $sessionId\n";

sid = vr.getSessionIDFromOauth({
    'consumer_key'                 => 'your_app_consumer_key',
    'user_access_token'                 => 'your_secret_access_token',
    'session_duration_minutes' => 15,
})
echo "session id: $sessionId\n";

getSessionIDFromOauthArgs objla = new getSessionIDFromOauthArgs();
objla.consumer_key = strConsumerKey;
objla.user_access_token = strUserAccessToken.ToString();

string _sSessionId = vr.getSessionIDFromOauth(objla);

getSignonURLFromOauth

The getSignonURLFromOauth() authenticates the consumer key and user token to make sure they are valid 3rd party application and oauth access token. At the end it returns a URL that can be used once to log into VR application as the specified user without entering a password. The URL will be valid for the specified number of seconds, the maximum allowed time to live is 120 seconds. When the user logs out, they will be redirected to the logout_url specified when requesting the signon URL. When the user's session times out or the signon URL is invalid, the user will be redirected to the specified login URL or to the partner's specified login page if no login URL was specified.

Input [vrtypens:getSignonURLFromOauthArgs]

consumer_key [xsd:string] (required)
Your VerticalResponse 3rd party application oauth consumer key

user_access_token [xsd:string]
This account should be linked to your 3rd party application through oauth. The value is the account or subaccount's access token.

ttl [xsd:integer]
The number of seconds the user signon URL will be valid. This must be an integer between 1 and 120.

logout_url [xsd:string]
The URL to which the user should be redirected when they log out of the VR application.

login_url [xsd:string]
The URL to which the user should be redirected when their session times out. If this is not specified, the 3rd party app url value will be used.

post_login_path [xsd:string]
The path to which browsers will be redirected after successfully logging in via single signon. If not specified, the browser will be redirected to the default "welcome" page.

Output [xsd:string]

The output is a URL to which the 3rd party application can redirect the user to log them directly into the VerticalResponse application.

Examples

Perl PHP Ruby

my $sid = $vr->getSignonURLFromOauth( {
    consumer_key      => 'your_app_consumer_key',
    user_access_token => 'your_secret_access_token',
    ttl               => 60,
    logout_url        => 'http://www.somecompany.com/confirmLogout.html',
    login_url         => 'http://www.somecompany.com/login.html'
} );

$sid = $vr->getSessionIDFromOauth( array( 
    'consumer_key'      => 'your_app_consumer_key',
    'user_access_token' => 'your_secret_access_token',
    'ttl'               => 60,
    'logout_url'        => 'http://www.somecompany.com/confirmLogout.html',
    'login_url'         => 'http://www.somecompany.com/login.html'
) );

sid = vr.getSessionIDFromOauth({
    'consumer_key'      => 'your_app_consumer_key',
    'user_access_token' => 'your_secret_access_token',
    'ttl'               => 60,
    'logout_url'        => 'http://www.somecompany.com/confirmLogout.html',
    'login_url'         => 'http://www.somecompany.com/login.html'
})

getSubscriptionType

The getSubscriptionType() method returns information about the user's current subscription for the current company. Subscriptions type for companies should be PAYG or PPM. For PAYG accounts we should return the number of remaining credits for PPM accounts we should return the total number of email addresses that account can hold. Error handling: If for some reason we cannot determine the status for the account we are returning 'UNKNOWN' as the subscription_type. On similar way, if we cannot determine the credits or the PPM type we are returning empty values for the credit_balance and max_list_size.

Input [vrtypens:getSubscriptionTypeArgs]

session_id [xsd:string] (required)
Your API session id.

Output [vrtypens:SubscriptionType]

The output is a set of values containing the information about the user's current subscription.

Examples

Perl PHP Ruby

$vrapi->getSubscriptionType( {
    session_id => $sid,
} );

$vrapi->getSubscriptionType( array(
    'session_id' => $sid,
) );

vr.getSubscriptionType({
    'session_id' => sid,
})

getUser

The getUser() method retrieves one VerticalResponse user with the specified id. Please note that this method will never provide any User's password.

Input [vrtypens:getUserArgs]

session_id [xsd:string] (required)
Your API session id.

user_id [xsd:int] (required)
The id of the user being searched for.

Output [vrtypens:User]

The user whose id was specified if that user exists.

Examples

Perl PHP Ruby

$vrapi->getUser( {
    session_id => $sid,
    user_id    => $uid,
} );

$vrapi->getUser( array(
    'session_id' => $sid,
    'user_id'    => $uid,
) );

vr.getUser({
    'session_id' => sid,
    'user_id'    => uid,
})

getUserByEmailAddress

The getUserByEmailAddress() method retrieves one VerticalResponse user with the specified email address. Please note that this method will never provide any User's password.

Input [vrtypens:getUserByEmailAddressArgs]

session_id [xsd:string] (required)
Your API session id.

email_address [xsd:string] (required)
The email address of the user being searched for.

Output [vrtypens:User]

The user whose email address was specified if that user exists.

Examples

Perl PHP Ruby

$vrapi->getUserByEmailAddress( {
    session_id => $sid,
    email_address => 'user@company.com'
} );

$vrapi->getUserByEmailAddress( array(
    'session_id' => $sid,
    'email_address' => 'user@company.com'
) );

vr.getUserByEmailAddress({
    'session_id'    => sid
    'email_address' => 'user@company.com'
})

getUserSignonURL

The getUserSignonURL() method authenticates the specified VerticalResponse user and returns a URL that can be used once to log in as the specified user without entering a password. The URL will be valid for the specified number of seconds, the maximum allowed time to live is 120 seconds. When the user logs out, they will be redirected to the logout_url specified when requesting the signon URL. When the user's session times out or the signon URL is invalid, the user will be redirected to the specified login URL or to the partner's specified login page if no login URL was specified.

Input [vrtypens:getUserSignonURLArgs]

session_id [xsd:string] (required)
Your API session id.

ttl [xsd:integer]
The number of seconds the user signon URL will be valid. This must be an integer between 1 and 120.

logout_url [xsd:string]
The URL to which the user should be redirected when they log out of the VR application.

login_url [xsd:string]
The URL to which the user should be redirected when their session times out. If this is not specified, the global cobrand value will be used.

user [xsd:string]
Log in as this partner subaccount. The value is the subaccount's application login username (an email address). This cannot be provided if impersonate_partner_integration_user is provided.

partner_integration_user [xsd:string]
Log in as this partner subaccount. The value is the subaccount's partner user id (supplied as the "partner_integration_user_id" argument to createUser). This cannot be provided if impersonate_user is provided. If this is provided, then partner_integration must also be provided.

partner_integration [xsd:string]
The name of your partner integration. This is only required if impersonate_partner_integration_user is provided.

Output [xsd:string]

The output is a URL to which the partner application can redirect the user to log them directly into the VerticalResponse application.

Examples

Perl PHP Ruby

$vrapi->getUserSignonURL( {
    session_id => $sid,
    ttl => 60,
    logout_url => 'http://www.somecompany.com/confirmLogout.html',
    login_url => 'http://www.somecompany.com/login.html',
    user => 'myuser@somecompany.com'
} );

$vrapi->getUserSignonURL( array(
    'session_id' => $sid,
    'ttl' => 60,
    'logout_url' => 'http://www.somecompany.com/confirmLogout.html',
    'login_url' => 'http://www.somecompany.com/login.html',
    'user' => 'myuser@somecompany.com'
) );

vr.getUserSignonURL({
    'session_id' => sid,
    'ttl' => 60,
    'logout_url' => 'http://www.somecompany.com/confirmLogout.html',
    'login_url' => 'http://www.somecompany.com/login.html',
    'user' => 'myuser@somecompany.com'
})

launchEmailCampaign

The launchEmailCampaign() method is used to launch a campaign once it is ready. Before launching a campaign must have its from_label and support_email attributes set.

For template (wizard) campaigns, the following contents must be set:

subject
unsub_message
unsub_link_text
postal_address

For freeform and canvas campaigns, the following contents must be set:

subject
freeform_html
freeform_text
unsub_message
unsub_link_text
postal_address

For freeform_text campaigns, the following contents must be set:

subject
freeform_text
unsub_message
unsub_link_text
postal_address

Your company must have enough credits to cover the number of recipients that will receive the campaign, and any merge field in the campaign must be covered by fields in all the attached lists. After launching, the campaign will mail out on its mail_date.

Input [vrtypens:launchEmailCampaignArgs]

session_id [xsd:string] (required)
Your API session id.

campaign_id [xsd:int] (required)
The id of the campaign to launch.

dry_run [xsd:int]
If this is set to 1, then go through all the motions of launching a campaign (calculating audience, checking for sufficient credits, etc.) except for the actual launch.

Output [vrtypens:launchEmailCampaignResult]

Examples

Perl PHP Ruby

$vrapi->launchEmailCampaign( {
    session_id  => $sid,
    campaign_id => $cid,
} );

$vrapi->launchEmailCampaign( array(
    'session_id'  => $sid,
    'campaign_id' => $cid,
) );

vr.launchEmailCampaign({
    'session_id'  => sid,
    'campaign_id' => cid,
})

The login() method authenticates a VerticalResponse user and returns a session_id token that can be used for subsequent VRAPI calls. The maximum allowed session length is 120 minutes. Partners can impersonate a subaccount by specifying their own login credentials and additionally providing the subaccount's email address for the "impersonate_user" argument.

Input [vrtypens:loginArgs]

username [xsd:string] (required)
Your VerticalResponse application login user name (an email address)

password [xsd:string] (required)
Your VerticalResponse application login password

session_duration_minutes [xsd:integer]
The session will close after this many minutes have elapsed since the last API call.

impersonate_user [xsd:string]
Log in as this partner subaccount. The value is the subaccount's application login username (an email address). This cannot be provided if impersonate_partner_integration_user is provided.

impersonate_partner_integration_user [xsd:string]
Log in as this partner subaccount. The value is the subaccount's partner user id (supplied as the "partner_integration_user_id" argument to createUser). This cannot be provided if impersonate_user is provided. If this is provided, then partner_integration must also be provided.

partner_integration [xsd:string]
The name of your partner integration. This is only required if impersonate_partner_integration_user is provided.

Output [xsd:string]

The output is a session id - a token that uniquely identifies your new session (e.g., "92cf2c60a9eb1c50a73c4361d0543105").

Examples

Perl PHP Ruby C#.NET

my $sid = $vr->login( {
    username                 => 'joe@mycompany.com',
    password                 => 'secret',
    session_duration_minutes => 15,
} );
print "session id: $sessionId\n";

$sid = $vr->login( array( 
    'username'                 => 'joe@mycompany.com',
    'password'                 => 'secret',
    'session_duration_minutes' => 15,
) );
echo "session id: $sessionId\n";

sid = vr.login({
    'username'                 => 'joe@mycompany.com',
    'password'                 => 'secret',
    'session_duration_minutes' => 15,
})
echo "session id: $sessionId\n";

loginArgs objla = new loginArgs();
objla.username = strUserName;
objla.password = strPassword.ToString();

string _sSessionId = vr.login(objla);

makeCreditCardPurchase

The makeCreditCardPurchase() method performs the specified purchase against the specified credit card. Any authorization errors are returned by the method. Gateway, database, or other errors are thrown as faults.

Input [vrtypens:makeCreditCardPurchaseArgs]

session_id [xsd:string] (required)
Your API session id.

credit_card [vrtypens:CreditCard]
The credit card to charge. If the 'id' field of this structure is specified, then the stored credit card with that ID is used. Otherwise, the credit card info provided in the CreditCard structure is used.

line_items [vrtypens:ArrayOfPurchaseLineItem]
The line item(s) to be purchased.

promotion_code [xsd:string]
Whether to pre-auth the supplied credit card rather than actually performing the authorization and funds capture.

campaign_id [xsd:int]
The campaign to which the purchase should be associated (postcard purchases only).

remote_ip [xsd:string]
The IP address of the remote user invoking the credit card transaction, if known.

send_receipt_to [xsd:string]
An email address to send a purchase receipt to.

Output [vrtypens:makeCreditCardPurchaseResult]

moveFile

The moveFile() method moves a file within your Library from one location to another. A file move that would result in the replacement of an existing file requires presence of the "force" argument.

Input [vrtypens:moveFileArgs]

session_id [xsd:string] (required)
Your API session id.

source [xsd:string] (required)
Library path to file to move (e.g., "/logos/fall.jpg")

target [xsd:string] (required)
Library path to destination of move (e.g., "/logos/fall/fall_2007.jpg")

force [xsd:boolean]
Whether to prevent a fault from being thrown when the move would result in a file being overwritten

Output [xsd:boolean]

Examples

Perl PHP

$vrapi->moveFile( {
    session_id => $sid,
    source     => '/foo/bar/baz.jpg',
    target     => '/baz/bar/quux.jpg',
    force      => 1,
} );

$vrapi->moveFile( array(
    'session_id' => $sid,
    'source'     => '/foo/bar/baz.jpg',
    'target'     => '/baz/bar/quux.jpg',
    'force'      => 1,
) );

refresh

The refresh() method refreshes an existing session created by login(), extending the timeout window of the existing session by the amount specified in the session_duration_minutes argument to the login() call that created the session.

Input [vrtypens:refreshArgs]

session_id [xsd:string] (required)
Your API session id.

Output [xsd:boolean]

The output is always true.

Examples

Perl PHP Ruby C#.NET

$vr->refresh( {
    session_id =>$sid
} );

$vr->refresh( array(
   'session_id' => $sid,
) );

vr.refresh({
   'session_id' => sid,
})

refreshArgs objRefresh = new refreshArgs();
objRefresh.session_id = _sSessionId;

objVR.refresh(objRefresh);

renderCampaignContent

The renderCampaignContent() method is used to provide a picture of what the finished campaign looks like. The campaign can be specified by id or by hash. The content_type should be set to either "html" or "text". The only view_type currently supported is "preview".

Input [vrtypens:renderCampaignContentArgs]

session_id [xsd:string] (required)
Your API session id.

campaign_id [xsd:int]
The ID of the campaign to render. Either this or "campaign_hash" must be provided.

campaign_hash [xsd:string]
The hash of the campaign to render. Either this or "campaign_id" must be provided.

content_type [xsd:string] (required)
Set this to "html" for an HTML rendering of the campaign, and set it to "text" for a text-only rendering of the campaign.

view_type [xsd:string] (required)
Set this to "preview" for a preview rendering of the campaign, and set it to "mailing" for an actual mailable rendering of the campaign. For actual mailable renderings, all links are replaced with redirect links.

max_text_line_length [xsd:int]
For text-only renderings of a campaign, this is the width of a line in the rendering after text wrapping. The default value is 70.

Output [vrtypens:renderCampaignContentResult]

Examples

Perl PHP Ruby

$vrapi->renderCampaignContent( {
    session_id   => $sid,
    campaign_id  => $cid,
    view_type    => 'preview',
    content_type => 'html',
} );

$vrapi->renderCampaignContent( array(
    'session_id'     => $sid,
    'campaign_id'    => $cid,
    'view_type'      => 'preview',
    'content_type'   => 'html',
) );

vr.renderCampaignContent({
    'session_id'     => sid,
    'campaign_id'    => cid,
    'view_type'      => 'preview',
    'content_type'   => 'html',
})

runSegmentationQuery

The runSegmentationQuery() method compiles the results associated with each input for a given segmentation query, and then finally for the segmentation query itself. This method can be called by itself, or will be implicitly called by compileSegmentationQuery() on an as-needed basis. The output of the method will be the total number of email addresses found that matched the query.

Input [vrtypens:runSegmentationQueryArgs]

session_id [xsd:string] (required)
Your API session id.

segmentation_query_id [xsd:int]

notification_email_address [xsd:string]

Output [xsd:int]

Examples

Perl PHP Ruby

$vr->runSegmentationQuery({
   session_id => $sid,
   segmentation_query_id => $seg_id,
   notification_email_address = 'your@company.com'
});

$vr->runSegmentationQuery(array(
   'session_id' => $sid,
   'segmentation_query_id' => $seg_id,
   'notification_email_address' = 'your@company.com'
));

vr.runSegmentationQuery({
   'session_id' => sid,
   'segmentation_query_id' => seg_id,
   'notification_email_address' = 'your@company.com'
})

runSegmentationQueryBackground

The runSegmentationQueryBackground() method performs the same tasks as the runSegmentationQuery() method, but does so after detaching and running as a background process. The return value of the runSegmentationQueryBackground() method is a background task ID that can be used to poll for the task status using getBackgroundTaskStatus(). The final results of the runSegmentationQueryBackground() method can be retrieved using the fetchRunSegmentationQueryBackgroundResult() method.

Input [vrtypens:runSegmentationQueryArgs]

session_id [xsd:string] (required)
Your API session id.

segmentation_query_id [xsd:int]

notification_email_address [xsd:string]

Output [xsd:int]

Examples

Perl PHP Ruby

$vr->runSegmentationQueryBackground({
   session_id => $sid,
   segmentation_query_id => $seg_id,
   notification_email_address = 'your@company.com'
});

$vr->runSegmentationQueryBackground(array(
   'session_id' => $sid,
   'segmentation_query_id' => $seg_id,
   'notification_email_address' = 'your@company.com'
));

vr.runSegmentationQueryBackground({
   'session_id' => sid,
   'segmentation_query_id' => seg_id,
   'notification_email_address' = 'your@company.com'
})

searchListMembers

The searchListMembers() searches across all member lists for records containing a specified value in a specified field. Only field names that have been set in a call to setIndexedListFields() can be used in a search.

Input [vrtypens:searchListMembersArgs]

session_id [xsd:string] (required)
Your API session id.

field_name [xsd:string] (required)
The name of the field to search by. This should be a list field name. Lists that don't contain this field won't be searched.

field_value [xsd:string] (required)
The value that's desired in the result ListMembers. The call returns only ListMembers whose value for the given field name matches this.

list_id [xsd:int]
If this is set, then the search will be limited to the specified list. Otherwise the search is performed across all lists.

list_ids [xsd:string]
To find occurrences in specific lists use a comma separated string of list ids.

max_records [xsd:int]
Set this argument to limit the number of ListMembers returned

recursive_search [xsd:int]
Assign 1 to this argument to search for occurrences in all lists.

Output [vrtypens:ArrayOfListMember]

An array of ListMembers that match the query arguments

Examples

Perl PHP Ruby

$vrapi->searchListMembers( {
    session_id => $sid,
    field_name => 'Country',
    field_value => 'Mexico',
    max_records => 200
} );

$vrapi->searchListMembers( array(
    'session_id'  => $sid,
    'field_name'  => 'Country',
    'field_value' => 'Mexico',
    'max_records' => 200
) );

vr.searchListMembers({
    'session_id'  => sid,
    'field_name'  => 'Country',
    'field_value' => 'Mexico',
    'max_records' => 200
})

sendEmailCampaignTest

The sendEmailCampaignTest() method mails a test version of the specified campaign to a specified list of recipients. Provide each recipient as a list of name/value pairs. Each recipient must contain an "email_address" name/value pair. The number of test emails is limited to 10 per call.

Input [vrtypens:sendEmailCampaignTestArgs]

session_id [xsd:string] (required)
Your API session id.

campaign_id [xsd:int] (required)
The id of the campaign to test

recipients [vrtypens:ArrayOfNVDictionary] (required)
An array whose items are each an NVDictionary describing a test email recipient. Each NVDictionary should at least contain an "email_address" entry.

Output [vrtypens:sendEmailCampaignTestResult]

Examples

Perl PHP Ruby

$vrapi->sendEmailCampaignTest( {
    session_id => $sid,
    campaign_id => $cid,
    recipients => [
        {
            name => 'email_address',
            value => 'test_email@company.com'
        },
        {
            name => 'first_name',
            value => 'Joe'
        },
    ],
} );

$vrapi->sendEmailCampaignTest( array(
    'session_id'  => $sid,
    'campaign_id' => $cid,
    'recipients'  => array(
        array(
            name => 'email_address',
            value => 'test_email@company.com'
        ),
        array(
            name => 'first_name',
            value => 'Joe'
        ),
    ),
) );

vr.sendEmailCampaignTest({
    'session_id'  => sid,
    'campaign_id' => cid,
    'recipients'  => [
        {
            name => 'email_address',
            value => 'test_email@company.com'
        },
        {
            name => 'first_name',
            value => 'Joe'
        },
    ],
})

setCampaignLists

The setCampaignLists() method is used to specify which lists a campaign should be mailed to when launched. If the campaign contains a merge field that's not present in one of the lists, then a fault is thrown.

Input [vrtypens:setCampaignListsArgs]

session_id [xsd:string] (required)
Your API session id.

campaign_id [xsd:int] (required)
The id of the campaign whose lists are being set.

list_ids [vrtypens:ArrayOfInteger] (required)
The ids of the lists that are to be associated with this campaign.

Output [xsd:boolean]

The output is always true.

Examples

Perl PHP Ruby

$vrapi->setCampaignLists( {
    session_id  => $sid,
    campaign_id => $cid,
    list_ids    => [ $lid, $lid2, $lid3, $lid4 ],
} );

$vrapi->setCampaignLists( array(
    'session_id'  => $sid,
    'campaign_id' => $cid,
    'list_ids'    => array( $lid, $lid2, $lid3 )
) );

vr.setCampaignLists({
    'session_id'  => sid,
    'campaign_id' => cid,
    'list_ids'    => [ lid, lid2, lid3 ]
})

setCustomListFields

The setCustomListFields() method changes the list of custom (non-standard) fields for the specified list.

Warning: This call will remove any custom fields that are already present in a list if those custom fields aren't provided in the fields argument. When adding new custom fields to a list, you should first obtain a list of the current custom fields, add the new fields to it, and call setCustomListFields() with the combined list of field names.

Input [vrtypens:setCustomListFieldsArgs]

session_id [xsd:string] (required)
Your API session id.

list_id [xsd:int] (required)
The id of the list whose custom field names are being set.

fields [vrtypens:ArrayOfString] (required)
The names of the custom fields that should exist for this list.

widths [vrtypens:ArrayOfString] (required)
An array of widths for the custom fields. This array should match 1 on 1 with the fields array. Allowed widths: "small", "medium", "large". Defaults to "medium"

Output [xsd:boolean]

The output is always true.

Examples

Perl PHP Ruby

$vrapi->setCustomListFields( {
    session_id => $sid,
    list_id    => $lid,
    fields     => [ 'customerID', 'cell_phone' ],
    widths     => [ 'medium', 'small' ]
} );

$vrapi->setCustomListFields( array(
    'session_id' => $sid,
    'list_id'    => $lid,
    'fields'     => array( 'customerID', 'cell_phone' ),
    'widths'     => array( 'medium', 'small' )
) );

vr.setCustomListFields({
    'session_id' => sid,
    'list_id'    => lid,
    'fields'     => [ 'customerID', 'cell_phone' ],
    'widths'     => [ 'medium', 'small' ]
})

setDisplayedListFields

The setDisplayedListFields() method sets the fields which are displayed when viewing a list in the VerticalResponse application.

Input [vrtypens:setDisplayedListFieldsArgs]

session_id [xsd:string] (required)
Your API session id.

list_id [xsd:int] (required)
The id of the list whose displayed fields are being set.

displayed_fields [vrtypens:ArrayOfString] (required)
A list of the names of the fields that should be displayed.

Output [xsd:boolean]

The output is always true.

Examples

Perl PHP Ruby

$vrapi->setDisplayedListFields( {
    session_id => $sid,
    list_id    => $lid,
    displayed_fields => [ 'email_address', 'first_name', 'state' ],
} );

$vrapi->setDisplayedListFields( array(
    'session_id'      => $sid,
    'list_id'         => $lid,
    'displayed_fields' => array( 'email_address', 'first_name', 'state' ),
) );

vr.setDisplayedListFields({
    'session_id'      => sid,
    'list_id'         => lid,
    'displayed_fields' => [ 'email_address', 'first_name', 'state' ],
})

setEmailCampaignAttribute

The setEmailCampaignAttribute() method is used to specify a field for the given campaign.

Attributes that can be set for a campaign are:

name
template_id (for template campaigns)
send_friend
from_label
support_email
redirect_url
mail_date

Input [vrtypens:setEmailCampaignAttributeArgs]

session_id [xsd:string] (required)
Your API session id.

campaign_id [xsd:int] (required)
The id of the campaign whose attribute is being set.

name [xsd:string] (required)
The name of the attribute being set.

value [xsd:string] (required)
The attribute's new value.

Output [xsd:boolean]

The output is always true.

Examples

Perl PHP

$vrapi->setEmailCampaignAttribute( {
    session_id => $sid,
    campaign_id => $cid,
    name => 'support_email',
    value => 'new_support_email@address.com',
} );

$vrapi->setEmailCampaignAttribute( array(
    'session_id' => $sid,
    'campaign_id' => $cid,
    'name' => 'support_email',
    'value' => 'new_support_email@address.com',
) );

setEmailCampaignContent

The setEmailCampaignContent() method is used to add or change a block of copy for an email campaign. The content type must be valid for the specified campaign's type, and the number of bytes in the copy must not exceed the freeform upload limit for your company.

Valid content types for template (wizard) campaigns are:

subject
salutation
greeting
closing
unsub_message
unsub_link_text
postal_address
custom_color

Valid content types for freeform and canvas campaigns are:

subject
freeform_html
freeform_text
unsub_message
unsub_link_text
postal_address

Valid content types for freeform_text campaigns are:

subject
freeform_text
unsub_message
unsub_link_text
postal_address

Input [vrtypens:setEmailCampaignContentArgs]

session_id [xsd:string] (required)
Your API session id.

campaign_id [xsd:int] (required)
The id of the campaign whose content is being set.

content [vrtypens:EmailCampaignContent] (required)
The type and copy of the content being set

Output [xsd:boolean]

The output is always true.

Examples

Perl PHP Ruby

# set the subject of this campaign to "summer sale starts tomorrow"
$api->setEmailCampaignContent( {
    session_id  => $sid
    campaign_id => 42,
    content     => {
        type => 'subject',
        copy => 'summer sale starts tomorrow',
    },
} );

# set the subject of this campaign to "summer sale starts tomorrow"
$vrapi->setEmailCampaignContent( array(
    'session_id'  => $sid
    'campaign_id' => 42,
    'content'     => array(
        'type' => 'subject',
        'copy' => 'summer sale starts tomorrow',
    ),
) );

# set the subject of this campaign to "summer sale starts tomorrow"
vr.setEmailCampaignContent({
    'session_id'  => sid,
    'campaign_id' => 42,
    'content'     => {
        'type' => 'subject',
        'copy' => 'summer sale starts tomorrow',
    },
})

setIndexedListFields

The setIndexedListFields() method sets the fields which are indexed for a given list. Only fields that are indexed may be specified in calls to searchListMembers().

Input [vrtypens:setIndexedListFieldsArgs]

session_id [xsd:string] (required)
Your API session id.

list_id [xsd:int] (required)
The id of the list whose indexed fields are being set

indexed_fields [vrtypens:ArrayOfString] (required)
A list of the names of the fields that should be indexed.

Output [xsd:boolean]

The output is always true.

Examples

Perl PHP Ruby

$vrapi->setIndexedListFields( {
    session_id => $sid,
    list_id => $cid,
    indexed_fields => ['country'],
} );

$vrapi->setIndexedListFields( array (
    'session_id'     => $sid,
    'list_id'        => $cid,
    'indexed_fields' => array ( 'country' ),
));

vr.setIndexedListFields({
    'session_id'     => sid,
    'list_id'        => cid,
    'indexed_fields' => [ 'country' ],
})

setTemplateCampaignModule

The setTemplateCampaignModule() method is used to replace the contents of an existing template campaign module. The specified email campaign must be a template (wizard) campaign, and a module with the specified position must already exist within that campaign.

Input [vrtypens:setTemplateCampaignModuleArgs]

session_id [xsd:string] (required)
Your API session id.

campaign_id [xsd:int] (required)
The id of the campaign whose template module is being set.

module [vrtypens:TemplateCampaignModule] (required)
The new module contents.

Output [xsd:boolean]

The output is always true.

Examples

Perl PHP

$vrapi->setTemplateCampaignModule( {
    session_id => $sid,
    campaign_id => $cid,
    module => {
        position => 3,
        template_id => 8,
        title => 'This is a text only module',
        copy => 'Text-only users unite!'
    },
} );

$vrapi->setTemplateCampaignModule( array(
    'session_id'  => $sid,
    'campaign_id' => $cid,
    'module'      => array (
        'position'    => 3,
        'template_id' => 8,
        'title'       => 'This is a text only module',
        'copy'        => 'Text-only users unite!'
    ),
) );

transferEmailCredits

The transferEmailCredits() method transfers email credits from one company's account to another. The number of credits transferred must be a whole number greater than or equal to one, and the company from which the credits are being transferred must have sufficient credits in its account for the requested transaction.

Input [vrtypens:transferEmailCreditsArgs]

session_id [xsd:string] (required)
Your API session id.

from_company_id [xsd:int]

to_company_id [xsd:int]

credits_to_transfer [xsd:int]

Output [xsd:boolean]

Examples

Perl PHP Ruby

$vrapi->transferEmailCredits( {
    session_id => $sid, 
    from_company_id => 1234,
    to_company_id => 5678,
    credits_to_transfer => 5000,
} );

$vrapi->enumerateLists( array(
    'session_id'          => $sid, 
    'from_company_id'     => 1234,
    'to_company_id'       => 5678,
    'credits_to_transfer' => 5000,
) );

vr.enumerateLists({
    'session_id'          => sid, 
    'from_company_id'     => 1234,
    'to_company_id'       => 5678,
    'credits_to_transfer' => 5000,
})

undeleteCampaign

The undeleteCampaign() method restores a campaign to the state it was in prior to being deleted.

Input [vrtypens:undeleteCampaignArgs]

session_id [xsd:string] (required)
Your API session id.

campaign_id [xsd:int] (required)
The id of the campaign to undelete.

Output [xsd:boolean]

The output is always true.

Examples

Perl PHP Ruby

$vrapi->undeleteCampaign( {
    session_id => $sid,
    campaign_id => $cid,
} );

$vrapi->undeleteCampaign( array (
    'session_id' => $sid,
    'campaign_id' => $cid,
) );

vr.undeleteCampaign({
    'session_id'  => sid,
    'campaign_id' => cid,
})

undeleteList

The undeleteList() method restores a deleted list back to an active (undeleted) status.

Input [vrtypens:undeleteListArgs]

session_id [xsd:string] (required)
Your API session id.

list_id [xsd:int] (required)
The id of the list to undelete.

Output [xsd:boolean]

The output is always true.

Examples

Perl PHP Ruby

$vrapi->undeleteList( {
    session_id => $sid,
    list_id => $lid,
} );

$vrapi->undeleteList( array (
    'session_id' => $sid,
    'list_id'    => $lid,
) );

vr.undeleteList({
    'session_id' => sid,
    'list_id'    => lid,
})

undeleteSegmentationQuery

The undeleteSegmentationQuery() method restores a segmentation query to the state it was in prior to being deleted.

Input [vrtypens:undeleteSegmentationQueryArgs]

session_id [xsd:string] (required)
Your API session id.

segmentation_query_id [xsd:int]

Output [xsd:boolean]

Examples

Perl PHP Ruby

$vr->undeleteSegmentationQuery({
   session_id => $sid, 
   segmentation_query_id => $seg_id
});

$vr->undeleteSegmentationQuery(array(
   'session_id' => $sid,
   'segmentation_query_id' => $seg_id,
));

vr.undeleteSegmentationQuery({
   'session_id' => sid,
   'segmentation_query_id' => seg_id,
})

unlaunchEmailCampaign

The unlaunchEmailCampaign() method is used to cancel the launch of a campaign. It simply changes the campaign's status to "active". If the campaign is already in the process of mailing or if it has already been mailed, then a fault is thrown.

Input [vrtypens:unlaunchEmailCampaignArgs]

session_id [xsd:string] (required)
Your API session id.

campaign_id [xsd:int] (required)
The id of the campaign to unlaunch.

Output [xsd:boolean]

The output is always true.

Examples

Perl PHP Ruby

$vrapi->unlaunchEmailCampaign( {
    session_id =>$sid,
    campaign_id => $cid,
} );

$vrapi->unlaunchEmailCampaign( array(
    'session_id'  => $sid,
    'campaign_id' => $cid, 
));

vr.unlaunchEmailCampaign({
    'session_id'  => sid,
    'campaign_id' => cid, 
})

unsetOauthToken

The unsetOauthToken() method removes an access token for a subaccount. This will remove the link of the account with the 3rd party application, preventing app to access account data again with such token. Method can only be accessed by 3rd party application admin account

Input [vrtypens:unsetOauthTokenArgs]

session_id [xsd:string] (required)
Your API session id.

user_access_token [xsd:string]
This account should be linked to your 3rd party application through oauth. The value is the subaccount's access token.

Output [xsd:boolean]

Returns true if token was unset correctly, false otherwise

Examples

Perl PHP Ruby

my $ret = $vr->unsetOauthToken( {
    session_id        => $sid, 
    user_access_token => 'your_secret_access_token',
} );

$ret = $vr->unsetOauthToken( array( 
    'session_id'        => $sid, 
    'user_access_token' => 'your_secret_access_token',
) );

ret = vr.unsetOauthToken({
    'session_id'        => sid, 
    'user_access_token' => 'your_secret_access_token',
})

updateEmailContents

The updateEmailContents() method updates the html and text content for specified email.

Input [vrtypens:updateEmailContentsArgs]

session_id [xsd:string] (required)
Your API session id.

email_id [xsd:int]
This email's ID. Provided by VerticalResponse.

freeform_html [xsd:string]
The HTML content of the email.

freeform_text [xsd:string]
The text-only content of the email.

Output [xsd:boolean]

The output is a boolean representing if contents were updated or not.

Examples

Perl PHP Ruby C#.NET

$vrapi->updateEmailContents( {
    session_id    => $sid,
    email_id      => $eid,
    freeform_html => $html_content,
    freeform_text => $text_content
} );

$vrapi->updateEmailContents( array(
    'session_id'    => $sid,
    'email_id'      => $eid,
    'freeform_html' => $html_content,
    'freeform_text' => $text_content
) );

vr.updateEmailContents({
  'session_id'    => sid,
  'email_id'      => eid,
  'freeform_html' => html_content,
  'freeform_text' => text_content
})

updateEmailContentsArgs objUpdateEmailContents = new updateEmailContentsArgs();
objUpdateEmailContents.session_id = _sSessionId;
objUpdateEmailContents.email_id = iemailId;
objUpdateEmailContents.freeform_html = _sHtmlContent;
objUpdateEmailContents.freeform_text = _sTextContent;

vr.updateEmailContents(objUpdateEmailContents);

userExistsByEmailAddress

The userExistsByEmailAddress() method returns true if the VerticalResponse user with the specified email address exists.

Input [vrtypens:userExistsByEmailAddressArgs]

session_id [xsd:string] (required)
Your API session id.

email_address [xsd:string] (required)
The email address of the user being searched for.

Output [xsd:boolean]

True if the user exists, false otherwise.

Examples

Perl PHP Ruby

$vrapi->userExistsByEmailAddress( {
    session_id => $sid,
    email_address => 'user@company.com'
} );

$vrapi->userExistsByEmailAddress( array(
    'session_id' => $sid,
    'email_address' => 'user@company.com'
) );

vr.userExistsByEmailAddress({
    'session_id'    => sid
    'email_address' => 'user@company.com'
})