SendGrid-Java

This Java module allows you to quickly and easily send emails through SendGrid using Java.

import com.sendgrid.*;
SendGrid sendgrid = new SendGrid("sendgrid_username", "sendgrid_password");

SendGrid.Email email = new SendGrid.Email();
email.addTo("[email protected]");
email.setFrom("[email protected]");
email.setSubject("Hello World");
email.setText("My first email through SendGrid");

try {
  SendGrid.Response response = sendgrid.send(email);
catch (SendGridException e) {
  System.out.println(e);
}

Installation

Choose your installation method - Maven w/ Gradle (recommended) or Jar file.

via Maven w/ Gradle

Add the following to your build.gradle file in the root of your project.

...
dependencies {
  ...
  compile 'com.sendgrid:sendgrid-java:1.1.0'
}

repositories {
  mavenCentral()
}
...

Then import the library - in the file appropriate to your Java project.

import com.sendgrid.SendGrid;

via jar file

You can just drop the jar file in. It's a fat jar - it has all the dependencies built in.

sendgrid-java.jar

import com.sendgrid.*;

Usage

To begin using this library, initialize the SendGrid object with your SendGrid credentials.

import com.sendgrid.SendGrid;
SendGrid sendgrid = new SendGrid("sendgrid_username", "sendgrid_password");

Add your message details.

Email email = new Email();
email.addTo("[email protected]");
email.addToName("Example Guy");
email.setFrom("[email protected]");
email.setSubject("Hello World");
email.setText("My first email through SendGrid");

Send it.

sendgrid.send(email);

To

email.addTo("[email protected]");
// or
email.setTos(["[email protected]"]);

From

email.setFrom("[email protected]");

From Name

email.setFromName("Other Dude");

Reply To

email.setReplyTo("[email protected]");

Subject

email.setSubject("Hello World");

Text

email.setText("This is some text of the email.");

Html

email.setHtml("<h1>My first email through SendGrid");

Attachments

email.addAttachment("text.txt", "contents");
// or
email.addAttachment("image.png", new File("./image.png"));
// or
email.addAttachment("text.txt", new InputStream(new File("./file.txt")));

X-SMTPAPI

The mail object extends the SMTPAPI object which is found in STMAPI-Java.

Substitutions

header.addSubstitution("key", "value");
// or
header.setSubstitutions("key", ["value1", "value2"]);

JSONObject subs = header.getSubstitutions();

Unique Arguments

header.addUuniqueAarg("key", "value");
// or
Map map = new HashMap<String, String>();
map.put("unique", "value");
header.setUniqueArgs(map);
// or
JSONObject map = new JSONObject();
map.put("unique", "value");
header.setUniqueArgs(map);

JSONObject args = header.getUniqueArgs();

Categories

header.addCategory("category");
// or
header.addCategory(["categories"]);
// or
header.setCategories(["category1", "category2"]);

String[] cats = header.getCategories();

Sections

header.addSection("key", "section");
// or
Map newSec = new HashMap();
newSec.put("-section-", "value");
header.setSections(newSec);
// or
JSONObject newSec = new JSONObject();
newSec.put("-section-", "value");
header.setSections(newSec);

JSONObject sections = header.getSections();

Filters

header.addFilter("filter", "setting", "value");
header.addFilter("filter", "setting", 1);

JSONObject filters = header.getFilters();

Get Headers

String headers = header.jsonString();

Filters/Apps

You can enable and configure Apps.

SendGrid sendgrid = new SendGrid("sendgrid_username", "sendgrid_password");
sendgrid.addTo("[email protected]");
...
sendgrid.addFilter("bcc", "enabled", 1);
sendgrid.addFilter("bcc", "email", "[email protected]");

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Running Tests

The existing tests in the src/test directory can be run using gradle with the following command:

./gradlew test -i

Generating the jar

./gradlew build

(If you don't have gradle install it. If on a mac, you can run brew install gradle)

Publishing to Maven

This only works if you have the correct permissions - for admins only basically.

Let's begin with the permissions.

cp gradle.properties.example ~/.gradle/gradle.properties

Edit that file and set your sonatypeUsername and sonatypePassword`. You also need to set the values for your keys. Here's how to list/create them. 1.

gpg --list-keys
gpg --gen-key

Set the signing.KeyId, signing.password, and the signing.secretKeyRingFile.

The signing.KeyId is the 'pub' one. It's the part of your list of keys that looks something like this: 2048R/5D64A177. So in this scenario it would be 5D64A177. 1 2

The signing.password is the password you used when generating this key. It could be blank if you didn't use a password.

The signing.secretKeyRingFile is the path to the secring.gpg.

Now, upload that key to the keyserver.

gpg --keyserver hkp://pool.sks-keyservers.net --send-keys 5D64A177

Now, you can finally upload! Ah, Java!

./gradlew uploadArchives

Login to Sonatype.

Go to staging repositories page.

Click 'Close' with the archive selected.

Wait a few minutes, and refresh the staging repositories page.

Check the box for the SendGrid repo again and this time click 'Release'.

You're all done.

Further help.

Example App

We have an example app using this library. This can be helpful to get a grasp on implementing it in your own app.

github.com/scottmotte/sendgrid-java-example

License

Licensed under the MIT License.