Unsubscribe and Log an UnsubEvent with a LogUnsubEvent Execute Call
This page contains information about using the SOAP API to unsubscribe a subscriber.
This call allows you to unsubscribe a subscriber and log an UnsubEvent that is tracked against a specific Job.
Use this call when you create your own landing page or profile center functionality. Previously, you could unsubscribe a subscriber, but you could not create and log the UnsubEvent.
The LogUnsubEvent Execute call uses the following parameters:
- SubscriberID - The Marketing Cloud generated ID that uniquely identifies a subscriber.
- SubscriberKey - The client supplied ID that uniquely identifies a subscriber.
- EmailAddress - The email address of the subscriber.
- JobID - The ID of the Job that sent the message.
- ListID - The ID of the List that the subscriber belonged to. You can use subscriber or publication lists (not suppression lists).
- BatchID - The ID of the Batch within the Job.
- Reason - (Optional) The reason the subscriber is being unsubscribed.
The parameters can be divided into 3 sections:
- Subscriber context
- Job context
- Unsub reason
If you make this call from the parent unit of an Enterprise 2.0 account, ensure that you include the ClientID of the child business account to return information specific to that business unit.
Subscriber Context
The Subscriber Context is defined by the SubscriberID, SubscriberKey and EmailAddress parameters. You must supply at least one of these parameters. If you provide more than one of these parameters, we retrieve the Subscriber using one of the values and validate that the other values match the retrieved Subscriber. If they don't match, an error returns.
If the SubscriberKey permission is turned on and you supply the EmailAddress parameter, you must supply either the SubscriberID or the SubscriberKey.
Job Context
The Job Context is defined by the JobID, ListID and BatchID parameters. These values are used to determine which Job the UnsubEvent is tracked against. The subscriber is also unsubscribed from the List that the Job was sent to. You don't need to supply all three values. The system looks up any missing values using the following rules:
-
If the JobID is supplied, we can lookup a missing ListID and/or BatchID.
-
If the ListID is supplied, we can lookup a missing JobID and/or BatchID.
- If the JobID is missing, we use the most recent JobID that the subscriber was sent to.
- This may not be the Job that the Subscriber is acting upon.
-
If only the BatchID is supplied, we cannot lookup the remaining information and the job context is not defined.
If the job context cannot be established because you did not supply any of these parameters or only supplied the BatchID, the UnsubEvent is not created. The subscriber is also Master Unsubscribed from the system instead of being unsubscribed from a particular list. Remove the ListID to address the All Subscribers list in an account.
Unsub Reason
This is used to specify the reason the subscriber is being unsubscribed from the system. If the reason is not supplied, the default value is used: Unsubscribed via Log Unsub Event Execute call
Applicable error codes for this call range from 400 to 407 inclusive (Subscriber Validation) and 12012.
Sample Code
Sample .NET Code
Sample .NET Code (Including ClientID for Enterprise 2.0 Accounts)
Sample PHP Code
SOAP Messages
Use the SOAP envelopes below as a guide for creating your own code.
SOAP Request
SOAP Response