Skip to content

Commit acc1054

Browse files
BillVolzdavid-schrenker
BillVolz
authored and
david-schrenker
committed
Initial commit
0 parents  commit acc1054

File tree

68 files changed

+6372
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

68 files changed

+6372
-0
lines changed

‎.gitignore‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
jssecacerts
2+
out
3+
repo
4+
settings.gradle
5+
target
6+
*.class
7+
.DS_Store
8+
.env
9+
.log
10+
.settings
11+
*.gpg
12+
13+
# Generated Files
14+
bin/
15+
gen/
16+
pom.xml
17+
18+
# IDE
19+
.vscode
20+
.idea
21+
.idea/
22+
*.iml
23+
.classpath
24+
.project
25+
proguard/
26+
.settings/
27+
.recommendors/
28+
29+
# Gradle
30+
.gradletasknamecache
31+
.gradle
32+
.gradle/
33+
build/
34+
bin/
35+
gradle.properties

‎CONTRIBUTING.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Contributing to 'socketlabs-java'
2+
3+
If you discover issues, have ideas for improvements or new features,
4+
please report them to the [issue tracker](https://github.com/socketlabs/socketlabs-java/issues) of the repository or
5+
submit a pull request. Please, try to follow these guidelines when you
6+
do so.
7+
8+
- [Issue Reporting](#reporting)
9+
- [Feature Requests](#feature)
10+
- [Pull Requests](#pull)
11+
12+
13+
## <a name="reporting"></a>Issue reporting
14+
15+
* Check that the issue has not already been reported.
16+
* Check that the issue has not already been fixed in the latest code
17+
(a.k.a. `master`).
18+
* Be clear, concise and precise in your description of the problem.
19+
* Open an issue with a descriptive title and a summary in grammatically correct,
20+
complete sentences.
21+
* Mention the version info.
22+
23+
## <a name="feature"></a> Want a Feature?
24+
25+
You can request a new feature by submitting an issue to our
26+
[GitHub Repository](https://github.com/socketlabs/socketlabs-java). If you would like to implement a new feature then
27+
consider what kind of change it is:
28+
29+
* **Major Changes** that you wish to contribute to the project should be
30+
discussed first with `csharp-socketlabs` contributors in an issue or pull request so
31+
that we can develop a proper solution and better coordinate our efforts,
32+
prevent duplication of work, and help you to craft the change so that it is
33+
successfully accepted into the project.
34+
* **Small Changes** can be crafted and submitted to the
35+
[GitHub Repository](https://github.com/socketlabs/socketlabs-java) as a Pull Request.
36+
37+
## <a name="pull"></a> Creating a Pull Request?
38+
39+
- Create a personal fork of the project on Github.
40+
- If you created your fork a while ago be sure to pull upstream changes into your local repository.
41+
- Create a new branch to work on! Branch from `master`.
42+
- Implement/fix your feature, comment your code.
43+
- Write or adapt tests as needed.
44+
- Add or change the documentation as needed.
45+
- Squash your commits into a single commit with git's [interactive rebase](https://help.github.com/articles/interactive-rebase). Create a new branch if necessary.
46+
- Push your branch to your fork on Github, the remote `origin`.
47+
- From your fork open a pull request with a clear title and description in grammatically correct, complete sentences.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2018 SocketLabs
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
[![SocketLabs](https://www.socketlabs.com/assets/socketlabs-logo1.png)](https://www.socketlabs.com)
2+
# [![Twitter Follow](https://img.shields.io/twitter/follow/socketlabs.svg?style=social&label=Follow)](https://twitter.com/socketlabs) [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/socketlabs/socketlabs-java/blob/master/CONTRIBUTING.md)
3+
<!--
4+
[![GitHub contributors](https://img.shields.io/github/contributors/socketlabs/socketlabs-java.svg)](https://github.com/socketlabs/socketlabs-java/graphs/contributors)
5+
-->
6+
7+
The SocketLabs Email Delivery Java library allows you to easily send email messages via the [SocketLabs Injection API](https://www.socketlabs.com/api-reference/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.
8+
9+
# Table of Contents
10+
* [Prerequisites and Installation](#prerequisites-and-installation)
11+
* [Getting Started](#getting-started)
12+
* [Managing API Keys](#managing-api-keys)
13+
* [Examples and Use Cases](#examples-and-use-cases)
14+
* [License](#license)
15+
16+
17+
<a name="prerequisites-and-installation"></a>
18+
# Prerequisites and Installation
19+
## Prerequisites
20+
* A supported Java version
21+
* Oracle JDK 7
22+
* Oracle JDK 8
23+
* OpenJDK 7
24+
* A SocketLabs account. If you don't have one yet, you can [sign up for a free account](https://signup.socketlabs.com/step-1?plan=free) to get started.
25+
26+
## Installation
27+
Choose your installation method - Maven w/ Gradle (recommended), Maven or Jar file.
28+
29+
### via Maven w/ Gradle
30+
Add the following to your build.gradle file in the root of your project.
31+
32+
```
33+
...
34+
dependencies {
35+
...
36+
compile group: 'com.socketlabs', name: 'injectionApi', version: '1.0.0'
37+
}
38+
39+
repositories {
40+
mavenCentral()
41+
}
42+
...
43+
```
44+
45+
### via Maven
46+
47+
```
48+
mvn install
49+
```
50+
51+
### via jar file
52+
53+
You can just drop the jar file in.
54+
55+
[socketlabs-java-1.0.0.jar](https://github.com/socketlabs/socketlabs-java/releases/download/1.0.0/socketlabs-java-1.0.0.jar)
56+
57+
[socketlabs-java-1.0.0-sources.jar](https://github.com/socketlabs/socketlabs-java/releases/download/1.0.0/socketlabs-java-1.0.0-sources.jar)
58+
59+
[socketlabs-java-1.0.0-javadoc.jar](https://github.com/socketlabs/socketlabs-java/releases/download/1.0.0/socketlabs-java-1.0.0-javadoc.jar)
60+
61+
Alternately, you can simply [clone this repository](https://github.com/socketlabs/socketlabs-java.git) directly to include the source code in your project.
62+
63+
<a name="getting-started"></a>
64+
# Getting Started
65+
## Obtaining your API Key and SocketLabs ServerId number
66+
In order to get started, you'll need to enable the Injection API feature in the [SocketLabs Control Panel](https://cp.socketlabs.com).
67+
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).
68+
Make note of your 4 or 5 digit ServerId number, as you'll need this along with
69+
your API key in order to use the Injection API.
70+
71+
To enable the Injection API, click on the "For Developers" dropdown on the top-level navigation, then choose the "Configure HTTP Injection API" option.
72+
Once here, you can enable the feature by choosing the "Enabled" option in the
73+
dropdown. Enabling the feature will also generate your API key, which you'll
74+
need (along with your ServerId) to start using the API. Be sure to click the
75+
"Update" button to save your changes once you are finished.
76+
77+
78+
79+
## Basic Message
80+
A basic message is an email message like you'd send from a personal email client such as Outlook.
81+
A basic message can have many recipients, including multiple To addresses, CC addresses, and even BCC addresses.
82+
You can also send a file attachment in a basic message.
83+
84+
```java
85+
import com.socketLabs.injectionApi.*;
86+
import com.socketLabs.injectionApi.message.*;
87+
88+
var client = new SocketLabsClient(000001, "YOUR-API-KEY"); //Your SocketLabs ServerId and Injection API key
89+
90+
BasicMessage message = new BasicMessage();
91+
92+
message.setSubject("Sending A Test Message (Basic Send)");
93+
message.setHtmlBody("<html><body><h1>Sending A Test Message</h1><p>This is the Html Body of my message.</p></body></html>");
94+
message.setPlainTextBody("This is the Plain Text Body of my message.");
95+
96+
message.setFrom(new EmailAddress("[email protected]"));
97+
98+
//A basic message supports up to 50 recipients and supports several different ways to add recipients
99+
100+
// Adding To Recipients
101+
message.getTo().add(new EmailAddress("[email protected]"));
102+
message.getTo().add(new EmailAddress("[email protected]", "Recipient #2"));
103+
104+
// Adding CC Recipients
105+
message.addCcEmailAddress(new EmailAddress("[email protected]", "Recipient #3" ));
106+
107+
// Adding Bcc Recipients
108+
message.addBccEmailAddress("[email protected]");
109+
message.addBccEmailAddress("[email protected]", "Recipient #2");
110+
111+
SendResponse response = client.send(message);
112+
```
113+
114+
## Bulk Message
115+
A bulk message usually contains a single recipient per message
116+
and is generally used to send the same content to many recipients,
117+
optionally customizing the message via the use of MergeData.
118+
For more information about using Merge data, please see the [Injection API documentation](https://www.socketlabs.com/api-reference/injection-api/#merging).
119+
```java
120+
121+
import com.socketLabs.injectionApi.*;
122+
import com.socketLabs.injectionApi.message.*;
123+
124+
SocketLabsClient client = new SocketLabsClient(000001, "YOUR-API-KEY"); //Your SocketLabs ServerId and Injection API key
125+
126+
BulkMessage message = new BulkMessage();
127+
128+
message.setSubject("Sending A Test Message (Bulk Send)");
129+
message.setHtmlBody("<html><body><h1>Sending A Test Message</h1><p>This is the Html Body of my message.</p></body></html>");
130+
message.setPlainTextBody("This is the Plain Text Body of my message.");
131+
132+
message.setFrom(new EmailAddress("[email protected]"));
133+
message.setReplyTo(new EmailAddress("[email protected]"));
134+
135+
message.getTo().add(new BulkRecipient("[email protected]"));
136+
message.getTo().add(new BulkRecipient("[email protected]", "Recipient #2"));
137+
message.getTo().add(new BulkRecipient("[email protected]"));
138+
message.getTo().add(new BulkRecipient("[email protected]", "Recipient #4"));
139+
140+
SendResponse response = client.send(message);
141+
```
142+
143+
<a name="managing-api-keys"></a>
144+
## Managing API Keys
145+
For ease of demonstration, many of our examples include the ServerId (SOCKETLABS_SERVER_ID) and API
146+
key (SOCKETLABS_INJECTION_API_KEY) directly in our code sample. Generally it is not considered a good practice
147+
to store sensitive information like this directly in your code. Depending on
148+
your project type, we recommend either storing your credentials using Environment Variables. For more
149+
information please see: [Using Environment Variables](https://docs.oracle.com/javase/tutorial/essential/environment/env.html)
150+
151+
<a name="examples-and-use-cases"></a>
152+
# Examples and Use Cases
153+
In order to demonstrate the many possible use cases for the SDK, we've provided
154+
an assortment of code examples. These examples demonstrate many different
155+
features available to the Injection API and SDK, including using templates
156+
created in the [SocketLabs Email Designer](https://www.socketlabs.com/blog/introducing-new-email-designer/), custom email headers, sending
157+
attachments, sending content that is stored in an HTML file, advanced bulk
158+
merging, and even pulling recipients from a datasource.
159+
160+
### [Basic send async example](https://github.com/socketlabs/socketlabs-java/tree/master/examples/src/main/java/examples/basic/BasicAsync.java)
161+
This example demonstrates a Basic Send done asynchronously.
162+
163+
### [Basic send example](https://github.com/socketlabs/socketlabs-java/tree/master/examples/src/main/java/examples/basic/BasicSend.java)
164+
This example demonstrates a Basic Send done synchronously.
165+
166+
### [Basic send complex example](https://github.com/socketlabs/socketlabs-java/tree/master/examples/src/main/java/examples/basic/BasicSendComplexExample.java)
167+
This example demonstrates many features of the Basic Send, including adding multiple recipients, adding message and mailing id's, and adding an embedded image.
168+
169+
### [Basic send from HTML file](https://github.com/socketlabs/socketlabs-java/tree/master/examples/src/main/java/examples/basic/BasicSendFromHtmlFile.java)
170+
This example demonstrates how to read in your HTML content from an HTML file
171+
rather than passing in a string directly.
172+
173+
### [Basic send from SocketLabs API Template](https://github.com/socketlabs/socketlabs-java/tree/master/examples/src/main/java/examples/basic/BasicSendWithApiTemplate.java)
174+
This example demonstrates the sending of a piece of content that was created in the
175+
SocketLabs Email Designer. This is also known as the [API Templates](https://www.socketlabs.com/blog/introducing-api-templates/) feature.
176+
177+
### [Basic send with specified character set](https://github.com/socketlabs/socketlabs-java/tree/master/examples/src/main/java/examples/basic/BasicSendWithASCIICharset.java)
178+
This example demonstrates sending with a specific character set.
179+
180+
### [Basic send with file attachment](https://github.com/socketlabs/socketlabs-java/tree/master/examples/src/main/java/examples/basic/BasicSendWithAttachment.java)
181+
This example demonstrates how to add a file attachment to your message.
182+
183+
### [Basic send with custom email headers](https://github.com/socketlabs/socketlabs-java/tree/master/examples/src/main/java/examples/basic/BasicSendWithCustomHeaders.java)
184+
This example demonstrates how to add custom headers to your email message.
185+
186+
### [Basic send with embedded image](https://github.com/socketlabs/socketlabs-java/tree/master/examples/src/main/java/examples/basic/BasicSendWithEmbeddedImage.java)
187+
This example demonstrates how to embed an image in your message.
188+
189+
### [Basic send with a web proxy](https://github.com/socketlabs/socketlabs-java/tree/master/examples/src/main/java/examples/basic/BasicSendWithProxy.java)
190+
This example demonstrates how to use a proxy with your HTTP client.
191+
192+
### [Basic send with invalid file attachment](https://github.com/socketlabs/socketlabs-java/tree/master/examples/src/main/java/examples/basic/invalid/BasicSendWithInvalidAttachment.java)
193+
This example demonstrates the results of attempting to do a send with an invalid attachment.
194+
195+
### [Basic send with invalid from address](https://github.com/socketlabs/socketlabs-java/tree/master/examples/src/main/java/examples/basic/invalid/BasicSendWithInvalidFrom.java)
196+
This example demonstrates the results of attempting to do a send with an invalid from address.
197+
198+
### [Basic send with invalid recipients](https://github.com/socketlabs/socketlabs-java/tree/master/examples/src/main/java/examples/basic/invalid/BasicSendWithInvalidRecipients.java)
199+
This example demonstrates the results of attempting to do a send with invalid recipients.
200+
201+
### [Bulk send with multiple recipients](https://github.com/socketlabs/socketlabs-java/tree/master/examples/src/main/java/examples/bulk/BulkSend.java)
202+
This example demonstrates how to send a bulk message to multiple recipients.
203+
204+
### [Bulk send with complex merge including attachments](https://github.com/socketlabs/socketlabs-java/tree/master/examples/src/main/java/examples/bulk/BulkSendComplexExample.java)
205+
This example demonstrates many features of the `BulkMessage()`, including
206+
adding multiple recipients, merge data, and adding an attachment.
207+
208+
### [Bulk send with recipients pulled from a datasource](https://github.com/socketlabs/socketlabs-java/tree/master/examples/src/main/java/examples/bulk/BulkSendFromDataSourceWithMerge.java)
209+
This example uses a mock repository class to demonstrate how you would pull
210+
your recipients from a database and create a bulk mailing with merge data.
211+
212+
### [Bulk send with Ascii charset and special characters](https://github.com/socketlabs/socketlabs-java/tree/master/examples/src/main/java/examples/bulk/BulkSendWithASCIICharsetMergeData.java)
213+
This example demonstrates how to send a bulk message with a specified character
214+
set and special characters.
215+
216+
### [Bulk send with merge data](https://github.com/socketlabs/socketlabs-java/tree/master/examples/src/main/java/examples/bulk/BulkSendWithMergeData.java)
217+
This example demonstrates how to send a bulk message to multiple recipients with
218+
unique merge data per recipient.
219+
220+
221+
<a name="license"></a>
222+
# License
223+
The SocketLabs.EmailDelivery library and all associated code, including any code samples, are [MIT Licensed](https://github.com/socketlabs/socketlabs-java/blob/master/LICENSE.MD).

‎examples/build.gradle‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
plugins {
2+
id 'java'
3+
}
4+
5+
group 'socketlabs-java-examples'
6+
version '1.0-SNAPSHOT'
7+
8+
sourceCompatibility = 1.8
9+
10+
repositories {
11+
mavenCentral()
12+
//mavenLocal()
13+
//maven {
14+
// url "${nexusUrl}/repository/maven-releases/"
15+
//}
16+
17+
}
18+
19+
dependencies {
20+
testCompile group: 'junit', name: 'junit', version: '4.12'
21+
compile group: 'com.fasterxml.jackson.core', name: 'jackson-core', version: '2.9.2'
22+
compile group: 'com.fasterxml.jackson.core', name: 'jackson-databind', version: '2.0.2'
23+
compile group: 'com.socketlabs', name: 'injectionApi', version: '1.0.0'
24+
}

‎examples/gradle/wrapper/gradle-wrapper.jar‎

53.1 KB
Binary file not shown.

‎examples/gradle/wrapper/gradle-wrapper.properties‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
distributionBase=GRADLE_USER_HOME
2+
distributionPath=wrapper/dists
3+
distributionUrl=https\://services.gradle.org/distributions/gradle-4.8-bin.zip
4+
zipStoreBase=GRADLE_USER_HOME
5+
zipStorePath=wrapper/dists

0 commit comments

Comments
 (0)