Java Library

This is a Java client for the REST API.

This client can be installed as a dependency using Maven. In your pom.xml:

Copy

<!-- https://mvnrepository.com/artifact/com.sailthru.client/sailthru-java-client --><dependency>    <groupId>com.sailthru.client</groupId>    <artifactId>sailthru-java-client</artifactId>    <version>2.4.0</version></dependency>

The client jar can be alternatively be downloaded directly from the Maven repository:

https://central.sonatype.com/artifact/com.sailthru.client/sailthru-java-client/

Within your application, a client object can then be created using your API key and secret.

Example:

Copy

String apiKey = "****";
String apiSecret = "****";
SailthruClient sailthruClient = new SailthruClient(apiKey, apiSecret);

The creation of the actual HTTP request and signature for an API call is abstracted away beneath the typed helper functions, per API call.

Standard Helper Function

There are helper functions for most (not all) action/method combination (e.g. GET/POST/DELETE for each API endpoint). They generally return a JsonResponse object, which is just a wrapper around the API's JSON response, and an OK boolean status. Many of these functions accept POJO parameters, as defined in the library--e.g. Blast, User, Template. These objects are to be constructed before invoking the API method. Their various fields are set by chaining their builder-style setter methods.

The setter functions for each POJO are chainable, meaning they return the modified object itself.

Send API Helper Functions

class Send This class is used to submit new sends, or to identify an existing send to be cancelled. All of the potential fields to be passed to the /send endpoint can be chained via builder-style setters. Methods:

setSendId(String sendId): set the id of an already-existing send. Required for send deletion.
setEmail(String email): set the email address to receive the message. Required for send creation.
setTemplate(String template): set the name of the template to use as the basis for the message content. Required for send creation.
setReplyTo(String replyTo): customize the Reply-To email header. Optional for send creation.
setIsTest(): denote the email as a test. Optional for send creation.
setVars(Map<String, Object> vars): A reference of custom vars to be used in the template's Zephyr evaluation.
setLimit(String name, String within_time): DEPRECATED. Set a limit on the number of messages that can be sent with the same limit name set, within the provided period of time (as a time description, e.g. "3 hours").
setScheduleTime(Date scheduleTime): set a time in the future for the message to be sent. Defaults to now. Optional for send creation.
- This method is overloaded to alternatively accept startTime/endTime parameters, which will cause the send to use PST for the actual send time.
setBehalfEmail(String email): sets Sender/From email headers to send the email on behalf of a third party. To be used sparingly, as it affects deliverability. Optional for send creation.
setOptions(Map<String, Object> options): sets a hash of options that can be used to specify any other valid API parameters for the send POST, the full list is available here

class MultiSend extends Send This class is used to submit new multisends. All of the potential fields to be passed to the /send endpoint can be chained via setter methods on a MultiSend object. This class has all of the setter methods available in Send, plus two others: Methods:

setEmails(List emails): list of valid email addresses to send the message to. Required.
setEvars(Map<String, Object> evars): A map of option maps, where the key is one of the emails to receive a message, and the value is a map of options for that email's send, to be used for the template's Zephyr evaluation.

public JsonResponse getSend(String sendId) Looks up the delivery status of a particular send, by its "send_id". Parameters:

String sendId: the send ID returned by a previous send call creating the send

Underlying endpoint: send GET Example: Look up a send by send_id

Copy

JsonResponse send = sailthruClient.getSend("V-WWJIO6iCcAi0Vo");
Map<String,Object> response = send.getResponse();
// handle response

public JsonResponse send(Send send) Send a single message, as detailed by the provided Send object. Parameters:

Send send: the object containing all of the data needed to create the new send.
- Note that email and template must be set on the Send object for the API call to succeed.

Underlying endpoint: send POST Example: send "Abandoned Cart Reminder" template to "example@example.com", using custom send vars, for a time in the future

Copy

Map<String, Object> vars = new HashMap<>();
vars.put("foo", "bar");
Send send = new Send()
    .setTemplate("Abandoned Cart Reminder")
    .setEmail("[example@example.com](mailto:example@example.com)")
    .setVars(vars)
    .setBehalfEmail("[behalf@example.com](mailto:behalf@example.com)")
    .setScheduleTime("tomorrow 9:30am EDT");
JsonResponse response = SailthruClient.send(send);
// handle response (get send ID, check response status, etc)

public JsonResponse multiSend(MultiSend multiSend) Send a message to a list of valid emails, as detailed by the provided MultiSend object. Parameters:

MultiSend multiSend: the object containing all of the data needed to create the new multisend.
- Note that emails and template must be set on the Send object for the API call to succeed.

Underlying endpoint: send POST Example: send "Abandoned Cart Reminder" template to "example1@example.com" and "example2@example.com", using evars, for a time in the future

Copy

List<String> emails = new ArrayList<>();
emails.add("[example1@example.com](mailto:example1@example.com)");
emails.add("[example2@example.com](mailto:example2@example.com)");

Map<String, Object> example1Vars = new HashMap<>();
example1Vars.put("foo", "bar");

Map<String, Object> example2Vars = new HashMap<>();
example2Vars.put("foo", "notbar");

Map<String, OBject> evars = new HashMap<>();
evars.put("[example1@example.com](mailto:example1@example.com)", example1Vars);
evars.put("[example2@example.com](mailto:example1@example.com)", example2Vars);

MultiSend multiSend = new MultiSend()
    .setTemplate("Abandoned Cart Reminder")
    .setEmails(emails)
    .setEvars(evars)
    .setBehalfEmail("[behalf@example.com](mailto:behalf@example.com)")
    .setScheduleTime("tomorrow 9:30am EDT");

JsonResponse response = SailthruClient.multiSend(multiSend);
// handle response (get send IDs, check response status, etc)

public JsonResponse cancelSend(String sendId) Cancels the scheduled send which is identified by "send_id". Note that you can only cancel sends which were scheduled in the future with the "schedule_time" parameters. Parameters:

String sendId: the send ID returned by a previous send call creating the send

Underlying Endpoint: send DELETE Examples: Cancel a send by send ID

Copy

JsonResponse response = sailthruClient.cancelSend("V-WWJIO6iCcAi0Vo");
// handle response

Cancel a send by Send object

Copy

Send send = new Send().setSendId("V-WWJIO6iCcAi0Vo");
JsonResponse response = sailthruClient.cancelSend(send);
// handle response

Blast API Helper Functions

class Blast This class is used to submit new campaigns. All of the potential fields to be passed to the /blast endpoint can be chained via builder-style setters. Methods:

- setName(String name): required. Sets the internal name of the campaign.
- setList(String list): required. Sets the list to receive the campaign.
- setScheduleTime(String schedule_time): required: sets the time to send the campaign.
- setFromName(String fromName): required. Sets the from name for the campaign.
- setFromEmail(String fromEmail): required. Sets the from email for the campaign.
- setSubject(String subject): required. Sets the subject of the email.
- setContentHtml(String contentHtml): required. Sets the content of the email body, for the HTML version of the campaign.
- setContentText(String contentText): required. Sets the content of the email body, for the Text version of the campaign.
- setCopyBlast(Integer copyBlastId): optional. Sets the ID of a previously sent campaign to copy details for, for this campaign.
- setCopyTemplate(String copyTemplate): optional. Sets the name of the template to copy details for, for this campaign.
- setEvalTemplate(String evalTemplate): unknown
- setReplyTo(String replyTo): optional. Customize the Reply-To email header.
- setReportEmail(String reportEmail): optional. Specify an email to receive confirmation upon completion of the campaign.
- enableLinkTracking(): optional. Specify whether clicks and opens should be tracked fro this campaign.
- enableGoogleAnalytics(): optional. Specify whether google analytics parameters are to be appended to links for this campaign.
- setLinkParams(Map<String, String> linkParams): optional. map of query parameters to be appended to links for this blast
- setAsPublic(): optional. Sepcify whether this campaign can be publicly viewable by anyone.
- setSuppressList(String suppressList): optional. Specify a suppress list for this campaign.

setDataFeedUrl(String|URI dataFeedUrl): Optional. Specify a URL to use as a data feed for this campaign.
setSetup(String setup): Optional. Specify a setup section, a block of Zephyr code that will run prior to any other evaluation.
setVars(Map<String, Object> vars): Optional. Set vars to be passed direclty into the campaign without using a data feed, to be used in Zephyr evaluation.
setEmailHourRange(Integer hours). Optional. Enable Personalized Send Time for this campaign, up to the given number of hours past the campaign's schedule time.
setBlastId(Integer blastId): unnecessary when using helper functions. Sets the ID of the campaign to be retrieved.

public JsonResponse getBlast(Integer blastId) Looks up the delivery status of a particular campaign, by its blast ID. Parameters:

Integer blast ID: the blast ID returned by a previous blast call creating the campaign

Underlying Endpoint: blast GET Example: Look up a blast by blast_id

Copy

JsonResponse blast = sailthruClient.getBlast(123);
Map<String,Object> response =blast.getResponse();
// handle response

public JsonResponse scheduleBlast(Blast blast) Schedule a new campaign. Parameters:

Blast blast: the object containing all of the data needed to schedule the campaign, as outlined in the blast POST documentation

Underlying Endpoint: blast POST Example: Schedule a campaign

Copy

Blast blast = new Blast()
    .setName("my campaign")
    .setList("clicked")
    .setSuppressList("not opened")
    .setEmailHourRange(6);
    .setFromName("Example User")
    .setFromEmail("email@example.com")
    .setSubject("my test send")
    .setContentHtml("<p>This is a test</p>{beacon}")
    .setContentText("This is a test");
JsonResponse response = sailthruClient.scheduleBlast(blast);
// handle response

public JsonResponse scheduleBlastFromTemplate(String template, String list, Date scheduleTime) Schedule a new campaign from a template Parameters:

String template: the name of the template to create the campaign from.
String list: the list to send the campaign to.
Date scheduleTime: the time to send the campaign.

Underlying Endpoint: blast POST Example: Schedule a campaign from the "Welcome" template

Copy

Date scheduleTime = Date.from(LocalDateTime.now().plusHours(2).toInstant(ZoneOffset.UTC)); // Java 8
JsonResponse response = sailthruClient.scheduleBlastFromTemplate("My Template", "clicked", scheduleTime);
// handle response

public JsonResponse scheduleBlastFromTemplate(String template, String list, Date scheduleTime, Blast blast) Schedule a new campaign based off a template. Parameters:

String template: the name of the template to create the campaign from.
String list: the list to send the campaign to.
Date scheduleTime: the time to send the campaign.
Blast blast: use a Blast object to set additional settings, as outlined in the blast POST documentation

Underlying Endpoint: blast POST Example: Schedule a campaign from the "Welcome" template, also adding suppress lists and PST

Copy

Date scheduleTime = Date.from(LocalDateTime.now().plusHours(2).toInstant(ZoneOffset.UTC)); // Java 8
Blast blast = new Blast()
        .setEmailHourRange(6)
        .setSuppressList("not opened");
JsonResponse response = sailthruClient.scheduleBlastFromTemplate("My Template", "clicked", scheduleTime, blast);
// handle response

public JsonResponse scheduleBlastFromBlast(Integer blastId, Date scheduleTime) Schedule a new campaign from a previously sent campaign. Parameters:

Integer blastId: the ID of the previously sent blast to create the campaign from.
String list: the list to send the campaign to.
Date scheduleTime: the time to send the campaign.

Underlying Endpoint: blast POST Example: Schedule a campaign from previous campaign 123

Copy

Date scheduleTime = Date.from(LocalDateTime.now().plusHours(2).toInstant(ZoneOffset.UTC)); // Java 8
JsonResponse response = sailthruClient.scheduleBlastFromBlast(123, scheduleTime);
// handle response

public JsonResponse scheduleBlastFromBlast(Integer blastId, Date scheduleTime, Blast blast) Schedule a new campaign based off a previously sent campaign. Parameters:

String template: the name of the template to create the campaign from.
String list: the list to send the campaign to.
Date scheduleTime: the time to send the campaign.
Blast blast: use a Blast object to set additional settings, as outlined in the blast POST documentation

Underlying Endpoint: blast POST Example: Schedule a campaign from previous campaign 123, also adding suppress lists and PST

Copy

Date scheduleTime = Date.from(LocalDateTime.now().plusHours(2).toInstant(ZoneOffset.UTC)); // Java 8
Blast blast = new Blast()
        .setEmailHourRange(6)
        .setSuppressList("not opened");
JsonResponse response = sailthruClient.scheduleBlastFromBlast(123, blast);
// handle response

public JsonResponse updateBlast(Integer blastId, Blast blast) Modify an existing blast by setting any field. Parameters:

Integer blastId: the blast ID returned by a previous blast call creating the campaign
Blast blast: use a Blast object to set additional settings, as outlined in the blast POST documentation

Underlying Endpoint: blast POST Example: Enable link tracking on existing campaign 123

Copy

Blast blast = new Blast()
    .enableLinkTracking();
JsonResponse response = sailthruClient.updateBlast(123, blast);
// handle response

public JsonResponse deleteBlast(Integer blastId) Delete a previously created campaign, by blast ID. This cannot be undone. Parameters:

Integer blastId: the blast ID returned by a previous blast call creating the campaign

Underlying Endpoint: blast DELETE Examples: Delete a previously created blast by blast_id

Copy

JsonResponse response = sailthruClient.deleteBlast(123);
// handle response

Template API Helper Functions

class Template This class is used to create new templates. All of the potential fields to be passed to the /template endpoint can be chained via builder-style setters. Methods:

- setTemplate(String template): Required. The name of the template.

setFromName(String fromName): set the From Name for this template.
setFromEmail(String fromEmail): set the From Email for this template.
setSubject(String subject): set the subject for this template.
setContentHtml(String contentHtml): Sets the content of the email body, for the HTML version of this template.
setContentText(String contentText): Sets the content of the email body, for the Text version of this template
setContentSms(String contentText): Sets the content of the message body, for the SMS version of this template.
enableLinkTracking(): Specify whether clicks and opens should be tracked for this template.
enableGoogleAnalytics(): Specify whether google analytics parameters are to be appended to links for this template.
setLinkParams(Map<String, String> linkParams): map of query paramaters to be appended to links for this template.

public JsonResponse getTemplate(String template) Return details about a named template in your account. Parameters:

String template: the name of the template to fetch

Underlying Endpoint: template GET Examples: Return information about the "Welcome" template in your account

Copy

JsonResponse response = sailthruClient.getTemplate("Welcome");
// handle response

public JsonResponse saveTemplate(Template template) Create or update a template with the provided information. Parameters:

Template template: the object containing all of the data needed to save the template, as outlined in the template POST documentation

Underlying Endpoint: template POST Example: Create a new template with a welcome message

Copy

Template template = new Template()
        .setTemplate("New Template")
        .setContentHtml("<p>Welcome</p>{beacon}")
        .setSubject("Welcome");
JSonResponse response = sailthruClient.saveTemplate(template);
// handle response

public JsonResponse deleteTemplate(String template) Delete a template from your account. This cannot be undone. Parameters:

String template: the name of the template to delete

Underlying Endpoint: template DELETE Examples: Delete a template called "test template"

Copy

JsonResponse response = sailthruClient.deleteTemplate("test template");
// handle response

Content API Helper Functions

class Content This class is used to create new templates. All of the potential fields to be passed to the /content endpoint can be chained via builder-style setters. Note that this library does not currently support Inventory Management. Methods:

setUrl(String url): required: set the URL for this content item.
setTitle(String title): set the title for this content item.
setTags(List<String tags): set a list of tags associated with this content item.
setDate(Date date): set a date associated with this content item.
setDate(String date): set a date associated with this content item, as a descriptor string.
setExpireDate(Date date): set an expiry date associated with this content item.
setExpireDate(String date): set an expiry date associated with this content item, as a descriptor string.
setVars(Map<String, Object> vars): set an arbitrary set of vars associated with this content item.
setSpecialVars(ContentSpecialVar var, String value): set one of 3 special vars: price, description, brand.
setImages(Map<String, Map<String, String>> images): A map of image names to { "url" : } image maps. Use the name "full" to denote the full-sized image, and "thumb" to denote the thumbnail-sized image. Other image names are not reserved.
setFullImage(String url): set the full image for this content item.
setThumbImage(String url): set the thumbnail image for this content item.
setLocation(double latitude, double longitude): set the location associated with this content item.
setPrice(long price): set the price for this content item, in cents.
setDescription(String description): set the description for this content item.
setSiteName(String siteName): set the site name for this content item.
setAuthor(String author): set the author for this content item.
setKeys(Map<String, String> keys): set a map of keys associated with this content item. Currently, only sku is supported in the keys parameter, url is a key that cannot currently be changed.
enableSpider(): force a re-spidering of this content item. Spidering will occur as soon as possible.

public JsonResponse pushContent(Content content) Create or update a content item with the provided information. Parameters:

Content content: the object containing all of the data needed to save the content, as outlined in the content POST documentation

Underlying Endpoint: content POST Example: Create a new content item

Copy

Content content = new Content()
    .setTitle("my new content")
    .setUrl("http://test.com/my-new-content");
JsonResponse response = sailthruClient.pushContent(content);
// handle response

Create a new content item with certain tags

Copy

List<String> tags = new ArrayList<>();
tags.add("new");
tags.add("exciting");
tags.add("shoes");
Content content = new Content()
    .setTitle("my new content")
    .setUrl("[http://test.com/my-new-content](http://test.com/my-new-content)")
    .setTags(tags);
JsonResponse response = sailthruClient.pushContent(content);
// handle response

Purchase API Helper Functions

class PurchaseItem This class is used to represent items bought in a purchase. Tags and item vars can be set via chained builder-style setters; all other (required) parameters are passed into the object constructor. Methods:

(constructor) PurchaseItem(Integer qty, String title, Integer price, String id, String url): creates a purchase item object, taking in all the required parameters.
Parameters:
- Integer qty: Quantity of the item purchased
- String title: Short user-readable name/title of the item purchased
- Integer price: Price of one item, in cents
- String id: Unique identifier (i.e. SKU) of the item
- String url: URL of the item
setTags(List tags): sets a list of tags applicable to this item.
setVars(Map<String, Object> vars): sets any user-defined vars applicable to this item.

class Purchase This class is used to submit new purchases. All of the potential fields to be passed to the /purchase endpoint can be chained via builder-style setters. Methods:

setEmail(String email): required. Sets the email of the purchaser.
setItems(List items): required. Sets the items purchased for this purchase.
setTenders(List<Map<String, Object>> tenders): set the method(s) of payment used for this purchase.
setAdjustments(List<Map<String, Object>> adjustments): set any discounts applied to this purchase.
setAsIncomplete(): mark this purchase as incomplete, i.e. still in the user's shopping cart.
setMessageId(String messageId): Required to match revenue data to campaigns. Pass the identifying message id of the email campaign the user is coming from. This will be stored in the sailthru_bid cookie in your domain.
setReminderTemplate(String reminderTemplate): set a template to send to a user if they have abandoned their shopping cart
setReminderTime(String reminderTime): set the time to send the abandoned cart email, where the parameter is a relative or absolute time descriptor string.
setDate(Date date): set the date of the purchase. Defaults to now.
setDate(String date): set the date of the purchase, passed as a descriptor string.
setSendTemplate(String sendTemplate): set a template to send to this user, e.g. as a receipt or confirmation.
setPurchaseLevelVars(Map<String, Object vars): sets any user-defined vars applicable to this purchase.
setCookies(Map<String, String> cookies): used to submit user cookie values along with the purchase. For example, to ensure attribution for purchased products shown in Site Personalization Manager sections, include the optional sailthru_pc value as the value of the cookie named sailthru_pc.

public JsonResponse pushContent(Content content) Record a purchase into the system. Parameters:

Purchase purchase: the object containing all of the data needed to save the purchase, as outlined in the purchase POST documentation

Underlying Endpoint: purchase POST Examples: Register a purchase for a single product, without any extra options

Copy

int qty = 1;
String title = "product1";
String url = "[https://www.example.com/product1](https://www.example.com/product1)";
int price = 10000;
String id = "id1";
PurchaseItem item = new PurchaseItem(qty, title, price, id, url);
List<PurchaseItem> items = new ArrayList<>();
items.add(item);
Purchase purchase = new Purchase()
        .setEmail("")
        .setItems(items);
JsonResponse response = sailthruClient.purchase(purchase);
// handle response

Register an incomplete purchase for two products, including a coupon code var and a reminder template

Copy

int qty1 = 1;
String title1 = "product1";
String url1 = "https://www.example.com/product1";
int price1 = 10000;
String id1 = "id1";

PurchaseItem item1 = new PurchaseItem(qty1, title1, price1, id1, url1);

int qty1 = 2;
String title1 = "product2";
String url1 = "https://www.example.com/product2";
int price1 = 9999;
String id1 = "id2";

PurchaseItem item2 = new PurchaseItem(qty2, title2, price2, id2, url2);

List<PurchaseItem> items = new ArrayList<>();
items.add(item1);
items.add(item2);
Map<String, Object> vars = new HashMap<>();
vars.put("coupon_code", "xyz");

Purchase purchase = new Purchase()
    .setEmail("")
    .setItems(items)
    .setReminderTemplate("abandoned_cart_template")
    .setReminderTime("+2 days")
    .setVars(vars);
JsonResponse response = sailthruClient.purchase(purchase);

// handle response

Event API Helper Functions

class Event This class is used to submit new events. All of the potential fields to be passed to the /event endpoint can be chained via builder-style setters. Methods:

(constructor) Event(String id): creates an event object, where the subject of the event is the provided id. The id key defaults to sid, and can be changed with the corresponding setter.
(constructor) Event(): creates an event object for a new unknown user profile.
setKey(String key): sets the key of the provided id
setEvent(String eventName): sets the name of the event type.
setVars(Map<String, Object> vars): sets any user-defined vars applicable to this event, potentially to be used for later event processing.
setScheduleTime(String scheduleTime): sets a time for any trigger associated with this event to occur, accepted as a time descriptor string.

public JsonResponse pushEvent(Event event) Record an event into the system. Parameters:

Event event: the object containing all of the data needed to save the event, as outlined in the event POST documentation

Underlying Endpoint: event POST Examples: Register an event for a given email, with schedule time in the future.

Copy

Event event = new Event("[example_email@example.com](mailto:example_email@example.com)")
    .setKey("email")
    .setEvent("custom_event")
    .setScheduleTime("+2 days");
JsonResponse response = sailthruClient.pushEvent(event);
// handle response

Stats API Helper Functions

class Stats This class serves as a wrapper class around the stat type to be retrieved. It is extended by other classes to get stats that require more information. Methods:

(constructor) Stats(String stat): creates a stats object for the given stat type.

class ListStat extends Stats This class is used to request stats for a given list. All of the potential fields to be passed to the /stats endpoint can be chained via builder-style setters. Methods:

setList(String list): required. sets the list to retrieve stats for
setDate(Date date): required. sets the date to retrieve list growth stats for the given list for
setDate(String date): required. sets the date to retrieve list growth stats for the given list for, given as a relative or absolute date descriptor string

class BlastStat extends Stats This class is used to request stats for a given campaign. All of the potential fields to be passed to the /stats endpoint can be chained via builder-style setters. Methods:

setBlastId(Integer blastId): required. Sets the id of the campaign to retrieve stats for.
setStartDate(Date startDate): set a start date for a date range to retrieve stats across all relevant campaigns.
setStartDate(String startDate): set a start date for a date range to retrieve stats across all relevant campaigns, given as a relative or absolute date descriptor string
setEndDate(Date startDate): set an end date for a date range to retrieve stats facross all relevant campaigns.
setEndDate(String startDate): set an end date for a date range to retrieve stats across all relevant campaigns, given as a relative or absolute date descriptor string
setList(String list): set a list to get stats from for a campaign, such that stats will only be returned for campaign recipients on the given list.
enableBeaconTimes(): enables stats to be returned on campaign beacon (open) times.
enableClickTimes(): enables stats to be returned on campaign click times.
enableClickMap(): enables stats on the clickmap to be returned.
enableDomain(): enables domain stats to be returned.
enableEngagement(): enables engagement stats to be returned.
enableSignup(): enables signup stats to be returned.
enableSubject(): enables subject stats to be returned.
enableUrls(): enables stats on the campaign's urls to be returned.

public JsonResponse listStats(ListStat stat) Returns stats on a given list on a given date. Parameters:

ListStat stat: the object containing all of the data needed to request a given list stat, as outlined in the stats GET documentation

Underlying endpoint: /stats GET Examples: Get stats for the performance of the "clicked" list on a certain day

Copy

ListStat stat = new ListStat()
    .setList("clicked")
    .setDate("2016-04-15");
JsonResponse response = sailthruClient.listStats(stat);


// handle response

public JsonResponse blastStats(BlastStat stat) Returns stats on a given campaign. Parameters:

BlastStat stat: the object containing all of the data needed to request a given blast stat, as outlined in the stats GET documentation

Underlying endpoint: /stats GET Examples: Get stats for the engagement level performance of campaigns over a certain month

Copy

BlastStat stat = new BlastStat()
        .setStartDate("-3 months")
        .setEndDate("today")
        .enableEngagement();
JsonResponse response = sailthruClient.blastStats(stat);
// handle response

Get subject line performance for a particular campaign

Copy

BlastStat stat = new BlastStat()
    .setBlastId(225)
    .enableSubject();
JsonResponse response = sailthruClient.blastStats(stat);
// handle response

User API Helper Functions

class User This class is used to lookup, modify, and create user profiles. All of the potential fields to be passed to the /user endpoint can be chained via builder-style setters. Methods:

- (constructor) User(String id): creates a user object, where the subject of the user is the provided id. The id key defaults to sid, and can be changed with the corresponding setter.
- (constructor) User(): creates a user object for a new unknown userprofile.
- setKey(String key): sets the key of the provided id
- setFields(Map<String, Object> fields): sets the fields to be returned by a user POST call. Defaults to none, as the POST by default does not do a synchronous user lookup
- setKeys(Map>String, String< keys): sets a map various keys to save for this user.
- setKeysConflict(String keysConflict): sets the keysconflict recovery mode, eg "merge" or "error"
- setVars(Map<String, Object> vars): sets a map of vars to save for this user
- setLists(Map<String, Object> vars): sets a map of natural list memberships to save for this user

public JsonResponse getUser(User user) Return a user profile by looking up via a User object containing a specified key/value. Parameters:

User user: the object containing the key/value pair used to lookup the user.

Underlying Endpoint: /user GET Examples: Return the user profile for a given ID (sid)

Copy

User user = new User("57e54ddc83ba8895008b4567");
JsonResponse response = sailthruClient.getUser(user);
// handle response

Return the user profile for a given email address

User user = new User("example@example.com")
    .setKey("email");
JsonResponse response = sailthruClient.getUser(user);
// handle response

Return the lists that a user for a given email address is on

Copy

Map<String, Object> fields = new HashMap<>();
fields.put("lists", 1);
User user = new User("example@example.com")
    .setKey("email")
    .setFields(fields);
JsonResponse response = sailthruClient.getUser(user);
// handle response

public JsonResponse saveUser(User user) Update or create a user profile. Parameters:

User user: a user, containing a key/value pair to lookup by, as well as any user API options, as specified in the user POST documentation

Underlying Endpoint: /user POST Examples: Add a var to a user profile

Copy

Map<String, Object> vars = new HashMap<>();
vars.put("abc", 456);
User user = new User("example@example.com")
    .setKey("email")
    .setVars(vars);
JsonResponse response = sailthruClient.saveUser(user);
// handle response

Job API Helper Functions

class Query This class is used to create query objects used for some job types. All of the potential fields need for a query object can be chained via builder-style setters. Query fields are index aligned, meaning that each index of all the different fields must match for each criterion. NOTE: this class is missing an addField(field) function! Methods:

setSourceList(String list): sets a source list for this query.
addCriteria(Criteria criteria): adds a new criterion to this query.
addValue(String value): adds a new value to this query.
addEngagement(int level): adds a new engagement to this query.
addGeoFrequency(int geoFrequency): adds a new geo frequency to this query.
addThreshold(int threshold): adds a new threshold to this query.
addTimeRange(TimeRange timeRange): adds a new timerange to this query.

enum Criteria This enum contains a list of criteria types that can be added to a query object. Any necessary values, timeranges, etc. must be added to the same index. (NOTE this enum does not include more recent criteria types). abstract class Job This abstract class contains base chainable setter functions for options used by all jobs. Methods:

setReportEmail(String reportEmail): sets the report email for this job.
setPostbackUrl(String postbackUrl): sets the postback URL for this job.
setJob(String job): sets the job type for this job. Any subclass must invoke this method with its corresponding job type.

class ImportJob extends Job This class is used to submit new import jobs. All of the potential fields to be passed to the /job endpoint can be chained via builder-style setters. Methods:

setList(String list): Required. Sets the name of the natural list to import to.
setEmails(List emails): Either this method or setFile or setFileDataAsString is required. Sets the list of emails to import.
setFile(File file): Either this method or setEmails or setFileDataAsString is required. Sets the import file to import from.
setFile(String filePath): Either this method or setEmails or setFileDataAsString is required. Sets the import file path to import from.
setFileDataAsString(String data): Either this method or setEmails or setFile is required. Using this method, you can add emails and vars in string format. This method can be used in secure compute environments that do not allow for creation of files in the local file system. See below for examples.

Example: Import user data into a new list called "New List" using file data passed as a string

Copy

ImportJob importJob = new ImportJob()
    .setList("New List")
    // email,name,age columns
    // name and age are profile/user vars
    .setFileDataAsString("email,name,age\nperson.one@example.com,Person One,21\nperson.two@example.com,Person Two,72");

JsonResponse response = sailthruClient.processImportJob(importJob);
// handle response

class SnapshotJob extends Job This class is used to submit new snapshot jobs. All of the potential fields to be passed to the /job endpoint can be chained via builder-style setters. Methods:

setQuery(Query query): sets the query to use for this snapshot.

class BlastQueryJob extends Job This class is used to submit new blast query jobs. All of the potential fields to be passed to the /job endpoint can be chained via builder-style setters. Methods:

setBlastId(int blastId): sets the blast id for this blastquery job.

class ExportListDataJob extends Job This class is used to submit new export list data jobs. All of the potential fields to be passed to the /job endpoint can be chained via builder-style setters. Methods:

setList(String list): sets the list to export for this job

class UpdateJob extends Job This class is used to submit new update jobs. All of the potential fields to be passed to the /job endpoint can be chained via builder-style setters. Methods:

setQuery(Query query): Exactly one of emails, file, url, or query is required. Sets the query to use for this snapshot.
setEmails(List emails): Exactly one of emails, file, url, or query is required. Sets the list of emails to import.
setFile(File file): Exactly one of emails, file, url, or query is required. Sets the import file to import from.
setFile(String filePath): Exactly one of emails, file, url, or query is required. Sets the import file path to import from.
setUrl(URI url): Exactly one of emails, file, url, or query is required. Sets the URL to the import file to import from.
setUrl(String url): Exactly one of emails, file, url, or query is required. Sets the URL to the import file to import from.
setUpdate(Map<String, Object> update): sets the update to perform for each updated user, including setting vars or lists. Overrides any previous calls to setUpdateVars or setUpdateLists.
setUpdateVars(Map<String, Object> vars): sets a map of vars to set for each updated user.
setUpdateLists(Map<String, Integer> lists): sets a map of lists to add or remove for each updated user.
setUpdateOptout(String optout): set an optout value for each updated user.

public JsonResponse getJobStatus(String jobId) Fetch the status of a job. Parameters:

String jobId: the ID of an already-existing job

Underlying endpoint: /job GET Examples: Get status of a particular job

Copy

String jobId = "575b100f83ba8830008b4568";
JsonResponse response = sailthruClient.getJobStatus(jobId);
// handle response

public JsonResponse processImportJob(ImportJob importJob) Submits a new import job. Parameters:

ImportJob importJob: the import job to submit

Underlying Endpoint: job POST Examples: Import a local CSV file into a new list called "New List", with a report email

Copy

ImportJob importJob = new ImportJob()
    .setList("New List")
    .setFile("/path/to/new_users.csv")
    .setReportEmail("[report_email@example.com](mailto:report_email@example.com)");
JsonResponse response = sailthruClient.processImportJob(importJob);
// handle response

public JsonResponse processSnapshotJob(SnapshotJob snapshotJob) Submits a new snapshot job. Parameters:

SnapshotJob snapshotJob: the snapshot job to submit

Underlying Endpoint: job POST Examples: Submit a snapshot for all valids on source list "Source List", with a postback URL

Copy

Query query = new Query()
    .setSourceList("Source List")
    .addCriteria(Criteria.EXISTS);
SnapshotJob snapshotJob = new SnapshotJob()
    .setQuery(query)
    .setPostbackUrl("http://example.com/postback");
JsonResponse response = sailthruClient.processSnapshotJob(importJob);
// handle responsev

public JsonResponse processBlastQueryJob(BlastQueryJob blastQueryJob) Submits a new blast query job. Parameters:

BlastQueryJob blastQueryJob: the blast query job to submit

Underlying Endpoint: job POST Examples: Submit a new blast query job for blast 123

Copy

BlastQueryJob blastQueryJob = new BlastQueryJob()
    .setBlastId(123);
JsonResponse response = sailthruClient.processBlastQueryJob(blastQueryJob);
// handle response

public JsonResponse processExportListDataJob(ExportListDataJob exportListDataJob) Submits a new export list data job. NOTE: it is not possible to set columns to be returned with this method; all columns will be included. Parameters:

ExportListDataJob exportListDataJob: the export job to submit

Underlying Endpoint: job POST Submit a new export job for list "Exported List"

Copy

ExportListDataJob exportJob = new ExportListDataJob()
    .setList("Exported List");
JsonResponse response = sailthruClient.processExportListDataJob(exportJob);
// handle response

public JsonResponse processUpdateJob(UpdateJob updateJob) Submits a new update job Parameters:

UpdateJob updateJob: the update job to submit

Underlying Endpoint: job POST Update users from a remote hosted update file, setting to a var, adding to a list, and removing from a list

Copy

Map<String, Integer> lists = new HashMap<>();
lists.put("Added List Name", 1);
lists.put("Removed List Name, 0);
Map<String, Object> vars = new HashMap<>();
vars.put("abc", 456);
UpdateJob updateJob = new UpdateJob()
    .setUrl("http://example.com/updated_users.csv")
    .setUpdateVars(vars)
    .setUpdateLists(lists);
JsonResponse response = sailthruClient.processUpdateJob(importJob);
// handle response