The SocketLabs Email Delivery Java library allows you to easily send email messages via the SocketLabs Injection API. The library makes it easy to build and send any type of message supported by the API, from a simple message to a single recipient all the way to a complex bulk message sent to a group of recipients with unique merge data per recipient.
- A supported Java version
- Oracle JDK 8
- A SocketLabs account. If you don't have one yet, you can sign up for a free account to get started.
Choose your installation method - Maven w/ Gradle (recommended), Maven or Jar file.
Add the following to your build.gradle file in the root of your project.
...
dependencies {
...
compile group: 'com.socketlabs', name: 'injectionApi', version: '1.4.0'
}
repositories {
mavenCentral()
}
...
<dependency>
<groupId>com.socketlabs</groupId>
<artifactId>injectionApi</artifactId>
<version>1.4.0</version>
</dependency>
You can just drop the jar file in.
injectionApi-1.4.0-sources.jar
injectionApi-1.4.0-javadoc.jar
Alternately, you can simply clone this repository directly to include the source code in your project.
In order to get started, you'll need to enable the Injection API feature in the SocketLabs Control Panel. Once logged in, navigate to your SocketLabs server's dashboard (if you only have one server on your account you'll be taken here immediately after logging in). Make note of your 4 or 5 digit ServerId number, as you'll need this along with your API key in order to use the Injection API.
To enable the Injection API, click on the "For Developers" dropdown on the top-level navigation, then choose the "Configure HTTP Injection API" option. Once here, you can enable the feature by choosing the "Enabled" option in the dropdown. Enabling the feature will also generate your API key, which you'll need (along with your ServerId) to start using the API. Be sure to click the "Update" button to save your changes once you are finished.
A basic message is an email message like you'd send from a personal email client such as Outlook. A basic message can have many recipients, including multiple To addresses, CC addresses, and even BCC addresses. You can also send a file attachment in a basic message.
import com.socketLabs.injectionApi.*;
import com.socketLabs.injectionApi.message.*;
SocketLabsClient client = new SocketLabsClient(000001, "YOUR-API-KEY"); //Your SocketLabs ServerId and Injection API key
BasicMessage message = new BasicMessage();
message.setSubject("Sending A Test Message (Basic Send)");
message.setHtmlBody("<html><body><h1>Sending A Test Message</h1><p>This is the Html Body of my message.</p></body></html>");
message.setPlainTextBody("This is the Plain Text Body of my message.");
message.setFrom(new EmailAddress("from@example.com"));
//A basic message supports up to 50 recipients and supports several different ways to add recipients
// Adding To Recipients
message.getTo().add(new EmailAddress("recipient1@example.com"));
message.getTo().add(new EmailAddress("recipient2@example.com", "Recipient #2"));
// Adding CC Recipients
message.addCcEmailAddress(new EmailAddress("ccRecipients1@example.com", "Recipient #3" ));
// Adding Bcc Recipients
message.addBccEmailAddress("bccRecipients1@example.com");
message.addBccEmailAddress("bccRecipients2@example.com", "Recipient #2");
SendResponse response = client.send(message);A bulk message usually contains a single recipient per message and is generally used to send the same content to many recipients, optionally customizing the message via the use of MergeData. For more information about using Merge data, please see the Injection API documentation.
import com.socketLabs.injectionApi.*;
import com.socketLabs.injectionApi.message.*;
SocketLabsClient client = new SocketLabsClient(000001, "YOUR-API-KEY"); //Your SocketLabs ServerId and Injection API key
BulkMessage message = new BulkMessage();
message.setSubject("Sending A Test Message (Bulk Send)");
message.setHtmlBody("<html><body><h1>Sending A Test Message</h1><p>This is the Html Body of my message.</p></body></html>");
message.setPlainTextBody("This is the Plain Text Body of my message.");
message.setFrom(new EmailAddress("from@example.com"));
message.setReplyTo(new EmailAddress("replyto@example.com"));
message.getTo().add(new BulkRecipient("recipient1@example.com"));
message.getTo().add(new BulkRecipient("recipient2@example.com", "Recipient #2"));
message.getTo().add(new BulkRecipient("recipient3@example.com"));
message.getTo().add(new BulkRecipient("recipient4@example.com", "Recipient #4"));
SendResponse response = client.send(message);For ease of demonstration, many of our examples include the ServerId (SOCKETLABS_SERVER_ID) and API key (SOCKETLABS_INJECTION_API_KEY) directly in our code sample. Generally it is not considered a good practice to store sensitive information like this directly in your code. Depending on your project type, we recommend either storing your credentials using Environment Variables. For more information please see: Using Environment Variables
In order to demonstrate the many possible use cases for the SDK, we've provided an assortment of code examples. These examples demonstrate many different features available to the Injection API and SDK, including using templates created in the SocketLabs Email Designer, custom email headers, sending attachments, sending content that is stored in an HTML file, advanced bulk merging, and even pulling recipients from a datasource.
This example demonstrates a Basic Send done asynchronously.
This example demonstrates a Basic Send done synchronously.
This example demonstrates many features of the Basic Send, including adding multiple recipients, adding message and mailing id's, and adding an embedded image.
This example demonstrates how to read in your HTML content from an HTML file rather than passing in a string directly.
This example demonstrates the sending of a piece of content that was created in the SocketLabs Email Designer. This is also known as the API Templates feature.
This example demonstrates sending with a specific character set.
This example demonstrates how to add a file attachment to your message.
This example demonstrates how to add custom headers to your email message.
This example demonstrates how to embed an image in your message.
This example demonstrates how to use a proxy with your HTTP client.
This example demonstrates how to use the retry logic with your HTTP client.
This example demonstrates the results of attempting to do a send with an invalid attachment.
This example demonstrates the results of attempting to do a send with an invalid from address.
This example demonstrates the results of attempting to do a send with invalid recipients.
This example demonstrates how to send a basic message with an AMP Html body. For more information about AMP please see AMP Project
This example demonstrates how to send a bulk message to multiple recipients.
This example demonstrates many features of the BulkMessage(), including
adding multiple recipients, merge data, and adding an attachment.
This example uses a mock repository class to demonstrate how you would pull your recipients from a database and create a bulk mailing with merge data.
This example demonstrates how to send a bulk message with a specified character set and special characters.
This example demonstrates how to send a bulk message to multiple recipients with unique merge data per recipient.
This example demonstrates how to send a bulk message with an AMP Html body. For more information about AMP please see AMP Project
- 1.4.0 - Adding Metadata and Tags
- 1.2.1 - Adding optional retry logic for Http requests. If configured, the request will retry when certain 500 errors occur (500, 502, 503, 504)
- 1.1.1 - Adding request timeout value on the client for Http requests
- 1.1.0 - Adds Amp Html Support
- 1.0.0 - Initial Release
The SocketLabs.EmailDelivery library and all associated code, including any code samples, are MIT Licensed.