Start an Email Send Definition

You can use the SOAP API to start an email send definition from your development environment or another system.

Use these code examples to create your own API calls.

.NET Start and Create Code Examples

Use the sample code to set up your call to create and start an email send definition.

1// 1. Create the EmailSendDefinition
2EmailSendDefinition sd = new EmailSendDefinition();
3sd.CustomerKey = "95";
4// 2. Start the Send
5PerformResult[] results = integrationFramework.Perform(new PerformOptions(), "start", new InteractionBaseObject[] { sd }, out status, out message, out requestID);
6// 3. Print out overall results
7System.Text.StringBuilder sb = new System.Text.StringBuilder();
8sb.Append("Perform Send Definition");
9sb.AppendFormat("\nOverall result: {0}.  RequestID: {1}, {2}\n{3}\n{4}\n{5}\nTaskID: {6}", status, requestID, message, results[0].ErrorCode, results[0].StatusCode, results[0].StatusMessage, results[0].Task.ID);
10Console.WriteLine(sb.ToString());

The output of the code includes the results of the send.

1Perform Send Definition Overall result: OK.  RequestID: f111b13f-fea3-42f7-8e48-367cf09ea4cb, OK 0 OK EmailSendDefinition performed TaskID: 10937228

.NET Start Code Example

This code example includes a dynamic From name and email address.

1/**
2* How to start email send definition from account. After perform call is executed system returns JobId.
3*/
4public void startEmailSendDefinition()
5   {
6      EmailSendDefinition definition = new EmailSendDefinition();
7      definition.CustomerKey = "Definition_Key";
8      //By default fromAddress picks from Account object or SenderProfile defined for Classification
9      definition.SenderProfile.FromName = "Dynamic from Name";
10      definition.SenderProfile.FromAddress = "SendTime@example.com";
11      PerformOptions options = new PerformOptions();
12      //Use this client only if object belongs to Sub-Account
13      ClientID clientID = new ClientID();
14      clientID.ID = 12029;
15      clientID.IDSpecified = true;
16      options.Client = clientID;
17      APIObject[] objects = {definition};
18      PerformResult[] result =
19            soapClient.Perform(options, "start", objects, out overallStatus, out overallStatusMessage, out requestID);
20      //Capture JobId from Result object
21   }

The output includes the Job ID.

.NET Start Code Example with a Filter Definition

1using System;
2using System.Collections.Generic;
3using System.Linq;
4using System.Web;
5using System.Web.UI;
6using System.Web.UI.WebControls;
7using ET_API_WFC.ExactTargetWebReference;
8namespace ET_API_WFC
9{
10    public partial class API_CREATE_SEND_DEF : System.Web.UI.Page
11    {
12        protected void Page_Load(object sender, EventArgs e)
13        {
14        }
15        protected void btn_create_send_def_Click(object sender, EventArgs e)
16        {
17            string Username, Password;
18            string requestID, status;
19            Username = "xxxxx";
20            Password = "xxxx";
21            SoapClient client = new ExactTargetWebReference.SoapClient();
22            client.ClientCredentials.UserName.UserName = Username;
23            client.ClientCredentials.UserName.Password = Password;
24                //Create a GUID for ESD
25                string strGUID = System.Guid.NewGuid().ToString();
26                //Create EmailSendDefinition object to refer to current users ESD [Messages > Email > User-Initiated]
27                EmailSendDefinition esd = new EmailSendDefinition();
28                esd.Name = "EmailSendDefinition";
29                esd.CustomerKey = "CustomerKey";
30                esd.Description = "Description";
31                //Create Email object to refer to pre-created email
32                Email em = new Email();
33                em.ID = 12345;//Found via a Retreive or UI
34                em.IDSpecified = true;
35                esd.Email = em;
36                esd.EmailSubject = "ESD Email Subject";
37                //Create SendClassification
38                SendClassification sc = new SendClassification();
39                sc.ObjectID = "123456";
40                //Found via a Retreive
41                esd.SendClassification = sc;
42                esd.IsSendLogging = false;
43                esd.IsSendLoggingSpecified = true;
44                esd.DeduplicateByEmail = true;
45                esd.DeduplicateByEmailSpecified = true;
46                //Set Send Definition List for the Email Send Definition
47                esd.SendDefinitionList = new SendDefinitionList[2];
48                esd.SendDefinitionList[0] = new SendDefinitionList();
49                FilterDefinition fd = new FilterDefinition();
50                fd.ObjectID = "1234567";
51                fd.CustomerKey = "FilterCustomerKey";
52                esd.SendDefinitionList[0].SendDefinitionListType = SendDefinitionListTypeEnum.SourceList;
53                esd.SendDefinitionList[0].SendDefinitionListTypeSpecified = true;
54
55                esd.SendDefinitionList[0].FilterDefinition = fd;
56                esd.SendDefinitionList[0].DataSourceTypeID = DataSourceTypeEnum.FilterDefinition;
57                esd.SendDefinitionList[0].DataSourceTypeIDSpecified = true;
58                esd.SendDefinitionList[1] = new SendDefinitionList();
59                DataExtension ea = new DataExtension();
60                ea.ObjectID = "123456";
61                ea.CustomerKey = "DECustomerKey";
62                esd.SendDefinitionList[1].SendDefinitionListType = SendDefinitionListTypeEnum.ExclusionList;
63                esd.SendDefinitionList[1].SendDefinitionListTypeSpecified = true;
64
65                esd.SendDefinitionList[1].DataSourceTypeID = DataSourceTypeEnum.CustomObject;
66                esd.SendDefinitionList[1].DataSourceTypeIDSpecified = true;
67                esd.SendDefinitionList[1].CustomObjectID = ea.ObjectID;
68                //Create the EmailSendDefinition, it is visible as a user-initiated Email in Marketing Cloud Engagement
69                string cRequestID = "";
70                string cStatus = "";
71                CreateResult[] cResults = client.Create(new CreateOptions(), new APIObject[] { esd }, out cRequestID, out cStatus);
72                PerformResult[] results = client.Perform(new PerformOptions(), "start", new InteractionBaseObject[] { esd }, out status, out message, out requestID);
73                lblStatus.Text = cStatus;
74            }
75        }
76    }

Java (Axis2) Code Example

1private static void PerformESD(PartnerAPIStub stub) {
2   try {
3                  PerformRequestMsgDocument prmd = PerformRequestMsgDocument.Factory.newInstance();
4                  PerformRequestMsg pr = PerformRequestMsg.Factory.newInstance();
5                  com.exacttarget.wsdl.partnerapi.PerformRequestMsgDocument.PerformRequestMsg.Definitions defs = com.exacttarget.wsdl.partnerapi.PerformRequestMsgDocument.PerformRequestMsg.Definitions.Factory.newInstance();
6                  EmailSendDefinition id = EmailSendDefinition.Factory.newInstance();
7                  id.setCustomerKey("ExampleExternalKey");
8                  defs.setDefinitionArray(new EmailSendDefinition[] {id});
9                  pr.setAction("start");
10                  pr.setDefinitions(defs);
11                  prmd.setPerformRequestMsg(pr);
12                  PerformResponseMsgDocument performResponseMsgDoc = stub.Perform(prmd);
13                  PerformResponseMsgDocument.PerformResponseMsg performResponseMsg = performResponseMsgDoc.getPerformResponseMsg();
14                  System.out.println(performResponseMsg.getOverallStatus() + " " +performResponseMsg.getOverallStatusMessage());
15                  System.out.println(performResponseMsgDoc.toString());
16   } catch (RemoteException e) {
17                  e.printStackTrace();
18   } catch (Exception e) {
19                  e.printStackTrace();
20   }
21}

Ruby Code Example

1require 'rubygems'
2gem 'soap4r'
3require 'soap/wsdlDriver'
4require 'soap/header/simplehandler'
5require 'defaultDriver.rb'
6require 'authStub.rb'
7#Async create options
8#options = CreateOptions.new(nil,nil,nil,nil,nil,nil,nil,nil,'Asynchronous')
9options = nil
10customerKey = 'API-Test-1'
11emailSendDef = EmailSendDefinition.new(nil,nil,nil,nil,nil,nil,nil,customerKey,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil)
12apiObj = emailSendDef
13resp = $driver.perform(PerformRequestMsg.new(options,'start',[apiObj]))

SOAP Request Example

1<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
2   <soap:Header>
3      <wsa:Action>Perform</wsa:Action>
4      <wsa:MessageID>urn:uuid:30ffce73-2bdc-422a-b3da-1e71e3f15270</wsa:MessageID>
5      <wsa:ReplyTo>
6         <wsa:Address>http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous</wsa:Address>
7      </wsa:ReplyTo>
8      <wsa:To>https://YOUR_SUBDOMAIN.soap.marketingcloudapis.com/Service.asmx</wsa:To>
9      <wsse:Security soap:mustUnderstand="1">
10         <wsse:UsernameToken wsu:Id="SecurityToken-4c1eed3b-75ee-4d19-8712-731028aaad77">
11            <wsse:Username>username</wsse:Username>
12            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">password</wsse:Password>
13         </wsse:UsernameToken>
14      </wsse:Security>
15   </soap:Header>
16   <soap:Body>
17      <PerformRequestMsg xmlns="http://exacttarget.com/wsdl/partnerAPI">
18         <Action>start</Action>
19         <Definitions>
20            <Definition xsi:type="EmailSendDefinition">
21               <CustomerKey>Definition_Key</CustomerKey>
22               <SenderProfile>
23                  <FromName>FromName</FromName>
24                  <FromAddress>johndoe@example.com</FromAddress>
25               </SenderProfile>
26            </Definition>
27         </Definitions>
28      </PerformRequestMsg>
29   </soap:Body>
30</soap:Envelope>

SOAP Response Example

1<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
2   <soap:Header>
3      <wsa:Action>PerformResponse</wsa:Action>
4      <wsa:MessageID>urn:uuid:5fe18fef-cc88-416c-862d-28013ef1d379</wsa:MessageID>
5      <wsa:RelatesTo>urn:uuid:30ffce73-2bdc-422a-b3da-1e71e3f15270</wsa:RelatesTo>
6      <wsa:To>http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous</wsa:To>
7      <wsse:Security>
8         <wsu:Timestamp wsu:Id="Timestamp-22862e3f-fefa-45db-ba7f-e69d88571df3">
9            <wsu:Created>2010-02-22T20:29:14Z</wsu:Created>
10            <wsu:Expires>2010-02-22T20:34:14Z</wsu:Expires>
11         </wsu:Timestamp>
12      </wsse:Security>
13   </soap:Header>
14   <soap:Body>
15      <PerformResponseMsg xmlns="http://exacttarget.com/wsdl/partnerAPI">
16         <Results>
17            <Result>
18               <StatusCode>OK</StatusCode>
19               <StatusMessage>EmailSendDefinition performed</StatusMessage>
20               <Object xsi:type="EmailSendDefinition">
21                  <ObjectID>fb3f4fff-8a6c-de11-8fc9-00215adef71a</ObjectID>
22                  <CustomerKey>Definition_Key</CustomerKey>
23                  <Name>Definition_Name</Name>
24                  <SenderProfile>
25                     <ObjectID xsi:nil="true"/>
26                     <FromName>FromName</FromName>
27                     <FromAddress>johndoe@example.com</FromAddress>
28                  </SenderProfile>
29               </Object>
30               <Task>
31                  <StatusCode>OK</StatusCode>
32                  <StatusMessage>OK</StatusMessage>
33                 <!-- JobId -->
34                 <ID>12052743</ID>
35                  <InteractionObjectID>49d6e0eb-f01f-df11-9b82-00237dd3560e</InteractionObjectID>
36               </Task>
37            </Result>
38         </Results>
39         <OverallStatus>OK</OverallStatus>
40         <OverallStatusMessage/>
41         <RequestID>6fb20bc4-2772-4681-8ee3-b36445457676</RequestID>
42      </PerformResponseMsg>
43   </soap:Body>
44</soap:Envelope>