GitHub - sendwithus/sendwithus_java: Sendwithus Java Client

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)

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

import java.util.HashMap;
import java.util.Map;

import com.sendwithus.SendWithUs;

// IDs and API keys are found in the Sendwithus dashboard
final String SENDWITHUS_API_KEY = "API-KEY-HERE"; // starts with "live_..." or "test_..."
final String TEMPLATE_ID = "TEMPLATE-ID-HERE"; // starts with "tem_..."
final String DRIP_CAMPAIGN_ID = "DRIP-CAMPAIGN-ID-HERE"; // starts with "dc_..."
final String SNIPPET_ID = "SNIPPET-ID-HERE"; // starts with "snp_..."

SendWithUs sendwithusAPI = new SendWithUs(SENDWITHUS_API_KEY);

// Send
Map<String, Object> recipientMap = new HashMap<String, Object>();
recipientMap.put("name", "Matt"); // optional
recipientMap.put("address", "us@sendwithus.com");

// Sender is optional
Map<String, Object> senderMap = new HashMap<String, Object>();
senderMap.put("name", "Company"); // optional
senderMap.put("address", "company@company.com");
senderMap.put("reply_to", "info@company.com"); // optional

// ESP Account is optional
String espAccount = "esp_1234asdf";

// Setup Email Data for Send
Map<String, Object> emailDataMap = new HashMap<String, Object>();
emailDataMap.put("first_name", "Brad");
emailDataMap.put("link", "http://sendwithus.com/some_link");

// Attachments is optional
String[] 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>[]) new HashMap[ccEmails.length];

int i = 0;
for (String email : ccEmails){
    HashMap<String, Object> hashMap = new HashMap<String, Object>();
    hashMap.put("address", email);
    ccRecipientsMap[i] = hashMap;
    i++;
}

// Sending the email using the legacy send() java API
SendReceipt sendReceipt = sendwithusAPI.send(
    TEMPLATE_ID,
    recipientMap,
    senderMap,
    emailDataMap,
    null,
    null,
    attachments,
    espAccount
);

// Example sending the same email using the new SendWithUsSendRequest class
SendWithUsSendRequest request = new SendWithUsSendRequest()
    .setEmailId(TEMPLATE_ID)
    .setRecipient(recipientMap)
    .setCcRecipients(ccRecipientsMap)
    .setSender(senderMap)
    .setEmailData(emailDataMap)
    .setAttachmentPaths(attachments)
    .setEspAccount(espAccount);
SendReceipt sendReceipt = sendwithusAPI.send(request);

// Resend Example
SendReceipt sendReceipt = sendwithusAPI.resend("log_asdf123456qwerty");

// Templates
Email template = sendwithusAPI.template(TEMPLATE_ID);
List<TemplateVersion> versions = template.getVersions();
TemplateVersion version = versions.get(0);
TemplateVersionDetails details = sendwithusAPI.version(TEMPLATE_ID, version.getId());

// Drip Campaigns
String recipientAddress = "customer@email.com";

SendWithUsDripRequest dripRequest = new SendWithUsDripRequest();
dripRequest.setRecipient(recipientMap);
dripRequest.setEmailData(emailDataMap);

ActivatedDrip activateDripCampaign = sendwithusAPI.startOnDripCampaign(DRIP_CAMPAIGN_ID, dripRequest);
DeactivatedDrip deactivateDripCampaign = sendwithusAPI.removeFromDripCampaign(recipientAddress, DRIP_CAMPAIGN_ID);
DeactivatedDrips deactivateAllDripCampaigns = sendwithusAPI.deactivateDrips(recipientAddress);

// Customers
CustomerReceipt customerReceipt = sendwithusAPI.createUpdateCustomer(recipientAddress, emailDataMap);

// Snippets
String snippetName = "My Snippet";
String snippetBody = "<h1>Snippets!</h1>";
Snippet[] snippets = sendwithusAPI.getSnippets();
Snippet snippet = sendwithusAPI.getSnippet(SNIPPET_ID);
SnippetReceipt createSnippet = sendwithusAPI.createSnippet(snippetName, snippetBody);
SnippetReceipt updateSnippet = sendwithusAPI.updateSnippet(SNIPPET_ID, snippetName, snippetBody);
APIReceipt deleteSnippet = sendwithusAPI.deleteSnippet(SNIPPET_ID);

// Render
RenderedTemplate render = 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: