Submit a Triggered Send Definition Using the Asynchronous API

This page contains information regarding submitting triggered send definitions using the asynchronous API.

Why Submit a Triggered Send Definition Using the Asynchronous API

By using the asynchronous API, you can assign priorities to your API calls or sequence and schedule them for a later date. The asynchronous API also holds calls in queue until it processes them, meaning that the system doesn’t lose your calls in case of an unplanned outage. The asynchronous nature of the calls also prevents unintentional call replays.

How to Submit a Triggered Send Definition Using the Asynchronous API

Use the sample code below as a model to submit your own triggered send definition call to the asynchronous API:

Sample .NET Code

1//Create a new Subscriber to send the TriggerSend to
2   Subscriber newSub = new Subscriber();
3   newSub.EmailAddress = emailAddress;
4   newSub.SubscriberKey = emailAddress;
5   //Create Subscriber Attributes
6   newSub.Attributes = new Attribute[2];
7   //Attribute 1
8   newSub.Attributes[0] = new Attribute();
9   newSub.Attributes[0].Name = "FromName";
10   newSub.Attributes[0].Value = "From John Doe";
11   //Attribute 2
12   newSub.Attributes[1] = new Attribute();
13   newSub.Attributes[1].Name = "HTML__Content";
14   newSub.Attributes[1].Value = "<b>Sent Asynchronously!</b>";
15   //Create a TriggeredSend that uses an existing TriggeredSendDefinition
16   TriggeredSend ts = new TriggeredSend();
17   ts.TriggeredSendDefinition = new TriggeredSendDefinition();
18   ts.TriggeredSendDefinition.CustomerKey = "ETWSEX_TSD";
19   ts.TriggeredSendDefinition.Priority = "High";//This is another feature
20   //Instantiate the CreateOptions object for the create call of TSD
21   CreateOptions cOptionsTS = new CreateOptions();
22   cOptionsTS.RequestType = RequestType.Asynchronous;
23   cOptionsTS.RequestTypeSpecified = true;
24   cOptionsTS.QueuePriority = Priority.High;
25   cOptionsTS.QueuePrioritySpecified = true;
26   ts.Subscribers = new Subscriber[] { newSub };
27   try
28   {
29      //Create the TriggeredSend
30      string tsRequestID = "";
31      string tsStatus = "";
32      CreateResult[] tsResults = client.Create(cOptionsTS, new APIObject[] { ts }, out tsRequestID, out tsStatus);
33      TriggeredSendCreateResult tsCreateResults = tsResults[0] as TriggeredSendCreateResult;
34      //Check for Error
35      if (tsStatus != "OK") { throw new Exception(); }
36   }
37   catch (Exception exCreate)
38   {
39   }

Sample SOAP Envelope

1<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
2   <s:Header>
3      <o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
4         <o:UsernameToken u:Id="uuid-f4119202-0c6f-4383-9872-4745b39f24f6-1">
5            <o:Username>XXXXX</o:Username>
6            <o:Password>XXXXX</o:Password>
7         </o:UsernameToken>
8      </o:Security>
9   </s:Header>
10   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
11      <CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
12         <Options>
13            <RequestType>Asynchronous</RequestType>
14            <QueuePriority>High</QueuePriority>
15         </Options>
16         <Objects xsi:type="TriggeredSend">
17            <PartnerKey xsi:nil="true"/>
18            <ObjectID xsi:nil="true"/>
19            <TriggeredSendDefinition>
20               <PartnerKey xsi:nil="true"/>
21               <ObjectID xsi:nil="true"/>
22               <CustomerKey>ETWSEX_TSD</CustomerKey>
23            </TriggeredSendDefinition>
24            <Subscribers>
25               <PartnerKey xsi:nil="true"/>
26               <ObjectID xsi:nil="true"/>
27               <EmailAddress>example@example.com</EmailAddress>
28               <SubscriberKey>example@example.comm</SubscriberKey>
29               <Attributes>
30                  <Name>FromName</Name>
31                  <Value>From John Doe</Value>
32               </Attributes>
33               <Attributes>
34                  <Name>HTML__Content</Name>
35                  <Value>&lt;b>Sent Asynchronously!&lt;/b></Value>
36               </Attributes>
37            </Subscribers>
38         </Objects>
39      </CreateRequest>
40   </s:Body>
41</s:Envelope>

Setting the priority on a triggered sendrequires that more functionality be enabled for your account. Contact your Account Executive for more details on this feature and to enable this feature for your account.

How to Retrieve the Status

Use the sample code below as a model to retrieve the status of the triggered send API call:

Sample .NET Code

1//Check the ResultItem
2//Create the filter, passing in the RequestID of the TriggeredSend
3SimpleFilterPart sfp = new SimpleFilterPart();
4sfp.Property = "RequestID";
5sfp.SimpleOperator = SimpleOperators.equals;
6sfp.Value = new string[] { requestID };
7//Create a String Array of Properties to Retreive for the Object
8string[] oProps = new string[] { "RequestType", "ErrorCode", "StatusCode" };
9//Create RetreiveRequest Object
10RetrieveRequest rr = new RetrieveRequest();
11rr.ObjectType = "ResultItem";
12rr.Properties = oProps;
13rr.Filter = sfp;
14//Call the Retrieve Method for the RetrieveRequest Object
15APIObject[] rResults;
16string rStatus = "";
17string rRequestID = "";
18rStatus = client.Retrieve(rr, out rRequestID, out rResults);

Sample SOAP Envelope

1<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
2   <soapenv:Header>
3      <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
4         <wsse:UsernameToken wsu:Id="UsernameToken-24440876" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
5            <wsse:Username>XXXXX</wsse:Username>
6            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">XXXXX</wsse:Password>
7         </wsse:UsernameToken>
8      </wsse:Security>
9   </soapenv:Header>
10   <soapenv:Body>
11      <RetrieveRequestMsg xmlns="http://exacttarget.com/wsdl/partnerAPI">
12         <RetrieveRequest>
13            <ObjectType>ResultItem</ObjectType>
14            <Properties>RequestType</Properties>
15            <Properties>ErrorCode</Properties>
16            <Properties>StatusCode</Properties>
17            <Filter xsi:type="ns1:SimpleFilterPart" xmlns:ns1="http://exacttarget.com/wsdl/partnerAPI">
18               <Property>RequestID</Property>
19               <SimpleOperator>equals</SimpleOperator>
20               <Value>F9168C5E-CEB2-4faa-B6BF-329BF39FA1E4</Value>
21            </Filter>
22         </RetrieveRequest>
23      </RetrieveRequestMsg>
24   </soapenv:Body>
25</soapenv:Envelope>