Create, Perform, and Delete Email Send Definitions

You can use email send definitions to send emails using SOAP API. Email send definitions are known as email message interactions. This helps you maintain a integration between your external system or development environment and Marketing Cloud Engagement.

How to Create, Perform, and Delete Email Send Definitions 

Use the sample code below as a model for creating your own API calls related to email send definitions.

When you update a user-initiated send definition via the SOAP API with the Email object, you must set the EmailSubject property on the email send definition. If you don’t pass the new subject to the email send definition, it retains the old subject for that definition.

Sample .NET Code - Create Email Send Definition 

 
1//Create a GUID for ESD
2        string strGUID = System.Guid.NewGuid().ToString();
3        //Create EmailSendDefinition object to refer to current users ESD [Messages > Email > User-Initiated]
4        EmailSendDefinition esd = new EmailSendDefinition();
5        esd.Name = "ESD_Name_" + strGUID;
6        esd.CustomerKey = strGUID;
7        esd.Description = "ESD_Desc_" + strGUID;
8
9        //Create Email object to refer to pre-created email
10        Email em = new Email();
11        em.ID = 542894;//Found via a Retreive or UI
12        em.IDSpecified = true;
13        esd.Email = em;
14        esd.EmailSubject = "ESD Email Subject";
15        //Create SendClassification
16        SendClassification sc = new SendClassification();
17        sc.ObjectID = "51422ad6-6f65-de11-bf42-001e0bbb7678";
18        //Found via a Retreive
19        esd.SendClassification = sc;
20        //Pass the ID of the Content via this property
21        esd.Additional = "01c59e4f-dac8-4dcb-ab99-a00f565bcc00";
22        //DataExtension to Send to
23        DataExtension de = new DataExtension();
24        de.ObjectID = "729860f8-7d66-de11-bf42-001e0bbb7678";//This can be obtained via a Retrieve (Named Send_DE)
25        //Set Send Definition List for the Email Send Definition
26        esd.SendDefinitionList = new SendDefinitionList[1];
27        esd.SendDefinitionList[0] = new SendDefinitionList();
28        esd.SendDefinitionList[0].Name = "SDL Name";
29        esd.SendDefinitionList[0].CustomerKey = "SDL CustomerKey";
30        esd.SendDefinitionList[0].SendDefinitionListType = SendDefinitionListTypeEnum.SourceList;
31        esd.SendDefinitionList[0].SendDefinitionListTypeSpecified = true;
32        esd.SendDefinitionList[0].CustomObjectID = de.ObjectID;
33        esd.SendDefinitionList[0].DataSourceTypeID = DataSourceTypeEnum.CustomObject;//This specifies a Data Extension
34        esd.SendDefinitionList[0].DataSourceTypeIDSpecified = true;
35        //Create the EmailSendDefinition. It is visible as a user-initiated Email in Marketing Cloud Engagement.
36        string cRequestID = "";
37        string cStatus = "";
38        CreateResult[] cResults = client.Create(new CreateOptions(), new APIObject[] { esd }, out cRequestID, out cStatus);
1using System;
2using System.Configuration;
3using System.Data;
4using System.Linq;
5using System.Web;
6using System.Web.Security;
7using System.Web.UI;
8using System.Web.UI.HtmlControls;
9using System.Web.UI.WebControls;
10using System.Web.UI.WebControls.WebParts;
11using System.Xml.Linq;
12using etAPI;
13public partial class EmailSendDefinitionCreate : System.Web.UI.Page
14{
15    //Global Variables
16    private SoapClient client = new SoapClient();
17    protected void Page_Load(object sender, EventArgs e)
18    {
19        //Authenticate
20        client.ClientCredentials.UserName.UserName = System.Configuration.ConfigurationSettings.AppSettings["wsUserName"];
21        client.ClientCredentials.UserName.Password = System.Configuration.ConfigurationSettings.AppSettings["wsPassword"];
22        if (!IsPostBack)
23        {
24        }
25    }
26    protected void btnSubmit_Click(object sender, EventArgs e)
27    {
28        try
29        {
30            //Create a GUID for ESD to ensure a unique name and customer key
31            string strGUID = System.Guid.NewGuid().ToString();
32            //Create EmailSendDefinition object [Messages > Email > User-Initiated]
33            EmailSendDefinition esd = new EmailSendDefinition();
34            esd.Name = "ESD_Name_" + strGUID;//required
35            esd.CustomerKey = strGUID;//required
36            esd.TestEmailAddr = "bjennings@exacttarget.com";
37            //Create Email object to refer to pre-create Email
38            Email em = new Email();
39            em.ID = 542894;//required //Available at Content > My Emails > Properties
40            em.IDSpecified = true;//required
41            //Apply Email object to the EmailSendDefiniton object
42            esd.Email = em;//required
43            //Create SendClassification
44            SendClassification sc = new SendClassification();
45            sc.ObjectID = "51422ad6-6f65-de11-bf42-001e0bbb7678";//required
46            esd.SendClassification = sc;//required
47            //The Additional property is OPTIONAL
48            esd.Additional = "AdditionalInformationVariable";//A Great way to pass values from your API call to the Email, this is available via AMP Script to the Email
49
50            //DataExtension object to be passed into SendDefinitionList's CustomObjectID property
51            DataExtension de = new DataExtension();
52            de.ObjectID = "729860f8-7d66-de11-bf42-001e0bbb7678";//required //This can be obtained via a Retrieve filtered by the External Key of the Data Extension
53            //Set Send Definition List for the EmailSendDefinition
54            esd.SendDefinitionList = new SendDefinitionList[1];//You can have many SendDefinitonLists of different SendDefinitionListTypes
55            esd.SendDefinitionList[0] = new SendDefinitionList();
56            esd.SendDefinitionList[0].SendDefinitionListType = SendDefinitionListTypeEnum.SourceList;
57            esd.SendDefinitionList[0].SendDefinitionListTypeSpecified = true;
58            esd.SendDefinitionList[0].CustomObjectID = de.ObjectID;
59            esd.SendDefinitionList[0].DataSourceTypeID = DataSourceTypeEnum.CustomObject;//This specifies a Data Extension
60            esd.SendDefinitionList[0].DataSourceTypeIDSpecified = true;
61            try
62            {
63                string cRequestID = String.Empty;
64                string cStatus = String.Empty;
65                //Call the Create method on the Subscriber object
66                CreateResult[] cResults = client.Create(new CreateOptions(), new APIObject[] { esd }, out cRequestID, out cStatus);
67                //Display Results
68                lblMessage.Text += "Overall Status: " + cStatus;
69                lblMessage.Text += "<br/>";
70                lblMessage.Text += "Number of Results: " + cResults.Length;
71                lblMessage.Text += "<br/>";
72                //Loop through each object returned and display the StatusMessage
73                foreach (CreateResult cr in cResults)
74                {
75                    lblMessage.Text += "Status Message: " + cr.StatusMessage;
76                    lblMessage.Text += "<br/>";
77                }
78            }
79            catch (Exception exCreate)
80            {
81                //Set Message
82                lblMessage.Text += "<br/><br/>CREATE ERROR:<br/>" + exCreate.Message;
83            }
84        }
85        catch (Exception exc)
86        {
87            //Set Message
88            lblMessage.Text += "<br/><br/>###ERROR<br/>" + exc.Message;
89        }
90    }
91}

Sample .NET Code - Perform an Email Send Definition 

 
1using System;
2using System.Configuration;
3using System.Data;
4using System.Linq;
5using System.Web;
6using System.Web.Security;
7using System.Web.UI;
8using System.Web.UI.HtmlControls;
9using System.Web.UI.WebControls;
10using System.Web.UI.WebControls.WebParts;
11using System.Xml.Linq;
12using etAPI;
13public partial class EmailSendDefinitionPerform : System.Web.UI.Page
14{
15    //Global Variables
16    private SoapClient client = new SoapClient();
17    protected void Page_Load(object sender, EventArgs e)
18    {
19        //Authenticate
20        client.ClientCredentials.UserName.UserName = System.Configuration.ConfigurationSettings.AppSettings["wsUserName"];
21        client.ClientCredentials.UserName.Password = System.Configuration.ConfigurationSettings.AppSettings["wsPassword"];
22        if (!IsPostBack)
23        {
24        }
25    }
26    protected void btnSubmit_Click(object sender, EventArgs e)
27    {
28        try
29        {
30            //Create EmailSendDefinition object [Messages > Email > User-Initiated]
31            EmailSendDefinition esd = new EmailSendDefinition();
32            esd.CustomerKey = "359866e9-1ec1-4854-ba49-c50a0ca61dd5";//required //Called External Key in the UI
33            try
34            {
35                //Perform the ESD
36                string pStatus = String.Empty;
37                string pMessage = String.Empty;
38                string pRequestID = String.Empty;
39                PerformResult[] pResults = client.Perform(new PerformOptions(), "start", new InteractionBaseObject[] { esd }, out pStatus, out pMessage, out pRequestID);
40                //Display Results
41                lblMessage.Text += "Overall Status: " + pStatus;
42                lblMessage.Text += "<br/>";
43                lblMessage.Text += "Number of Results: " + pResults.Length;
44                lblMessage.Text += "<br/>";
45                //Loop through each object returned and display the StatusMessage
46                foreach (PerformResult pr in pResults)
47                {
48                    lblMessage.Text += "Status Message: " + pr.StatusMessage;
49                    lblMessage.Text += "<br/>";                }
50                }
51            catch (Exception exCreate)
52            {
53                //Set Message
54                lblMessage.Text += "<br/><br/>CREATE ERROR:<br/>" + exCreate.Message;
55            }
56        }
57        catch (Exception exc)
58        {
59            //Set Message
60            lblMessage.Text += "<br/><br/>ERROR<br/>" + exc.Message;
61        }
62    }
63}

Sample .NET Code - Start an Email Send Definition with API 

 
1/**
2     * Start Email send definiton using perform call. This internally sends email using Data Extensions.
3     * In Response capture Task ID="12345" which is sendID. Use this to
4     * retrieve tracking information.
5     * @throws RemoteException
6     */
7    public void startEmailSendDefinition() throws RemoteException {
8       EmailSendDefinition definition = new EmailSendDefinition();
9        definition.setCustomerKey("Market2Lead_Email_Definition_Key");
10        Soap_PortType stub = init();
11        PerformRequestMsg performRequestMsg = new PerformRequestMsg();
12        performRequestMsg.setOptions(new PerformOptions());
13        performRequestMsg.setAction("start");
14        performRequestMsg.setDefinitions(new EmailSendDefinition[]{definition});
15        //This sends email using User-Initiated-Email-definition.
16        PerformResponseMsg responseMsg = stub.perform(performRequestMsg);
17        System.out.println(responseMsg.getOverallStatus());
18    }

Sample Ruby Code 

 
1require 'rubygems'
2gem 'soap4r'
3require 'soap/wsdlDriver'
4require 'soap/header/simplehandler'
5require 'defaultDriver.rb'
6require 'authStub.rb'
7require 'WSHelpers.rb'
8props = {
9  :object => 'DataExtension',
10  :props => ['Name','Description','CustomerKey','ObjectID']
11}
12filter = {
13  :filterType => 'Simple',
14  :filter => ['CustomerKey','equals','APITestSendDe0']
15}
16de = BuildRetrieve.new
17resp = de.creates(props,filter)
18objID = String.new
19resp.results.each do |result|
20  objID = result.objectID
21end
22#Async create options
23#options = CreateOptions.new(nil,nil,nil,nil,nil,nil,nil,nil,'Asynchronous')
24options = nil
25customerKey = 'API-Test-1'
26desc = customerKey + ' created through the API'
27sendClass = SendClassification.new(nil,nil,nil,nil,nil,nil,nil,189,nil,nil,nil,nil,nil,nil,nil,nil)
28sendProf = SenderProfile.new(nil,nil,nil,nil,nil,nil,nil,352,nil,nil,nil,nil,'NTO Customer Support','acruz@example.com',nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil)
29delProf = DeliveryProfile.new(nil,nil,nil,nil,nil,nil,nil,306,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil)
30email = Email.new(nil,nil,nil,nil,nil,2052608,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil)
31sendDefList = SendDefinitionList.new(nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,nil,objID,'CustomObject',nil,nil,nil,nil,nil)
32emailSendDef = EmailSendDefinition.new(nil,nil,nil,nil,nil,nil,nil,customerKey,nil,nil,customerKey,desc,nil,nil,nil,sendClass,sendProf,nil,nil,delProf,nil,nil,nil,nil,nil,nil,nil,nil,0,0,sendDefList,email,nil,nil,nil,'Thank You for Contacting NTO Customer Support',nil,1,1,nil,nil,nil,nil,1,nil,nil,nil,'acruz@example.com')
33apiObj = emailSendDef
34resp = $driver.create(CreateRequest.new(options,[*apiObj]))

Sample Java Code (Axis 1.4) 

 
1/**
2      * Create User-Intiated-Send-definition using Data Extension
3      */
4    public void testCreateEmailSendDefinition() throws RemoteException {
5        EmailSendDefinition definition = new EmailSendDefinition();
6        Soap_PortType stub = init();
7        definition.setName("Market2Lead_Email_Definition");   //Name
8        //This is Unique identifier for Definition
9        definition.setCustomerKey("Market2Lead_Email_Definition_Key");
10        //RetrieveEmail
11        Email email = retrieveEmail(stub);//Retrieve email
12        definition.setEmail(email); //Associate what email you are going to send
13        // Retrieve sendClassification and attach to Definition
14        definition.setSendClassification(retrieveSendClassifications(stub));
15        SendDefinitionList sendDefinitionList = new SendDefinitionList();
16       //This is objectId of DataExtension, You can retrieve DataExtension and assign value.
17       //1a3e2c14-580e-de11-b30f-001cc494ae9e Captured after creating DataExtension.
18       //Refer this link for Retrieving Data Extension
19        //http://wiki.memberlandingpages.com/API_References/Web_Service_Guide/_Technical_Articles/Retrieving_DataExtension_Object
20        sendDefinitionList.setCustomObjectID("1a3e2c14-580e-de11-b30f-001cc494ae9e");
21        sendDefinitionList.setDataSourceTypeID(DataSourceTypeEnum.CustomObject);
22        definition.setIsMultipart(true);
23        definition.setSendDefinitionList(new SendDefinitionList[]{sendDefinitionList});
24        APIObject[] createObjects = {definition};
25        //Create Request to create EmailDefinition
26        CreateRequest createRequest = new CreateRequest(new   CreateOptions(),reateObjects);
27        CreateResponse createResponse = stub.create(createRequest);
28        System.out.println(createResponse.getOverallStatus());
29    }

Sample Java Code (Axis 1.4) - Retrieve Send Classifications for Email Send Definition 

 
1/**
2         * Retrieve SendClassifications Transactional or Commerical type.
3         * @throws RemoteException
4     */
5   private SendClassification retrieveSendClassifications(Soap_PortType stub) throws RemoteException {
6        String[] props = { "ObjectID", "Name", "Description", "CustomerKey",
7         "SenderProfile.CustomerKey","Client.ID", "Client.PartnerClientKey", "PartnerKey"
8        };
9        RetrieveRequest request = new RetrieveRequest();
10        request.setObjectType("SendClassification");
11        request.setProperties(props);
12        /*
13        ClientID clientID = new ClientID();
14        clientID.setPartnerClientKey("partnerkey_subaccount_2");         ClientID[] clientIDs = {clientID};
15        request.setClientIDs(clientIDs);         */
16        //Default Transactional
17        SimpleFilterPart filterPart = new SimpleFilterPart();         String[] filterValues = {"Default Commercial"};
18        filterPart.setProperty("Name");
19        filterPart.setSimpleOperator(SimpleOperators.equals);
20        filterPart.setValue(filterValues);
21        request.setFilter(filterPart);
22        RetrieveRequestMsg requestMsg = new RetrieveRequestMsg();
23        requestMsg.setRetrieveRequest(request);
24        RetrieveResponseMsg responseMsg = stub.retrieve(requestMsg);
25        SendClassification classification = null;
26        if (responseMsg.getResults() != null && responseMsg.getResults().length > 0){
27            classification = (SendClassification) responseMsg.getResults(0);
28         }
29        return classification;
30    }
31
32     /**
33     * Reteive email from System
34     * @param stub
35     * @return
36     * @throws RemoteException
37     */
38    public Email retrieveEmail(Soap_PortType stub) throws RemoteException {
39        Email email = null;
40        RetrieveRequest request = new RetrieveRequest();
41        request.setObjectType("Email");
42        String[] props = {"ID", "Name", "Subject", "Status", "PartnerKey"};
43        request.setProperties(props);
44        SimpleFilterPart part = new SimpleFilterPart();
45         part.setProperty("Name"); //If Uniquie, or indentify which is unique in    your case
46        part.setSimpleOperator(SimpleOperators.equals);
47        String[] values = {"Market2Lead"};
48        part.setValue(values);
49        request.setFilter(part);
50        RetrieveRequestMsg requestMsg = new RetrieveRequestMsg();
51        requestMsg.setRetrieveRequest(request);
52        RetrieveResponseMsg responseMsg = stub.retrieve(requestMsg);
53        if (responseMsg.getResults() != null && responseMsg.getResults().length > 0){
54            email = (Email) responseMsg.getResults(0);
55        }
56        return email;
57    }

Sample Create SOAP Envelope 

 
1<s:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
2    <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
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-30851894" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
5                <wsse:Username>Username</wsse:Username>
6                <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">Password</wsse:Password>
7            </wsse:UsernameToken>
8        </wsse:Security>
9        <wsa:To>https://YOUR_SUBDOMAIN.soap.marketingcloudapis.com/Service.asmx</wsa:To>
10        <wsa:MessageID>urn:uuid:FAB69169EC56A8F9D51228490514867</wsa:MessageID>
11        <wsa:Action>Retrieve</wsa:Action>
12    </soapenv:Header>
13    <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
14        <CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
15            <Options></Options>
16            <Objects xmlns:q1="http://exacttarget.com/wsdl/partnerAPI" xsi:type="q1:EmailSendDefinition">
17                <q1:ObjectID xsi:nil="true"></q1:ObjectID>
18                <q1:CustomerKey>7dc973cc-e0ab-4aec-9ba8-cf0b739e02dc</q1:CustomerKey>
19                <q1:Name>ESD_Name_7dc973cc-e0ab-4aec-9ba8-cf0b739e02dc</q1:Name>
20                <q1:Description>ESD_Desc_7dc973cc-e0ab-4aec-9ba8-cf0b739e02dc</q1:Description>
21                <q1:SendClassification>
22                    <q1:ObjectID>51422ad6-6f65-de11-bf42-001e0bbb7678</q1:ObjectID>
23                </q1:SendClassification>
24                <q1:SendDefinitionList>
25                    <q1:ObjectID xsi:nil="true"></q1:ObjectID>
26                    <q1:CustomerKey>SDL CustomerKey</q1:CustomerKey>
27                    <q1:SendDefinitionListType>SourceList</q1:SendDefinitionListType>
28                    <q1:CustomObjectID>729860f8-7d66-de11-bf42-001e0bbb7678</q1:CustomObjectID>
29                    <q1:DataSourceTypeID>CustomObject</q1:DataSourceTypeID>
30                    <q1:Name>SDL Name</q1:Name>
31                </q1:SendDefinitionList>
32                <q1:Email>
33                    <q1:ID>542894</q1:ID>
34                    <q1:ObjectID xsi:nil="true"></q1:ObjectID>
35                </q1:Email>
36                <q1:EmailSubject>ESD Email Subject</q1:EmailSubject>
37                <q1:Additional>cb99f3b1-67a4-452a-94c0-886e9a930961</q1:Additional>
38            </Objects>
39        </CreateRequest>
40    </s:Body>
41</s:Envelope>

Sample Perform SOAP Envelope 

 
1<s:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
2    <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
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-30851894" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> <wsse:Username>Username</wsse:Username>
5                <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">Password</wsse:Password>
6            </wsse:UsernameToken>
7        </wsse:Security>
8        <wsa:To>https://YOUR_SUBDOMAIN.soap.marketingcloudapis.com/Service.asmx</wsa:To>
9        <wsa:MessageID>urn:uuid:FAB69169EC56A8F9D51228490514867</wsa:MessageID>
10        <wsa:Action>Retrieve</wsa:Action>
11    </soapenv:Header>
12    <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
13        <PerformRequestMsg xmlns="http://exacttarget.com/wsdl/partnerAPI">
14            <Options></Options>
15            <Action>start</Action>
16            <Definitions>
17                <Definition xmlns:q1="http://exacttarget.com/wsdl/partnerAPI" xsi:type="q1:EmailSendDefinition">
18                    <q1:ObjectID xsi:nil="true"></q1:ObjectID>
19                    <q1:CustomerKey>7dc973cc-e0ab-4aec-9ba8-cf0b739e02dc</q1:CustomerKey>
20                    <q1:Name>ESD_Name_7dc973cc-e0ab-4aec-9ba8-cf0b739e02dc</q1:Name>
21                    <q1:Description>ESD_Desc_7dc973cc-e0ab-4aec-9ba8-cf0b739e02dc</q1:Description>
22                    <q1:SendClassification>
23                        <q1:ObjectID>51422ad6-6f65-de11-bf42-001e0bbb7678</q1:ObjectID>
24                    </q1:SendClassification>
25                    <q1:SendDefinitionList>
26                        <q1:ObjectID xsi:nil="true"></q1:ObjectID>
27                        <q1:CustomerKey>SDL CustomerKey</q1:CustomerKey>
28                        <q1:SendDefinitionListType>SourceList</q1:SendDefinitionListType>
29                        <q1:CustomObjectID>729860f8-7d66-de11-bf42-001e0bbb7678</q1:CustomObjectID>
30                        <q1:DataSourceTypeID>CustomObject</q1:DataSourceTypeID>
31                        <q1:Name>SDL Name</q1:Name>
32                    </q1:SendDefinitionList>
33                    <q1:Email>
34                        <q1:ID>123</q1:ID>
35                        <q1:ObjectID xsi:nil="true"></q1:ObjectID>
36                    </q1:Email>
37                    <q1:EmailSubject>ESD Email Subject</q1:EmailSubject>
38                    <q1:Additional>cb99f3b1-67a4-452a-94c0-886e9a930961</q1:Additional>
39                </Definition>
40            </Definitions>
41        </PerformRequestMsg>
42    </s:Body>
43</s:Envelope>

Sample Delete SOAP Envelope 

 
1<s:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
2    <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
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-30851894" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
5                <wsse:Username>Username</wsse:Username>
6                <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">Password</wsse:Password>
7            </wsse:UsernameToken>
8        </wsse:Security>
9        <wsa:To>https://YOUR_SUBDOMAIN.soap.marketingcloudapis.com/Service.asmx</wsa:To>
10        <wsa:MessageID>urn:uuid:FAB69169EC56A8F9D51228490514867</wsa:MessageID>
11        <wsa:Action>Retrieve</wsa:Action>
12    </soapenv:Header>
13    <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
14        <DeleteRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
15            <Options></Options>
16            <Objects xmlns:q1="http://exacttarget.com/wsdl/partnerAPI" xsi:type="q1:EmailSendDefinition">
17                <q1:ObjectID xsi:nil="true"></q1:ObjectID>
18                <q1:CustomerKey>7dc973cc-e0ab-4aec-9ba8-cf0b739e02dc</q1:CustomerKey>
19                <q1:Name>ESD_Name_7dc973cc-e0ab-4aec-9ba8-cf0b739e02dc</q1:Name>
20                <q1:Description>ESD_Desc_7dc973cc-e0ab-4aec-9ba8-cf0b739e02dc</q1:Description>
21                <q1:SendClassification>
22                    <q1:ObjectID>51422ad6-6f65-de11-bf42-001e0bbb7678</q1:ObjectID>
23                </q1:SendClassification>
24                <q1:SendDefinitionList>
25                    <q1:ObjectID xsi:nil="true"></q1:ObjectID>
26                    <q1:CustomerKey>SDL CustomerKey</q1:CustomerKey>
27                    <q1:SendDefinitionListType>SourceList</q1:SendDefinitionListType>
28                    <q1:CustomObjectID>729860f8-7d66-de11-bf42-001e0bbb7678</q1:CustomObjectID>
29                    <q1:DataSourceTypeID>CustomObject</q1:DataSourceTypeID>
30                    <q1:Name>SDL Name</q1:Name>
31                </q1:SendDefinitionList>
32                <q1:Email>
33                    <q1:ID>542894</q1:ID>
34                    <q1:ObjectID xsi:nil="true"></q1:ObjectID>
35                </q1:Email>
36                <q1:EmailSubject>ESD Email Subject</q1:EmailSubject>
37                <q1:Additional>cb99f3b1-67a4-452a-94c0-886e9a930961</q1:Additional>
38            </Objects>
39        </DeleteRequest>
40    </s:Body>
41</s:Envelope>

SOAP Request to Create an Email Send Definition 

 
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-9560865" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">             <wsse:Username>username</wsse:Username>
5            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">password</wsse:Password>          </wsse:UsernameToken>       </wsse:Security>    </soapenv:Header>    <soapenv:Body>
6      <CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
7         <Options/>
8         <Objects xsi:type="ns1:EmailSendDefinition" xmlns:ns1="http://exacttarget.com/wsdl/partnerAPI">
9            <CustomerKey>Market2Lead_Email_Definition_Key</CustomerKey>
10            <Name>Market2Lead_Email_Definition</Name>
11            <SendClassification>
12               <Client>
13                  <ID>75741</ID>
14               </Client>
15               <ObjectID>4819efef-4527-dd11-8126-001a4be9433a</ObjectID>
16               <CustomerKey>3542</CustomerKey>
17               <Name>Default Commercial</Name>
18               <Description>Default Commercial Send Classification</Description>
19               <SenderProfile>
20                  <CustomerKey>1973</CustomerKey>
21               </SenderProfile>
22            </SendClassification>
23            <SendDefinitionList>
24               <CustomObjectID>1a3e2c14-580e-de11-b30f-001cc494ae9e</CustomObjectID>
25               <DataSourceTypeID>CustomObject</DataSourceTypeID>
26            </SendDefinitionList>
27            <Email>
28               <ID>794527</ID>
29               <Name>Market2Lead</Name>
30               <Subject>Market2Lead-Email</Subject>
31               <Status>New</Status>
32            </Email>
33            <IsMultipart>true</IsMultipart>
34         </Objects>
35      </CreateRequest>
36   </soapenv:Body>
37</soapenv:Envelope>

SOAP Response to Request to Create an Email Send Definition 

 
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>CreateResponse</wsa:Action>
4      <wsa:MessageID>urn:uuid:107dc09d-fdff-408e-af80-373012788c53</wsa:MessageID>
5      <wsa:RelatesTo>urn:uuid:02be8551-f51a-45c2-a298-2cfbd23fe715</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-e41f7772-de26-4ef4-9aec-950e013c39e6">
9            <wsu:Created>2009-03-11T18:51:24Z</wsu:Created>
10            <wsu:Expires>2009-03-11T18:56:24Z</wsu:Expires>
11         </wsu:Timestamp>
12      </wsse:Security>
13   </soap:Header>
14   <soap:Body>
15      <CreateResponse xmlns="http://exacttarget.com/wsdl/partnerAPI">
16         <Results>
17            <StatusCode>OK</StatusCode>
18            <StatusMessage>ImportDefinition created.</StatusMessage>
19            <OrdinalID>0</OrdinalID>
20            <NewID>0</NewID>
21            <NewObjectID>4da7bd99-6d0e-de11-b30f-001cc494ae9e</NewObjectID>
22            <Object xsi:type="ImportDefinition">
23               <ObjectID>4da7bd99-6d0e-de11-b30f-001cc494ae9e</ObjectID>
24               <CustomerKey>Import_To_DE_Market2Lead_Key</CustomerKey>
25               <Name>Import_To_DE_Market2Lead</Name>
26               <Description>Import_To_DE_Market2Lead</Description>
27               <AllowErrors>true</AllowErrors>
28               <DestinationObject xsi:type="DataExtension">
29                  <ObjectID xsi:nil="true"/>
30                  <CustomerKey>UsingAPI_For_Market2Lead_Key</CustomerKey>
31               </DestinationObject>
32               <FieldMappingType>InferFromColumnHeadings</FieldMappingType>
33               <FieldMaps>
34                  <FieldMap>
35                     <DestinationName>EmailAddress</DestinationName>
36                  </FieldMap>
37                  <FieldMap>
38                     <DestinationName>ChannelUser</DestinationName>
39                  </FieldMap>
40                  <FieldMap>
41                     <DestinationName>ChannelUser_EmailAddress</DestinationName>
42                  </FieldMap>
43                  <FieldMap>
44                     <DestinationName>Demographic_Address</DestinationName>
45                  </FieldMap>
46               </FieldMaps>
47               <FileSpec>Import2M2L.csv</FileSpec>
48               <FileType>CSV</FileType>
49               <Notification>
50                  <ResponseType>email</ResponseType>
51                  <ResponseAddress>response@exacttarget.com</ResponseAddress>
52               </Notification>
53               <RetrieveFileTransferLocation>
54                  <ObjectID xsi:nil="true"/>
55                  <CustomerKey>ExactTarget Enhanced FTP</CustomerKey>
56               </RetrieveFileTransferLocation>
57               <UpdateType>AddAndDoNotUpdate</UpdateType>
58            </Object>
59         </Results>
60         <RequestID>a491e5d7-6388-4e19-afb8-506d4136542a</RequestID>
61         <OverallStatus>OK</OverallStatus>
62      </CreateResponse>
63   </soap:Body>
64</soap:Envelope>

SOAP Envelope to Create an Email Send Definition Using Profile Attributes and a Data Filter to Create an Audience 

 
1<?xml version="1.0" encoding="UTF-8"?>
2<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
3<SOAP-ENV:Header>
4  <wsse:Security 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">
5   <wsu:Timestamp>
6    <wsu:Created>2011-05-20T21:24:16Z</wsu:Created>
7    <wsu:Expires>2011-05-20T21:29:16Z</wsu:Expires>
8   </wsu:Timestamp>
9   <wsse:UsernameToken>
10    <wsse:Username>XXXXX</wsse:Username>
11    <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">XXXXX</wsse:Password>
12    <wsse:Nonce>CvdDChr6jtfX++xFZVEoCAm6TXQ=</wsse:Nonce>
13    <wsu:Created>2011-05-20T21:24:16Z</wsu:Created>
14   </wsse:UsernameToken>
15  </wsse:Security>
16</SOAP-ENV:Header>
17<SOAP-ENV:Body>
18  <CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
19   <Options/>
20   <ns1:Objects xmlns:ns1="http://exacttarget.com/wsdl/partnerAPI" xsi:type="ns1:EmailSendDefinition">
21    <ns1:ModifiedDate xsi:nil="true"/>
22    <ns1:ObjectID xsi:nil="true"/>
23    <ns1:Name>12345</ns1:Name>
24    <ns1:SendClassification>
25     <ns1:ModifiedDate xsi:nil="true"/>
26     <ns1:CustomerKey>12345</ns1:CustomerKey>
27    </ns1:SendClassification>
28    <ns1:SendDefinitionList>
29     <ns1:ModifiedDate xsi:nil="true"/>
30     <ns1:List>
31      <ns1:ModifiedDate xsi:nil="true"/>
32      <ns1:ID>12345</ns1:ID>
33      <ns1:ObjectID xsi:nil="true"/>
34     </ns1:List>
35     <ns1:SendDefinitionListType>SourceList</ns1:SendDefinitionListType>
36     <ns1:DataSourceTypeID>FilterDefinition</ns1:DataSourceTypeID>
37     <ns1:FilterDefinition>
38      <ns1:PartnerKey xsi:nil="true"/>
39      <ns1:ModifiedDate xsi:nil="true"/>
40      <ns1:ObjectID>12345</ns1:ObjectID>
41      <ns1:CustomerKey>123456<ns1:CustomerKey>
42     </ns1:FilterDefinition>
43    </ns1:SendDefinitionList>
44    <ns1:Email>
45     <ns1:ModifiedDate xsi:nil="true"/>
46     <ns1:ID>12345</ns1:ID>
47     <ns1:ObjectID xsi:nil="true"/>
48    </ns1:Email>
49   </ns1:Objects>
50  </CreateRequest>
51</SOAP-ENV:Body>
52</SOAP-ENV:Envelope>

SOAP Request for Starting Email Send Definition 

 
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-28677619" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
5            <wsse:Username>username</wsse:Username>
6            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">password</wsse:Password>
7         </wsse:UsernameToken>
8      </wsse:Security>
9   </soapenv:Header>
10   <soapenv:Body>
11      <PerformRequestMsg xmlns="http://exacttarget.com/wsdl/partnerAPI">
12         <Options/>
13         <Action>start</Action>
14         <Definitions>
15            <Definition xsi:type="ns1:EmailSendDefinition" xmlns:ns1="http://exacttarget.com/wsdl/partnerAPI">
16               <CustomerKey>Market2Lead_Email_Definition_Key</CustomerKey>
17            </Definition>
18         </Definitions>
19      </PerformRequestMsg>
20   </soapenv:Body>
21</soapenv:Envelope>

SOAP Response for Starting Email Definition 

 
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:9a508056-981a-4290-83ba-50c5471ec5a1</wsa:MessageID>
5      <wsa:RelatesTo>urn:uuid:bab6f37f-ceab-4a5a-a8d3-9c3f3eb708d9</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-5dd9cc39-7484-49cf-b203-440b4ecc181e">
9            <wsu:Created>2009-03-11T21:05:55Z</wsu:Created>
10            <wsu:Expires>2009-03-11T21:10:55Z</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>66f6728e-7c0e-de11-b30f-001cc494ae9e</ObjectID>
22                  <CustomerKey>Market2Lead_Email_Definition_Key</CustomerKey>
23                  <Name>Market2Lead_Email_Definition</Name>
24               </Object>
25               <Task>
26                  <StatusCode>OK</StatusCode>
27                  <StatusMessage>OK</StatusMessage>
28                  <ID>7029017</ID>
29                  <InteractionObjectID>ed9aae62-800e-de11-b30f-001cc494ae9e</InteractionObjectID>
30               </Task>
31            </Result>
32         </Results>
33         <OverallStatus>OK</OverallStatus>
34         <OverallStatusMessage/>
35         <RequestID>1b9a83ff-9588-4185-92bc-8a138368f243</RequestID>
36      </PerformResponseMsg>
37   </soap:Body>
38</soap:Envelope>

SOAP Request to Update Email Send Definition 

 
1<soapenv:Body>
2      <UpdateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
3         <Options/>
4         <Objects xsi:type="ns1:EmailSendDefinition" xmlns:ns1="http://exacttarget.com/wsdl/partnerAPI">
5            <CustomerKey>Testing_Pub_List_Key</CustomerKey>
6            <Client>
7               <ID>12345</ID>
8            </Client>
9            <Email>
10               <Client>
11                  <ID>12345</ID>
12               </Client>
13               <ID>123456</ID>
14               <ObjectID xsi:nil="true"/>
15               <Subject>Test Email with Content Areas</Subject>
16            </Email>
17            <SendDefinitionList>
18               <PartnerKey xsi:nil="true"/>
19               <ObjectID xsi:nil="true"/>
20               <List>
21                  <Client>
22                     <ID>12345</ID>
23                  </Client>
24                  <ID>1234567</ID>
25               </List>
26               <DataSourceTypeID>List</DataSourceTypeID>
27            </SendDefinitionList>
28         </Objects>
29      </UpdateRequest>
30   </soapenv:Body>

SOAP Request to Update Email Send Definition with New Subject 

 
1<soapenv:Body>
2      <UpdateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
3         <Options/>
4         <Objects xsi:type="ns1:EmailSendDefinition" xmlns:ns1="http://exacttarget.com/wsdl/partnerAPI">
5            <CustomerKey>Testing_Pub_List_Key</CustomerKey>
6            <Client>
7               <ID>12345</ID>
8            </Client>
9            <Email>
10               <Client>
11                  <ID>12345</ID>
12               </Client>
13               <ID>123456</ID>
14               <ObjectID xsi:nil="true"/>
15               <Subject>Test Email with Content Areas</Subject>
16            </Email>
17  <EmailSubject>EmailSendDef subject updated via API</EmailSubject>
18            <SendDefinitionList>
19               <PartnerKey xsi:nil="true"/>
20               <ObjectID xsi:nil="true"/>
21               <List>
22                  <Client>
23                     <ID>12345</ID>
24                  </Client>
25                  <ID>1234567</ID>
26               </List>
27               <DataSourceTypeID>List</DataSourceTypeID>
28            </SendDefinitionList>
29         </Objects>
30      </UpdateRequest>
31   </soapenv:Body>

See Also 

Get Started
APIs
API Integration Security
Tenant-Specific API Endpoints
REST API
SOAP Web Service API
SOAP API Performance
Get Started with SOAP API
Work with SOAP Web Service API
Methods
Objects
Supported Operations for Objects and Methods
Technical Articles
General
Administration
Asynchronous Processing
Automation Studio
Campaigns and Programs
Data Extensions
Emails
Filters
Groups
Import Definition and Activity
Portfolio
Scheduled Messages
Send Definitions and Email Message Interactions
Associate Event Data with a Contact
Cancel a Scheduled Send
Create Items in and Move Items to a Folder
Create a List-Based Email Send Definition
Create a Send Classification
Create a Send Object
Create a Sender Profile
Create an Email Send Definition
Create an Email Send Definition with Dynamic Content
Create the GetMaxCount Action for Email Send Definitions
Create, Perform, and Delete Email Send Definitions
Retrieve the Audience of an Email Send Definition
Retrieve the Scheduled Send Time and Status of a Send
Schedule a User-Initiated Email Message Send
Schedule an Email Send Definition
Start an Email Send Definition
Start an Email Send Definition Test Send
Subscriber Attributes
Subscriber Lists
Subscribers
Tracking
Triggered Sends
Marketing Cloud Engagement for AppExchange API Guide
API Best Practices and Use Cases
API Errors
API Call Volume History and Health
Installed Packages
Programmatic Languages