legacy.retrieve_active

email

Email address to retrieve data on a single subscriber. Omit this element, the <external_id> element, and the <contact_id> element to retrieve data on all subscribers matching other criteria. The percentage symbol (%) may be used as a wildcard.

string

Conditional; required only if no other selection criteria are provided in the POST message.

jsmith@​example.com or %@example.com

return_count

Specifies whether the response will only include a count of active subscribers where:

• 0 – include subscriber data specified (default)

• 1 – return just a count of active subscribers matching the selection criteria

boolean

No

1

external_id

An identifier defined within an external system used to retrieve data on a single subscriber. Omit this element, the <email> element, and the <contact_id> element to retrieve data on all subscribers matching other criteria. The percentage symbol (%) may be used as a wildcard. If this element is included with the <email> element, then the search for the subscriber record will be based on both the external_id and the email address.

string

64 characters max

No

ABC123DEF456

contact_id

The contact ID (Mapp's internal ID for a subscriber record) to retrieve data on a single subscriber. Searching a subscriber record by contact_id cannot be paired with any other input parameter (e.g. email). If the <contact_id> element is included in the input, then the search will be done by contact ID and any other input parameter will be ignored. Omit this element, the <email> element, and the <external_id> element to retrieve data on all subscribers matching other criteria.

Number

No

12345678

firstname

The first name on which to base result search

string

No

John

lastname

Last name on which to base the result search

string

No

Smith

date_search_type

No longer used; is replaced by <date_joined_on>, <date_joined_start> and <date_joined_end>.

string

N/A

N/A

city

City name

string

No

Miami

state

State or province

string

No

FL

postal_code

Postal code

string

No

92110

country

Country name or ISO code

string

No

US

phone_hm

Home phone number

string

No

619-295-1856

phone_wk

Work phone number

string

No

619-295-1856

fax

Fax number

string

No

619-295-1856

date_modified_on

(Formerly known as <date_modified>) Date when the subscribers' profiles were last modified. The date must be in YYYY-MM-DD format. If <date_modified_on> is provided along with <date_modified_start> and <date_modified_end> then subscribers are selected solely upon <date_modified_on>.

date

No

2010-06-05

date_modified_start

Starting date range for selecting records by subscriber record last modified date.

The date must be in YYYY-MM-DD format.

date

No

2013-01-01

date_modified_end

Ending date range for selecting records by subscriber record last modified date.

The date must be in YYYY-MM-DD format.

date

No

2013-05-17

date_joined_on

(Formerly known as <optin_date>) The date when the subscribers were added to the database. The date must be in YYYY-MM-DD format. If <date_joined_on> is provided along with <date_joined_start> and <date_joined_end> then subscribers are selected solely upon <date_joined_on>.

string

No

2010-01-31

date_joined_start

The date range for selecting records by subscriber opt-in date starting on the date provided.

The date must be in YYYY-MM-DD format.

date

No

2013-01-05

date_joined_end

The date range for selecting records by subscriber opt-in date ending on the date provided.

The date must be in YYYY-MM-DD format.

date

No

2013-05-17

bounced

No longer used; is replaced by <bounce_status>. A boolean value that when set to '1' indicates finding subscribers that have not received an email because it "bounced"

number

No

1

bounce_status

When provided, will return only records with either valid or invalid bounce status. The valid bounce status types are:

• valid

• invalid

string

No

valid

invalid

No longer used; is replaced by <bounce_status>. A boolean value that when set to '1' indicates finding subscribers classified as "invalid"

number

No

1

valid

No longer used; is replaced by <bounce_status>. A boolean value that when set to '1' indicates finding subscribers in which emails sent to them have bounced less than three times over the lifetime of their subscriber records.

number

No

1

max

(Formerly known as <limit_rows>) An integer value that limits the number of subscribers returned in the response message

number

Conditional; required if <offset> is included in the POSTed message.

100000

offset

(Formerly known as <limit_offset>) An integer value that starts the return of subscribers after X number of records. Include <max> to specify a limited set of results.

number

No

2500

order

Set to either "desc" or "asc" to order the subscribers by a certain field as defined in the <orderby> element

string

No

asc

orderby

Set to "email" for email (the default), "firstname" for first name, "lastname" for last name, or "edate" for the date the record was added to the subscriber database

string

No

edate

custval{integer}={value}

Requests subscribers whose specified custom field equals the specified value where {integer} is the custom field ID to be referenced and {value} is either the string or date value that is stored in this custom field. To view a list of custom fields and their corresponding ID numbers, log in to the application and navigate to Administration > Configure Settings > Account and Segment IDs. Scroll down on the screen to the Custom Fields section to find the custom field name and its corresponding custom field ID.

string or date. If date, it must be in the format YYYY-MM-DD

No

custval8439=fido

groups

Requests subscribers that belong to the specified static segments. The value of this element is a comma-delimited list of the ID numbers of the static segments to which the subscribers belong. To view a list of static segments and their corresponding ID numbers, log in to the application and navigate to Administration > Configure Settings > Account and Segment IDs. Scroll down on the screen to the Segments section to find the static segment name and its corresponding segment ID.

string

No

194832,92439

grp_search_type

Parameter options include:

• any – Match subscribers who are in any of the static segments specified within the <groups> field (default)

• all – Match subscribers who are in all of the specified segments

• notany- Match subscribers who are not in any of the specified segments

• notall – Match subscribers who are not in all of the specified segments

string

No

all

asynchronous

Specifies to enable returning of the resource to operate in an asynchronous mode where:

• 0 – operate in synchronous mode, returning the resource in real-time (default)

• 1 – operate in asynchronous mode

boolean'

No

1

mess_id_sent

Returns all subscribers sent the specified message. This single parameter replaces the <m_id> and <m_sent> combination.Cannot be combined in the same request with the <mess_id_opened>, <mess_id_delivered>, and <mess_id_bounced> input fields.

number

No

95009

mess_id_delivered

Returns all subscribers that the specified message was successfully delivered. This single parameter replaces the <m_id> and <m_delivered> combination.Cannot be combined in the same request with the <mess_id_bounced> input field.

number

No

95009

mess_id_opened

Returns all subscribers that opened the specified message.Cannot be combined in the same request as the <mess_id_delivered> and <mess_id_bounced> input fields.

number

No

95009

mess_id_bounced

Returns all subscribers that the specified message bounced when sent. This single parameter replaces the <m_id> and <m_bounced> combination.Cannot be combined in the same request as the <mess_id_delivered> input field.

number

No

95009

m_id

No longer used. Is replaced by stand alone parameters for <mess_id_opened>, <mess_id_sent>, < mess_id_delivered>, and <mess_id_bounced>. This value is a message ID. This is identified as the 'id' attribute in the message element (<message id="162224″>) that can be found in the legacy.message_stats method response. When used by itself it will return subscribers who opened the message.

number

No

12309

m_sent

No longer used. Is replaced by stand alone parameters for <mess_id_opened>, <mess_id_sent>, < mess_id_delivered>, and <mess_id_bounced>. A boolean value that when set to 1 and paired with an m_id value, requests all subscribers sent the message identified by <m_id>.

number

No

1

m_delivered

No longer used. Is replaced by stand alone parameters for <mess_id_opened>, <mess_id_sent>, < mess_id_delivered>, and <mess_id_bounced>. A boolean value that when set to 1 and paired with an m_id value, requests all subscribers sent the message identified by m_id that was delivered (did not bounce)

number

No

1

m_bounced

No longer used. Is replaced by stand alone parameters for <mess_id_opened>, <mess_id_sent>, < mess_id_delivered>, and <mess_id_bounced>. A boolean value that when set to 1 and paired with an m_id value, requests all subscribers sent the message identified by m_id that bounced.

number

No

1

link_id_clicked

(Formerly known as <t_id>) Requests all subscribers who have clicked on the given link. This value is a message link ID. It is identified as the 'id'

attribute in the link element (<link id="133710″>) that can be found

in the legacy.message_stats method response.

number

No

133710

roi_id

Requests all subscribers who have purchase data associated with the given link. This value is a message link ID (the same value as the above t_id). This is identified as the 'id' attribute in the link element (<link id="133710″>) that can be found in the legacy.message_stats method response.

number

No

133710

basic

Specifies that only basic contact information in the response which includes first name, last name, email, number of times emails sent to the subscriber have bounced, and opt-in date in YYYY-MM-DD format where:

• 0 – do not specify basic contact info (default)

• 1 – include only basic contact information

boolean

No

1

extended

Specifies that extended contact information in the response which includes address, city, state, zip code, home phone, work phone, fax, country, and last modified date in YYYY-MM-DD where:

• 0 – do not specify extended contact info (default)

• 1 – include extended contact info

boolean

No

1

return_groups

Specifies whether to include a comma-delimited list of static segment IDs to which each subscriber belongs where:

• 0 – do not include (default)

• 1 – include

boolean

No

1

custom_fields

Specifies whether to include all custom field data to be included in the response message where:

• 0 – do not include (default)

• 1 – include

boolean

No

1

manifest

This element is the "wrapper" for all subscriber response data elements

count

The total number of active subscribers matching the search criteria POSTed in the input parameters. This element will only be returned if the <return_count> element is set to '1' in the input.

230239

contact_data

This element is the "wrapper" for individual subscriber response data elements

email

The subscriber's email address

jsmith@example.com

external_id

The subscriber's identifier defined within an external system.

This element will be included in the response only if the External ID feature is enabled for your account.

ABC123DEF456

firstname

First name

John

lastname

Last name

Smith

email_preference

A one-letter code defining the subscriber's email preference as:

• P – plain text

• H – HTML

• N – No preference

times_bounced

An integer indicating the number of times emails sent to the subscriber bounced

1

timezone

The subscriber's preferred time zone

contact_id

The unique ID assigned to the subscriber in the Empower Enterprise database

13350980

optin_date

A date in YYYY-MM-DD format indicating the date that the subscriber first opted in

address

Address

city

City

state

State or Province

postal_code

Postal code

country

Country

phone_wk

Work phone

phone_hm

Home phone

fax

Fax number

date_modified

A date in YYYY-MM-DD HH:Min:SS format indicating the date that the subscriber's record was last modified

groups_subscribed

This element is the "wrapper" for all <group_id> elements. This element will be included in the response when the <return_groups> element is set to '1' in the POSTed XML message.

group_id

The ID number of the static segment to which the subscriber belongs. To view a list of static segments and their corresponding ID numbers, log in to the application and navigate to Administration > Configure Settings > Account and Segment IDs. Scroll down on the screen to the Segments section to find the static segment name and its corresponding segment ID.

custom_field_data

This element is the "wrapper" for all individual <custom_field_{name/id/value}> data. This element will be included in the response when the <custom_fields> element is set to '1' in the POSTed XML message.

custom_field_name

The name of a custom field

Pet Name

custom_field_id

The custom field ID. To view a list of custom fields and their corresponding ID numbers, log in to the application and navigate to Administration > Configure Settings > Account and Segment IDs. Scroll down on the screen to the Custom Fields section to find the custom field name and its corresponding custom field ID.

4816

custom_field_value

The value of the custom field

Mr. Snuggles

task_id

This element will be included in the response when the input element <asynchronous> is set to '1'.

123456

201

Successfully retrieved active subscribers' data

Successfully retrieved active subscribers' data.

420

email filter specified is empty

The wildcard search provided in the <email> element did not return any results.

424

The external_id field must be less than 64 characters

The value provided in the <external_id> element exceeds the 64-character limit

428

The contact_id field does not support wildcard search

The value provided in the <contact_id> must be a numerical value without any wildcard characters

429

mess_id_opened, mess_id_delivered, and mess_id_bounced can not be combined with mess_id_sent

Invalid combination of elements provided in the input.

430

mess_id_delivered, and mess_id_bounced can not be combined with mess_id_opened

Invalid combination of elements provided in the input.

431

mess_id_bounced can not be combined with mess_id_delivered

Invalid combination of elements provided in the input.

451

date_modified_on must be in YYYY-MM-DD format.

Invalid data format provided in the input.

452

date_modified_start must be in YYYY-MM-DD format.

Invalid data format provided in the input.

453

date_modified_end must be in YYYY-MM-DD format.

Invalid data format provided in the input.

454

date_modified_start must be earlier than date_modified_end.

Invalid combination of elements provided in the input.

455

date_joined_on must be in YYYY-MM-DD format.

Invalid data format provided in the input.

456

date_joined_start must be in YYYY-MM-DD format.

Invalid data format provided in the input.

457

date_joined_end must be in YYYY-MM-DD format.

Invalid data format provided in the input.

458

date_joined_start must be earlier than date_modified_end.

Invalid combination of elements provided in the input.

459

mess_id_sent must be a whole number.

Invalid data format provided in the input.

460

mess_id_opened must be a whole number.

Invalid data format provided in the input.

461

mess_id_delivered must be a whole number.

Invalid data format provided in the input.

462

mess_id_bounced must be a whole number.

Invalid data format provided in the input.