CreateObject is used to return a Marketing Cloud webservice API object. It is most commonly used in conjunction with the
SetObjectProperty functions in AMPscript.
A simple use case for using the
CreateObject function is to use the WebServices API on a CloudPage using AMPscript to send a triggered send email. For example, if a customer reaches a preference page, makes an update, and once they land on the “Thank You” page, it triggers a send.
CreateObject(1) 1 = API Object receiving the new item in text form
%%[ SET @ts = CreateObject(“TriggeredSend”) SET @tsDef = CreateObject(“TriggeredSendDefinition”) SET @ts_subkey = @emailaddr SetObjectProperty(@tsDef, “CustomerKey”, “TriggeredSendKey”) SetObjectProperty(@ts, “TriggeredSendDefinition”, @tsDef) SET @ts_sub = CreateObject(“Subscriber”) SetObjectProperty(@ts_sub, “EmailAddress”, @emailaddr) SET @attribute = CreateObject(“Attribute”) SetObjectProperty(@attribute, “Name”, “FirstName”) SetObjectProperty(@attribute, “Value”, @FirstName) AddObjectArrayItem(@ts_sub, “Attributes”, @attribute) AddObjectArrayItem(@ts, “Subscribers”, @ts_sub) SET @ts_statusCode = InvokeCreate(@ts, @ts_statusMsg, @errorCode) IF @ts_statusCode != “OK” THEN RaiseError(@ts_statusMsg, 0, @ts_statusCode, @errorCode) ENDIF ]%%
(No Output. Triggered Email Sent)
CreateObject function is used several times in this example, for the:
- Triggered Send
- Triggered Send Definition
The Triggered Send and Triggered Send Definition go together in Marketing Cloud as they are both needed to deploy a triggered email send. In short, one is the properties that show which email content to use and the other is a sort of envelope around the email with more properties about the actual trigger.
The Subscriber and Attribute go together to create the Attribute object with one column for “First Name” and the value equal to the AMPscript variable of
@FirstName. This is used to connect with the Subscriber object to assign EmailAddress with AMPscript variables that can be defined from the CloudPage. More on the
AddObjectArrayItem function that is used to connect the two objects with the array.
Lastly, I threw in a
RaiseError function in case the status code for the trigger comes back with anything but “OK.”
CreateObject function has many uses within the web services API and used with AMPscript can be a flexible and customizable tool.
Related functions are the
AddObjectArrayItem function and the