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.

public void createEmailSendDefinition()
{
    EmailSendDefinition definition = new EmailSendDefinition();

    definition.Name = "DEFINITION_NAME";
    definition.CustomerKey = "DEFINITION_KEY";
    definition.CategoryID = 12345;
    definition.CategoryIDSpecified = true;

    // Retrieve email by ID
    Email email = new Email();
    email.ID = 1234567;
    email.IDSpecified = true;
    definition.Email = email; //Associate Email with defintion.

    SendClassification sendClass = new SendClassification();
    sendClass.ObjectID = "12345678-90ab-cdef-1234-567890abcdef";
    definition.SendClassification = sendClass;

    definition.SendDefinitionList = new SendDefinitionList[1];
    definition.SendDefinitionList[0] = new SendDefinitionList();

    // Define the data extension on the send using the ObjectID of the data
    // extension. If you only know the name of the data extension, perform a
    // retrieve operation to find its ObjectID. Remove this block if you use
    // a list (as opposed to using a data extension) to create the
    // SendDefinitionList.
    definition.SendDefinitionList[0].CustomObjectID = "9f296d0a-fe74-4d38-9033-c9d467bfed3f";
    definition.SendDefinitionList[0].DataSourceTypeID = DataSourceTypeEnum.CustomObject;
    definition.SendDefinitionList[0].DataSourceTypeIDSpecified = true;

    // Uncomment this block if all objects belong to a child account.
    /*
    ClientID clientID = new ClientID();
    clientID.ID = 987654;
    clientID.IDSpecified = true;
    clientID.PartnerClientKey = "SUBACCOUNT_PARTNER_KEY";
    // Create this definition in the subaccount
    definition.Client = clientID;
    */

    // You can create a SendDefinitionList using a list instead of a data
    // extension. Lists are a legacy feature that lack support for newer
    // features such as Contacts and Journey Builder. For this reason, we
    // recommend that you use data extensions.
    // If you choose to use lists, uncomment this block of code, and remove
    // the block that defines the data extension.
    /*
    defintion.SendDefinitionList[0].SendDefinitionListType = SendDefinitionListTypeEnum.SourceList;
    defintion.SendDefinitionList[0].List = new List();
    defintion.SendDefinitionList[0].List.ID = 34567890;
    defintion.SendDefinitionList[0].List.IDSpecified = true;
    defintion.SendDefinitionList[0].DataSourceTypeID = DataSourceTypeEnum.List;
    defintion.SendDefinitionList[0].DataSourceTypeIDSpecified = true;
    */

    definition.IsMultipart = true;
    definition.IsMultipartSpecified = true;
    APIObject[] createObjects = { definition };
    String requestId = null;
    String overallStatus = null;
    CreateResult[] results =
        soapClient.Create(new CreateOptions(), createObjects, out requestId, out overallStatus);
    Console.Write("Results ::: " + overallStatus);
}

Retrieve Email Send Definition

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

// Create the request object
RetrieveRequest request = new RetrieveRequest();
request.ObjectType = "EmailSendDefinition";
request.Properties = new string[] { "Name",
                                    "Description",
                                    "Email.ID",
                                    "CategoryID",
                                    "SendDefinitionList"
                                  };

// Invoke the web service
APIObject[] results;
string status = soapClient.Retrieve(request, out requestID, out results);

// Print overall results
System.Text.StringBuilder sb = new System.Text.StringBuilder();
sb.Append("Retrieve Send");
sb.AppendFormat("\nOverall result: {0}.  RequestID: {1}", status, requestID);
Console.WriteLine(sb.ToString());

// Print results for each new object created
for (int cntr = 0; cntr < results.Length; cntr++)
{
    sb.Append(string.Format("\nIndex {0}", cntr));
    EmailSendDefinition ESD = results[cntr] as EmailSendDefinition;
    sb.Append("\n ID: " + ESD.Name);
    sb.Append("\n Name: " + ESD.Description);
    sb.Append("\n EmailID: " + ESD.Email.ID);
    sb.Append("\n CategoryID: " + ESD.CategoryID);
    // Get SendDefinitionLists for each EmailSendDefinition
    foreach (SendDefinitionList SDL in ESD.SendDefinitionList)
    {
        sb.Append("\n SendDefinitionListType ID: " + SDL.SendDefinitionListType);
        sb.Append("\n SendDefinitionList ID: " + SDL.List.ID);
    }
    sb.Append("\n");
}  Console.WriteLine(sb.ToString());