API: HTTP Show Optouts

The Show Optouts command allows you to return all contacts that are opted out of a single list, regardless of origin of the event. The command requires the following arguments: Command, Realm, Password, List ID, and Days.

api_web?r=myrealm&p=mypass&c=show_opt&list_id=5&days=7

The command is ‘show_opt’, the realm is ‘myrealm’, the password is ‘mypass’ and will return optouts that occurred for list_id='5' in the last 7 days.

The command will attempt to find all contact optouts associated with the specified list and return the results. A successful search will return a list of email addresses that have been opted out of the list.

Example

Using all commands and arguments (please note the command is wrapped for display purposes only):

api_web?c=show_opt&r=myrealm&p=mypass&list_id=5&days=30&output_format=csv&headers=1

Successful results return:

"Email"
"jane@mydomain.com"
"john@mydomain.com"
"joe@mydomain.com"

Some systems have the ability to define a unique Customer Key per contact. If your realm has Customer Key enabled, and additional column "customer_key" will be included in the results.

Results

The Show Optout command outputs either the results of the search or a FAILURE message.

SUCCESS

The Show Optout command does not explicitly return a Success code. Instead, it outputs the email address of the contact in plain text format. Use the output_format argument to return the results in an alternate format.

If there are no results matching the request, nothing is returned.

FAILURE

A Show Optout command will fail for several reasons, such as if the list doesn't exist. The result format is:

FAILURE: [Reason]

Arguments

The Show Optouts command supports the following arguments:

Name	Req?	Description	Argument
Command	Yes	Defines the command to use.	cmd=show_opt c=show_optout
Realm	Yes	Name of the realm to run the command. This is required, and the command will fail if the realm and password do not match.	realm=[realm_name] r=[realm_name]
Password	Yes	Authentication code for API access. This is required, and the command will fail if the realm and password do not match.	pwd=[password] p=[password]
List ID	Yes	Identifier for the list opt outs to return.	list_id=[list_id]
Days	Yes	To limit the results, specifiy a number of days to search. For example, to see all optouts in the past year, use the number '365'	days=[number]
Output Format		To specify the format of the list output, use one of two arguments. If no argument is included, the default output is space-delimited plain text string, which may not include all data columns.	csv=1 or output_format=[csv,csv_tab, csv_pipe,xml]
Header		To define the data with a label, use the Header argument. This can only be used in conjunction with the output format, and does not affect XML.	headers=[0,1] DEFAULT==0