sendwithus_java

This repository contains the source code for the Java library for sending email via the sendwithus API.

To use the library in your own project, please follow the installation and usage instructions below - you do not need to build the library yourself.

Warning

This client is a working development repository, please use the 1.6.0 jar or maven repository. Do not build the client yourself.

Installation

via maven (preferred)

Add the following to your pom.xml:

<!-- in the repositories section -->
<repository>
<id>repo</id>
<url>https://github.com/sendwithus/sendwithus-mvn-repo/raw/master/releases</url>
</repository>
<!-- in the dependencies section -->
<dependency>
<groupId>com.sendwithus</groupId>
<artifactId>java-client</artifactId>
<version>2.2.0</version>
</dependency>

via wget:

$ wget https://github.com/sendwithus/sendwithus-mvn-repo/raw/master/releases/com/sendwithus/java-client/2.2.0/java-client-2.2.0.jar

External Dependencies (if not using maven)

• gson-2.2.2
• commons-io-2.4
• commons-codec

Usage

Sending

See SendWithUsExample.java for full usage.

NOTE - If a customer does not exist by the specified email (recipient address), the send call will create a customer.

NOTE - Email ID is the ID of the Template (template id)

Two APIs now exist for issuing "Send" requests:

• Legacy: SendWithUs.send(...) methods

A collection of overloaded methods for sending an Email with various parameters. DOES NOT SUPPORT: Tags, Inline Attachments, Version Name

• New: SendWithUsSendRequest class

The new method, employing SendWithUsSendRequest objects, enables a more object-oriented approach to issuing Send requests. The objects allow you to specify only the desired request parameters, and can be re-used and mutated easily.

Provided parameter setters:

• setEmailId(String emailId)
• setRecipient(Map<String, Object> recipient)
• setEmailData(Map<String, Object> emailData)
• setCcRecipients(Map<String, Object>[] ccRecipients)
• setBccRecipients(Map<String, Object>[] bccRecipients)
• setSender(Map<String, Object> sender)
• setTags(String[] tags)
• setInline(Map<String, String> inline)
• setAttachmentPaths(String[] attachmentPaths)
• setEspAccount(String espAccount)
• setVersionName(String versionName)
• setLocale(String locale)
• setHeaders(Map<String, Object> headers)

Advanced

The following methods are also available:

• templates()
• template(String)
• versions(String, String)
• render(String, Map<String, Object>)
• deactivateDrips(String)
• createUpdateCustomer(String, Map<String, Object>)
• getSnippets()
• getSnippet(String)
• createSnippet(String, String)
• updateSnippet(String, String, String)
• deleteSnippet(String)
• resend(String)

Examples

importjava.util.HashMap;
importjava.util.Map;
importcom.sendwithus.SendWithUs;
// IDs and API keys are found in the Sendwithus dashboardfinalStringSENDWITHUS_API_KEY = "API-KEY-HERE"; // starts with "live_..." or "test_..."finalStringTEMPLATE_ID = "TEMPLATE-ID-HERE"; // starts with "tem_..."finalStringDRIP_CAMPAIGN_ID = "DRIP-CAMPAIGN-ID-HERE"; // starts with "dc_..."finalStringSNIPPET_ID = "SNIPPET-ID-HERE"; // starts with "snp_..."SendWithUssendwithusAPI = newSendWithUs(SENDWITHUS_API_KEY);
// SendMap<String, Object> recipientMap = newHashMap<String, Object>();
recipientMap.put("name", "Matt"); // optionalrecipientMap.put("address", "us@sendwithus.com");
// Sender is optionalMap<String, Object> senderMap = newHashMap<String, Object>();
senderMap.put("name", "Company"); // optionalsenderMap.put("address", "company@company.com");
senderMap.put("reply_to", "info@company.com"); // optional// ESP Account is optionalStringespAccount = "esp_1234asdf";
// Setup Email Data for SendMap<String, Object> emailDataMap = newHashMap<String, Object>();
emailDataMap.put("first_name", "Brad");
emailDataMap.put("link", "http://sendwithus.com/some_link");
// Attachments is optionalString[] attachments = {"test.png"}
// CC is optional (BCC follows a similar pattern)String[] ccEmails = {"name.foo@domain.ca", "name.bar@domain.ca"};
HashMap<String, Object>[] ccRecipientsMap = (HashMap<String, Object>[]) newHashMap[ccEmails.length];
inti = 0;
for (Stringemail : ccEmails){
HashMap<String, Object> hashMap = newHashMap<String, Object>();
hashMap.put("address", email);
ccRecipientsMap[i] = hashMap;
i++;
}
// Sending the email using the legacy send() java APISendReceiptsendReceipt = sendwithusAPI.send(
TEMPLATE_ID,
recipientMap,
senderMap,
emailDataMap,
null,
null,
attachments,
espAccount
);
// Example sending the same email using the new SendWithUsSendRequest classSendWithUsSendRequestrequest = newSendWithUsSendRequest()
.setEmailId(TEMPLATE_ID)
.setRecipient(recipientMap)
.setCcRecipients(ccRecipientsMap)
.setSender(senderMap)
.setEmailData(emailDataMap)
.setAttachmentPaths(attachments)
.setEspAccount(espAccount);
SendReceiptsendReceipt = sendwithusAPI.send(request);
// Resend ExampleSendReceiptsendReceipt = sendwithusAPI.resend("log_asdf123456qwerty");
// TemplatesEmailtemplate = sendwithusAPI.template(TEMPLATE_ID);
List<TemplateVersion> versions = template.getVersions();
TemplateVersionversion = versions.get(0);
TemplateVersionDetailsdetails = sendwithusAPI.version(TEMPLATE_ID, version.getId());
// Drip CampaignsStringrecipientAddress = "customer@email.com";
SendWithUsDripRequestdripRequest = newSendWithUsDripRequest();
dripRequest.setRecipient(recipientMap);
dripRequest.setEmailData(emailDataMap);
ActivatedDripactivateDripCampaign = sendwithusAPI.startOnDripCampaign(DRIP_CAMPAIGN_ID, dripRequest);
DeactivatedDripdeactivateDripCampaign = sendwithusAPI.removeFromDripCampaign(recipientAddress, DRIP_CAMPAIGN_ID);
DeactivatedDripsdeactivateAllDripCampaigns = sendwithusAPI.deactivateDrips(recipientAddress);
// CustomersCustomerReceiptcustomerReceipt = sendwithusAPI.createUpdateCustomer(recipientAddress, emailDataMap);
// SnippetsStringsnippetName = "My Snippet";
StringsnippetBody = "<h1>Snippets!</h1>";
Snippet[] snippets = sendwithusAPI.getSnippets();
Snippetsnippet = sendwithusAPI.getSnippet(SNIPPET_ID);
SnippetReceiptcreateSnippet = sendwithusAPI.createSnippet(snippetName, snippetBody);
SnippetReceiptupdateSnippet = sendwithusAPI.updateSnippet(SNIPPET_ID, snippetName, snippetBody);
APIReceiptdeleteSnippet = sendwithusAPI.deleteSnippet(SNIPPET_ID);
// RenderRenderedTemplaterender = sendwithusAPI.render(TEMPLATE_ID, emailDataMap);

Errors

The following errors may be generated:

com.sendwithus.exception.SendWithUsException - Raised by send exceptions

Response Ranges

Sendwithus' API typically sends responses back in these ranges:

• 2xx – Successful Request
• 4xx – Failed Request (Client error)
• 5xx – Failed Request (Server error)

If you're receiving an error in the 400 response range follow these steps:

• Double check the data and ID's getting passed to sendwithus
• Ensure your API key is correct
• Log and check the body of the response

Developing

Prerequisites

• Java version 8 or higher
• Maven

Building and Running Tests

To build the client and run tests use this command:

mvn verify