Using AMPscript with the Web Service API

Arguments

• S1    The API Object receiving the new item in text form

Example

SET @subscriber = CreateObject("Subscriber")

Creates a new Subscriber object for the web service API.

NOTE: an object created with CreateObject() should only be used for one particular API call. So, if a Subscriber object is created and then updated via InvokeUpdate, it cannot be passed to a Triggered Send.

Arguments

• O1    The API object receiving the assigned value
• S1    The name of the property being assigned
• S2    The value of the property being assigned

Example

The following example creates an API object named "Subscriber" and gives it the the "EmailAddress" property with the value of an email address.

SET @subscriber=CreateObject("Subscriber")
SetObjectProperty(@subscriber,"EmailAddress","user@example.com")

The following example creates an API object named "Attribute", gives it a name of "First Name", and sets the value to John.

SET @attribute=CreateObject(Attribute)
SetObjectProperty(@attribute,"Name","First Name")
SetObjectProperty(@attribute,"Value","John")

Arguments

• O1    The API object containing the array
• S1    The array property to which an item is to be added
• S2    The item to be added to the array

Example

Given the example below:

AddObjectArrayItem(@mySubscriber,"Attribute",@myNewAttribute)

The Attributes array on the mySubscriberObject would receive the attribute myNewAttribute.

Arguments

• S1    Row from which to return the field, or object from which to return the attribute
• S2    Name of the field or attribute to return

Example

%%=Field(@row, "City")=%%

The system returns value of the City field in the row specified in the @row variable.

%%=Field(@subscriber, "EmailAddress")=%%

The system returns the EmailAddress value from the @subscriber WSDL object.

Arguments

• O1    The API object to be created
• S1    Output parameter for the API status message
• N1    Output parameter for the API error code
• O2    The CreateOptions API call

Example

Given the example below:

%%[

var @emailaddr
SET @emailaddr = "help@example.com"

   SET @ts = CreateObject("TriggeredSend")
   SET @tsDef = CreateObject("TriggeredSendDefinition")
   SET @ts_subkey = @emailaddr

   SetObjectProperty(@tsDef, "CustomerKey", "VolConfirm")
   SetObjectProperty(@ts, "TriggeredSendDefinition", @tsDef)  

   SET @ts_sub = CreateObject("Subscriber")
   SetObjectProperty(@ts_sub, "EmailAddress", @emailaddr)
   SetObjectProperty(@ts_sub, "SubscriberKey", @ts_subkey)

   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
 
]%%

The AMPscript creates the TriggeredSend and TriggeredSendDefinition objects as @ts and @tsDef. It also assigns the correct properties to the objects and passes the object into the InvokeCreate call. The InvokeCreate call returns a status code and status message by which exception handling can be built. In this example, the AMPscript returns an error to the screen.

Arguments

• P1    Text object for the API object
• P2    StatusMessage - optional text status message
• P3    ErrorCode - optional numeric error code
• P4    Options - optional options in text

Arguments

• O1    The API object to be deleted
• S1    Output parameter for the API status message
• N1    Output parameter for the API error code
• O2    The DeleteOptions API call

Arguments

• P1    The RetrieveRequest object from which you wish to return an array of API objects.
• P2    (Optional) The OverallStatus parameter passes the Status of the retrieve call to a previously defined AMPscript variable.
• P3    (Optional) The RequestID parameter passes the RequestID of the retrieve call to a previously defined AMPscript variable.

Arguments

• O1    The API object to be performed
• S1    The action to be performed - valid parameter values vary depending on object type
• S2    Output parameter that gives the API status message

RaiseError("An Error Occurred")

RaiseError("Do not send to subscriber", true)

SET @subscriber=CreateObject("Subscriber")
SetObjectProperty(@subscriber,"EmailAddress","user@example.com")

SET @attribute=CreateObject(Attribute)
SetObjectProperty(@attribute,"Name","First Name")
SetObjectProperty(@attribute,"Value","John")