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.
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.
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).
The appendTemplateCampaignModule() adds a module to the end of a template campaign's list of modules.
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.
The canCallMethod() method determines whether the current session is allowed to call the specified server method.
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.
The asynchronous version of compileCampaignRecipientResults(). This method is invoked and
the results are emailed to the caller.
The compileSegmentationQuery() method compiles one or more mailing lists
based on the results of a given segmentation query.
The asynchronous version of compileSegmentationQuery(). This method is invoked and the results are emailed to the caller.
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.
The createEmail() method creates the specified email.
The createEmailCampaign() method creates the specified email campaign.
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.
The createList() method creates a new email or mailing list in the VR system, but does not append any members to that list.
The createSegmentationQuery() method creates a new database segmentation query.
The deleteCampaign() method soft deletes a campaign. This operation can be undone with a call to undeleteCampaign().
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.
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.
The deleteList() method deletes a single VR mailing list.
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.
The deleteSegmentationQuery() method deletes an existing database segmentation query.
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.
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.
The asynchronous version of downloadCampaignRecipientResults(). This method is invoked and
the results are emailed to the caller.
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.
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.
The asynchronous version of downloadList(). The method is invoked and the results are emailed to the caller.
The editCompany() method updates the specified Company object.
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.
The editListAttribute() method edits one attribute an existing list. Currently supported attributes are "name" and "form_id".
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.
The editListMembers() method edits one or more list members. If the new list member values fail validation, an exception is thrown.
The editSegmentationQuery() method edits an existing database segmentation query.
The editUser() method updates the specified User object.
The emptyTrash() method removes all the files from the /Trash directory in the Library.
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.
The enumerateEmailLayoutCategories() method enumerates all email layout categories.
The enumerateEmailLayouts() method provides a way to list all layouts within a given layout category.
Multiple layout categories can be specified.
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.
The enumerateFiles() method provides a way to list files and directories in your Library.
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.
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.
The eraseListMembers() deletes all of the members from a list permanently, but leaves the list (now with zero members) intact.
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.
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.
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.
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.
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.
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.
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)
The getCompany() method returns the specified company.
Please note that if User information is requested, this method will never provide any User's password.
The getCompanySummary() method reports various summary statistics such as list count and campaign count for a company.
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.
The getEmailCampaignResponseHistorgrams() method provides campaign response stats such as opens, clicks, bounces, and unsubscribes in histogram form suitable for input into graphing tools.
The getEmailCampaignStats() method provides a variety of statistical information for a given campaign specified by id.
The getEmailCreditBalance() method returns the email credit balance of the specified company.
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).
The getListMemberByAddressHash() method retrieves exactly one member with the specified address_hash from a specified list.
The getListMemberByEmailAddress() method retrieves exactly one member with the specified email address from a specified list.
The getListMemberByHash() method retrieves exactly one member with the specified hash from a specified list.
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.
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".
The getPurchaseQuotation() method returns the quoted price for a given number of email or postcard credits.
The getSentEmailCampaignsSummary() method returns a paginated window of campaign stats along with the total number of sent campaigns.
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.
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.
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.
The getUser() method retrieves one VerticalResponse user with the specified id.
Please note that this method will never provide any User's password.
The getUserByEmailAddress() method retrieves one VerticalResponse user with the specified email address.
Please note that this method will never provide any User's password.
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.
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.
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.
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.
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.
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".
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.
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.
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.
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.
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.
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.
The setDisplayedListFields() method sets the fields which are displayed when viewing a list in the VerticalResponse application.
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
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
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().
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.
The storeArchiveEmailCampaign() method is used to obtain the URL of the Archived version of a specific email campaign.
If the archived version doesn't exist, the method will render it and store it.
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.
The undeleteCampaign() method restores a campaign to the state it was in prior to being deleted.
The undeleteList() method restores a deleted list back to an active (undeleted) status.
The undeleteSegmentationQuery() method restores a segmentation query to the state it was in prior to being deleted.
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.
The updateEmailContents() method updates the html and text content for specified email.
The VerticalResponse API Server - Enterprise Edition