Create an Email Send Definition

An email send definition is an object that defines the properties, recipients, and content for an email send. Email send definitions are a helpful way to send an email to a list of subscribers.

If you want to use SOAP API to send an email to a list of recipients in a data extension, you must create an email send definition.

Code Examples

These C# code examples show how to interact with email send classifications and send definitions.

Create the Email Send Definition

This example creates a send definition that includes a recipient list from a data extension.

1public void createEmailSendDefinition()
2{
3    EmailSendDefinition definition = new EmailSendDefinition();
4
5    definition.Name = "DEFINITION_NAME";
6    definition.CustomerKey = "DEFINITION_KEY";
7    definition.CategoryID = 12345;
8    definition.CategoryIDSpecified = true;
9
10    // Retrieve email by ID
11    Email email = new Email();
12    email.ID = 1234567;
13    email.IDSpecified = true;
14    definition.Email = email; //Associate Email with defintion.
15
16    SendClassification sendClass = new SendClassification();
17    sendClass.ObjectID = "12345678-90ab-cdef-1234-567890abcdef";
18    definition.SendClassification = sendClass;
19
20    definition.SendDefinitionList = new SendDefinitionList[1];
21    definition.SendDefinitionList[0] = new SendDefinitionList();
22
23    // Define the data extension on the send using the ObjectID of the data
24    // extension. If you only know the name of the data extension, perform a
25    // retrieve operation to find its ObjectID. Remove this block if you use
26    // a list (as opposed to using a data extension) to create the
27    // SendDefinitionList.
28    definition.SendDefinitionList[0].CustomObjectID = "9f296d0a-fe74-4d38-9033-c9d467bfed3f";
29    definition.SendDefinitionList[0].DataSourceTypeID = DataSourceTypeEnum.CustomObject;
30    definition.SendDefinitionList[0].DataSourceTypeIDSpecified = true;
31
32    // Uncomment this block if all objects belong to a child account.
33    /*
34    ClientID clientID = new ClientID();
35    clientID.ID = 987654;
36    clientID.IDSpecified = true;
37    clientID.PartnerClientKey = "SUBACCOUNT_PARTNER_KEY";
38    // Create this definition in the subaccount
39    definition.Client = clientID;
40    */
41
42    // You can create a SendDefinitionList using a list instead of a data
43    // extension. Lists are a legacy feature that lack support for newer
44    // features such as Contacts and Journey Builder. For this reason, we
45    // recommend that you use data extensions.
46    // If you choose to use lists, uncomment this block of code, and remove
47    // the block that defines the data extension.
48    /*
49    defintion.SendDefinitionList[0].SendDefinitionListType = SendDefinitionListTypeEnum.SourceList;
50    defintion.SendDefinitionList[0].List = new List();
51    defintion.SendDefinitionList[0].List.ID = 34567890;
52    defintion.SendDefinitionList[0].List.IDSpecified = true;
53    defintion.SendDefinitionList[0].DataSourceTypeID = DataSourceTypeEnum.List;
54    defintion.SendDefinitionList[0].DataSourceTypeIDSpecified = true;
55    */
56
57    definition.IsMultipart = true;
58    definition.IsMultipartSpecified = true;
59    APIObject[] createObjects = { definition };
60    String requestId = null;
61    String overallStatus = null;
62    CreateResult[] results =
63        soapClient.Create(new CreateOptions(), createObjects, out requestId, out overallStatus);
64    Console.Write("Results ::: " + overallStatus);
65}

Retrieve Email Send Definition

This code example retrieves information about a specific email send definition.

1// Create the request object
2RetrieveRequest request = new RetrieveRequest();
3request.ObjectType = "EmailSendDefinition";
4request.Properties = new string[] { "Name",
5                                    "Description",
6                                    "Email.ID",
7                                    "CategoryID",
8                                    "SendDefinitionList"
9                                  };
10
11// Invoke the web service
12APIObject[] results;
13string status = soapClient.Retrieve(request, out requestID, out results);
14
15// Print overall results
16System.Text.StringBuilder sb = new System.Text.StringBuilder();
17sb.Append("Retrieve Send");
18sb.AppendFormat("\nOverall result: {0}.  RequestID: {1}", status, requestID);
19Console.WriteLine(sb.ToString());
20
21// Print results for each new object created
22for (int cntr = 0; cntr < results.Length; cntr++)
23{
24    sb.Append(string.Format("\nIndex {0}", cntr));
25    EmailSendDefinition ESD = results[cntr] as EmailSendDefinition;
26    sb.Append("\n ID: " + ESD.Name);
27    sb.Append("\n Name: " + ESD.Description);
28    sb.Append("\n EmailID: " + ESD.Email.ID);
29    sb.Append("\n CategoryID: " + ESD.CategoryID);
30    // Get SendDefinitionLists for each EmailSendDefinition
31    foreach (SendDefinitionList SDL in ESD.SendDefinitionList)
32    {
33        sb.Append("\n SendDefinitionListType ID: " + SDL.SendDefinitionListType);
34        sb.Append("\n SendDefinitionList ID: " + SDL.List.ID);
35    }
36    sb.Append("\n");
37}  Console.WriteLine(sb.ToString());