legacy.manage_subscriber

email

The email address of the subscriber

string

132 characters max.

Conditional; email is only required if external_id is not included in the call

jsmith@example.com

external_id

A subscriber's identifier defined within an external system. This ID must be unique across all subscribers.

string

64 characters max.

No

ABC123DEF456

newemail

The email address used if replacing the current email address

string

132 characters max.

No

j_smith@Mapp.com

new_external_id

The external system's identifier for the subscriber that is replacing the current one

string

64 characters max.

No

ABC123DEF456

firstname

The subscriber's first name (64 characters max)

string

No

John

lastname

The subscriber's last name (64 characters max)

string

No

Smith

address

Street address (60 characters max)

string

No

123 Main St.

city

City name (64 characters max)

string

No

San Diego

state

State or province (64 characters max)

string

No

CA

postal_code

Postal code (64 characters max)

string

No

92110

country

Country name or ISO code (64 characters max)

string

No

US

phone_hm

Home phone number (64 characters max)

string

No

619-295-1856

phone_wk

Work phone number (64 characters max)

string

No

619-295-1856

fax

Fax number (64 characters max)

string

No

619-295-1856

email_type

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

• P – plain text

• H – HTML

• N – No preference

string

No

H

welcome_trigger

The value used to trigger a specific welcome message. The custom field specifically used as the Welcome Message Trigger Field is automatically mapped to this element.

string

No

website

doi

Applies only to new subscriber records. Specifies whether to send the new subscriber a standard Opt-in Confirmation email. Only when the message recipient confirms will the record be marked as a subscriber.

• 0 – follow the account default setting for Double Opt-in (default)

• 1 – send the Double Opt-in email regardless of the account's default setting

boolean

No

1

welcomeletter

Applies only to new subscriber records. Specifies whether to send the new subscriber a welcome letter. If <doi>1</doi> is also in the input parameter, the subscriber will receive the Welcome letter after confirming the double opt-in request.

• 0 – do not send a welcome letter (default)

• 1 – send a welcome letter

boolean

No

1

custval NNNN

A custom field that exists within the system where NNNN is the custom field ID to be referenced. To view a list of custom fields and their corresponding ID numbers, log in to the application and navigate to Assets > Manage Custom Fields. Scroll down on the screen to the Custom Fields section to find the custom field name and its corresponding custom field ID.

string, date, or number. If date, must be in the format YYYY-MM-DD. If number, must be either of the following characters: 0-9 . + –

No

Fido

grp

A comma-delimited list of the ID numbers of the static segments to which this subscriber should be added as a member. To view a list of static segments and their corresponding ID numbers, log in to the application and navigate to Segmentation > Manage Static Segments. Scroll down on the screen to the Segments section to find the static segment name and its corresponding segment ID.

string

No

342234,13212,​64533,7788

grpreplace

Specifies whether you want to change any of the subscriber's static segment memberships.

• 0 – do not replace (default)

• 1 – replace the subscriber's existing static segment memberships with the ones specified in the <grp> element. If the <grp> element is empty, then the system will remove this subscriber from all current static segments.

boolean

No

1

grpremove

A comma-delimited list of the ID numbers of the static segments from which this subscriber should be removed. To view a list of static segments and their corresponding ID numbers, log in to the application and navigate to Segmentation > Manage Static Segments. Scroll down on the screen to the Segments section to find the static segment name and its corresponding segment ID.

string

No

342231,13211,​64531,7781

signup_page

The URL of the page where the subscriber signed up

string

No

http://signup.bh.com/​signup.htm

subscriber_ip

The subscriber's IP address

string

No

66.185.166.116

select

The ID of the Refer-A-Friend program to use. To find the Refer-a-Friend program ID, log in to the application and navigate to Subscribers > Refer A Friend > Edit Refer A Friend. Select a specific Refer-a-Friend program and click the [Edit] button. When the screen appears, look in the URL bar of your browser. The program ID will be the last sequence of digits in the URI.

string

No

52927

From the URL https://barnstormer.​buffalobarn.com/​Empower/referafriend/​edit/52927

refer{N}

Up to 10 email addresses can be passed where: <refer1>, <refer2>, <refer3>, etc.

string

No

john_doe@example.com

name{N}

Up to 10 names of referred subscribers. The numerical pattern of the names must correspond to the pattern of the email addresses passed in the <refer{N}> element (see above).

string

Yes if <select> is included in the POST.

John or John Doe

personalized_message{N}

A personal message provided by the referring subscriber that will be included in the refer-a-friend message. The numerical pattern of the message must correspond to the pattern of the email addresses passed in the <refer{N}> element (see above).

string

No

Hey Joe, check out this awesome email list.

ref

The internal contact_id of the referring subscriber. You must set up the Refer a Friend email in your system to send this value using the tag %%ref_id%%. This will be dynamically set when the email is sent.

number

No

11209893

fmid

The internal contact_id of the subscriber who forwarded a message to the subscriber signing up

number

No

84723024

remove

Specifies whether to remove a subscriber contact record from the system.

• 0 – do not remove (default)

• 1 – remove from the system.

This performs a subscriber delete, not simply an opt-out. Contact records that are deleted through the use of this input parameter will be added back to the database as active records when included in files that are imported either via the Legacy.bulk_sync API method call or from directly within the application.

boolean

No

1

optout

Specifies whether to unsubscribe a contact record from receiving further email marketing communications.

• 0 – do not unsubscribe (default)

• 1 – unsubscribe the contact record

boolean

No

1

check_optout

Specifies whether to check if a contact record has previously opted out.

• 0 – do not check if the contact record has previously opted out (default)

• 1 – do check if a contact record has previously opted out. If <check_optout>1</check_optout> is included as an input parameter and the subscriber has previously opted out, the subscriber will not be added back into the system.

number

No

1

message_hash

If <optout>1</optout> is included as an input parameter, this will tie the opt-out to a specific message for reporting purposes. The message_hash can be obtained by using the %%mhash%% substitution tag in any message link. When the email is created and sent, the tag will be populated with the ID number of the actual message.

string

No

4lijfo409fajdj

status

Specifies whether to return error or success text.

• 0 – do not return text (default)

• 1 – return text

boolean

No

1

channel_source

Reserved for future use

string

No

status

A numeric code representing the result of the POST

1

message

A human-readable explanation of the numeric response code

The user has been added

1

The user has been added

1

The user has been sent a Double Opt-in Email

2

The user has been updated

2

The user had been sent a previous Double Opt-in Email and has not confirmed yet. They have been updated and been sent another Double Opt-in Email

3

The user does not exist

3

This does not appear to be a valid email address

3

This subscriber has previously opted out&optout=1

3

Bad CID

3

This email address is on the suppression list

3

The external_id field must be less than 64 characters

3

The subscriber record could not be updated because it could not be uniquely identified.

3

The external_id could not be updated because it already exists.

4

The user has been removed

4

The user was not added, they were previously unsubscribed

200

The user has been updated

Returned when a method call is used to update an existing subscriber record.

200

The user has been removed

Returned when a method call is used to delete an existing subscriber record.

200

The subscriber opted out, but the message hash value provided is invalid, therefore could not be used to track opt-out against this message.

Returned when a method call is used to delete an existing subscriber record, but the message hash is not valid.

201

The user has been added

A new record has been successfully added to the subscriber database.

211

User added, but contact opt-in information not included because of malformed data

A new record added to the subscriber database, but contact opt-in info could not be included (because of extra or unexpected characters).

212

User added, but profile information not included because of malformed data

A new record added to the subscriber database, but contact profile info could not be included (because of extra or unexpected characters).

213

User added, but opt-in and profile information not included because of malformed data

A new record added to the subscriber database, but contact opt-in and profile info could not be included (because of extra or unexpected characters).

214

The user updated, but profile information was not included because of malformed data

The existing subscriber database record has been updated, but profile info could not be included (because of extra or unexpected characters).

220

The user had been sent a previous Double Opt-in Email and has not confirmed yet. They have been updated and been sent another Double Opt-in Email

Returned when a subscriber record is added or updated, and that record is still pending Double Opt-in Email confirmation.

404

The user does not exist

The email address or the external ID provided in the request to update/unsubscribe/delete a contact record does not exist in the subscriber database.

420

Invalid Email Address

421

This subscriber has previously opted out&optout=1

Attempt to create a new contact record or update a record using an email address that has previously opted out.

423

This email address is on the suppression list

Attempt to create a new contact record or update a record using an email address that is listed in the global suppression list.

424

The external_id field must be less than 64 characters

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

425

The subscriber record could not be updated because it could not be uniquely identified

Returned when the External ID feature is enabled for your account, and the request included an email address that appears multiple times in the subscriber database, and there is no other information provided to uniquely identify the contact record.

426

The external_id could not be updated because it already exists

The value provided in the <new_external_id> element already exists.

427

The user was not added, they were previously unsubscribed

An attempt to create a new subscriber record using an email address that has already been unsubscribed.

428

The new email provided already exists.

The email address provided in the element already belongs to another subscriber.

429

The user was not added, firstname/lastname contains CRLF.

New users could not be added to the database due to unexpected characters (either CRLF or LF) included in the First Name or Last Name fields.