This document contains conceptual, procedural, and scenario information about using the Send server-side JavaScript functions.

Why Use Send Server-Side JavaScript Functions

These functions allow you to access and control how emails are sent via your ExactTarget account. 

Scenario

Northern Trail Outfitters conducts several email sends over the course of any given week, but the parameters for each type of send do not usually change. They use server-side JavaScript to retrieve the existing email sends, change the email message associated with those sends in order to send new content, and schedule a time for the sends to go out.

How to Use the Send Server-Side JavaScript Functions

In your server-side JavaScript code, first load the core library using the syntax below:

Platform.Load("core","1");

Use the sample code below as models for your own server-side JavaScript code.

Initialize

To interact with a existing send via server-side JavaScript, you must first initialize the object. The code below initializes a send with a send ID of 12345:

var s = Send.Init(12345);

Once you initialize the send, you can use the other functions contained on this page.

Add(emailKey, listIDArray, options)

This function adds a new send to your account and returns the status of the send's creation.

Arguments

  • emailKey - The CustomerKey of the email  you want to associate with this send.
  • listIDArray - An array of list IDs to associate with the send.
  • options - An optional parameter to allow send parameter flexibility, such as specifying a different Email subject or SendTime for scheduled sends.

The sample code below adds a send to your account, which will send the specified email message to the provided lists:

var status = Send.Add("test_email", [ 12345, 12346 ]);

The sample code below adds a send to your account, which will send the specified email message to the provided lists using the additional From name, From email address, and Subject specified in the Options variable:

var options = {
    FromName : "JSON Specified Name",
    FromAddress : "aruiz@example.com",
    Subject : "JSON Test Mail"
};

var status = Send.Add('test_email', [ 12345, 12346 ], options);

CancelSend()

This function attempts to cancel a currently existing send.

The sample code below demonstrates how to perform this against an initialized send:

var mySend = Send.Init(12345);
var status = mySend.CancelSend();

RetrieveLists(filter)

This function retrieves information regarding which list or lists that were targeted by a Send event.

The sample code below demonstrates how to retrieve this information for an individual Send event using the SendID:

var filter = { Property : "SendID", SimpleOperator : "equals", Value : 12345 };
var listsSentTo = Send.RetrieveLists(filter);

Definition

This sub-object allows you to add, update, retrieve, and remove email send definitions as well as send emails using an email send definition.

Initialize

To interact with a send definition via server-side JavaScript, you must first initialize the object. The code below initializes a send definition with the external key of myESD.

var esd = Send.Definition.Init('myESD');

Retrieve(filter)

This function retrieves send definitions based on the specified criteria.

Arguments
  • filter - The criteria on which to search for the send definition

The sample code below retrieves an array of send definitions based on the specified criteria:

var esd = Send.Definition.Retrieve({Property:"CustomerKey", SimpleOperator:"equals", Value:"ssjs_test_esd"});

Add(params, scKey, emailKey, listIDArray)

This function allows you to add a send definition.

Arguments
  • params - The customer key, name, and subject line to use for the send definition
  • scKey - The customer key of the related send classification
  • emailKey - The customer key of the email to be used in the send definition
  • listIDArray - An array of list IDs

The sample code below adds the send definition.

var esdParams = {
    "CustomerKey" : "example_esd",
    "Name" : "Example Send Definition",
    "EmailSubject" : "Sent By Example Send Definition"
};
Send.Definition.Add(esdParams, 'example_sc_key', 'example_email_key', [ 12345, 12346 ]);

AddWithDE(params, scKey, emailKey, deKey, pubListKey)

This function allows you to add a send definition that incorporates a sendable data extension.

Arguments
  • params - The customer key, name, and subject line to use for the send definition
  • scKey - The customer key of the related send classification
  • emailKey - The customer key of the email to be used in the send definition
  • deKey - The customer key of the sendable data extension to be used in the send definition
  • pubListKey - The customer key of the publication list to use in conjunction with the send definition

The sample code below adds the send definition with the appropriate sendable data extension:

var esdParams = {
    "CustomerKey" : "ssjs_de_esd_1c",
    "Name" : "SSJS DE Test ESD3",
    "EmailSubject" : "Third send By Test DE Send Definition"
};

// local values
var scKey = 'scKey';
var emailKey = 'test_email';
var deKey = 'deKey';
var pubListKey = 'myPubList';

var status = Send.Definition.AddWithDE(esdParams, scKey, emailKey, deKey, pubListKey);

AddWithFilterDefinition(params, scKey, emailKey, filterDefKey, listID)

This function allows you to add a send definition that incorporates a filter definition.

Arguments
  • params - The customer key, name, and subject line to use for the send definition
  • scKey - The customer key of the related send classification
  • emailKey - The customer key of the email to be used in the send definition
  • filterDefKey - The customer key of the filter definition to be used in the send definition
  • listID - the targeted list ID

The sample code below adds the send definition with the appropriate filter definition:

var esdParams = {
    "CustomerKey" : "filterDef_esd",
    "Name" : "Example Filtered Send Definition",
    "EmailSubject" : "Sent By Filtered Send Definition"
};

var scKey = 'scKey';
var emailKey = 'test_email';
var filterDefKey = 'fdKey';
var listID = 144;

var status = Send.Definition.AddWithFilterDefinition(esdParams, scKey, emailKey, filterDefKey, listID);

Remove()

This function will remove a previously initialized send definition and return the status of the removal.

The sample code removes a send definition with an external key of myESD:

var esd = Send.Definition.Init('myESD');
var status = esd.Remove();

Send(sendTime)

This function sends email to the lists associated with the initialized send definition.

Arguments
  • sendTime - An optional Date object specifying when the send should be performed. If null/not passed, the send will be performed immediately.

The sample code initializes a send definition with an external key of myESD and performs a send:

var esd = Send.Definition.Init('myESD');
var status = esd.Send();

Update(params)

This function updates the send definition and returns a status.

Arguments
  • params - Attributes regarding the send definition to be changed.

The sample code initializes a send definition with an external key of myESD and updates the name:

var esd = Send.Definition.Init('myESD');
var status = esd.Update({ "Name" : "Updated ESD Name" });

This sample code updates an email send definition with a new sendable data extension:

var newDE = {
    DataExtensionKey : "DE"
    PubListKey : "MyPubListKey"
}

var deESD = Send.Definition.Init('ESD');
var status = deESD.Update(newDE);

This sample code demonstrates how to update a filter definition used by a send definition:

var esd = Send.Definition.Init('myESD');
var esdUpdates = {
    Name : "Updated ESD Name",
    FilterDefinition : {
        CustomerKey : "myFilterDefKey",
        ListID : 12345
    }
};

var status = esd.Update(esdUpdates);

Remove()

This function removes the send you initialized previously.

The sample code below deletes the send with ID 12345.

var s = Send.Init(12345);
s.Remove();

Retrieve(filter)

This function retrieves a send based on the specified criteria.

Arguments

  • filter - The criteria on which to search for the send

The sample code below retrieves a send based on the specified filter criteria:

var sends = Send.Retrieve({Property:"ID",SimpleOperator:"equals",Value:12345});

This code sample uses a more complex filter to retrieve a send:

<script language="JavaScript" runat="Server"> Platform.Load("core", "1");
    var emailIDFilter = { Property : "Email.ID", SimpleOperator : "equals", Value : 71 }; var esdFilter = { Property : "EmailSendDefinition.CustomerKey", SimpleOperator : "equals", Value : "test_esd" };
    var complexFilter = {LeftOperand : emailIDFilter, LogicalOperator : "AND", RightOperand : esdFilter };
    Write(Stringify(Send.Retrieve(complexFilter)));
</script>

Tracking

This sub-object retrieves tracking information relating to sends.

Retrieve(filter)

This function returns an array of tracking data related to the send(s) specified by the passed filter argument.

Arguments
  • filter - The criteria on which to search for the send

The sample code below retrieves an array of tracking data for the send(s) based on the specified filter criteria:

var sendTracking = Send.Tracking.Retrieve({Property:"SendID",SimpleOperator:"equals",Value:12345});

Clicks.Retrieve(filter)

This function returns click tracking information for this send specified by the specified filter criteria

Arguments
  • filter - The criteria on which to filter the tracking results
var singleSend = Send.Init(12345);
var results = singleSend.Tracking.Clicks.Retrieve({Property:"ID",SimpleOperator:"equals",Value:12345});

TotalByInterval.Retrieve(type, startDate, endDate, totalBy)

This function returns tracking data related to an initialized send specified by type, duration, and interval.

Arguments
  • type - The type of data to aggregate and return. Valid values include the following:
    • Send
    • Open
    • Click
    • Bounce
    • Unsubscribe
  • startDate - The start date of the period of data
  • endDate - The end date of the period of data
  • totalBy - The interval to aggregate the data by. Valid values include the following:
    • day
    • hour

The sample code below returns a month's worth of click data for the initialized send aggregated by day:

var singleSend = Send.Init(12345);
var results = singleSend.Tracking.TotalByInterval.Retrieve('Click', '07-01-2010', '07-31-2010', 'day');
Was This Page Helpful?
Last updated by ryan.williams at 11:27, 9 Apr 2014