API: HTTP Change Email Address
The Change command is a simplified Update, allowing you to change only the email address for an existing Contact.
Arguments
The Change command requires the following arguments: Command, Realm, Password, Existing Email, and New Email.
api_web?r=myrealm&p=mypass&c=change&email=jane@domain.com&email_new=jayne@domain.com
The command is ‘change', the realm is ‘myrealm’ and the password is ‘mypass’. The current email address is 'jane@domain.com' and will be changed to 'jayne@domain.com'.
This command will attempt to find a single contact record with the specified email address and then update it to the new email address. Change will fail if duplicate contacts exist with the same email address and unique first name. To change the email address of a duplicate contact, use the Update command with the Identifier.
The Change command supports the following arguments:
Name | Req? | Description | Argument |
Command | Yes | Defines the command to use. | cmd=change c=change |
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] |
Yes | Current Email address of the Contact to update. | email=[email] | |
New Email | Yes | New email address to store in place of the current Contact Email address. | email_new=[email]
|
Example
Using all commands and arguments (please note the command is wrapped for display purposes only):
api_web?r=myrealm&p=mypass&c=change&email=john@domain.com&email_new=john.smith@domain.com
The contact's email address will be changed from 'john@domain.com' to 'john.smith@domain.com'. No other data will be updated or changed.
Successful results return:
SUCCESS: john@domain.com changed to john.smith@domain.com [subscriber ID 1171)
Customer Key Example
Some systems have the ability to define a unique Customer Key per contact. If your realm has Customer Key enabled, include the customer_key in the Change command. This is used in place of the Update command in Customer Key realms only.
In the following example, the unique contact with the Customer Key '11293' will have the email address changed from 'jane@domain.com' to 'jane.doe@domain.com':
api_web?r=myrealm&p=mypass&c=change&customer_key=11293&email=jane@domain.com&email_new=jane.doe@domain.com
If you need to update the email address for any contact with the same address, exclude customer_key from the command. In the following example, all contacts with the email address 'jane@domain.com' will be updated with the email address 'jane.doe@domain.com'
api_web?r=myrealm&p=mypass&c=change&email=jane@domain.com&email_new=jane.doe@domain.com
Results
The Change command outputs either a SUCCESS or FAILURE message.
SUCCESS
The Change command success message returns the SUCCESS message and includes the email address changes and the contact ID. The result format is:
SUCCESS: [email] changed to [email_new] (subscriber ID [subscriber_id]).
FAILURE
A Change command will fail for several reasons, such as if multiple contacts exist with the same email address. The result format is:
FAILURE: [Reason]