sendgrid-java

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

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

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

sendgrid.send();

Installation

There are multiple ways to install this library. I recommend using Gradle.

via Gradle (recommended)

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

...

repositories {
  mavenCentral()
  add(new org.apache.ivy.plugins.resolver.URLResolver()) {
    name = 'GitHub'
    addArtifactPattern 'https://github.com/sendgrid/sendgrid-java/raw/v[revision]/repo/com/github/sendgrid/[revision]/sendgrid-[revision]-jar.jar'
  }
}
dependencies {
  ...
  compile 'com.github.sendgrid:sendgrid:0.1.2'
}

...

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

import com.github.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-0.1.2-jar.jar

via copy/paste

Include the SendGrid.java library

Copy and paste the SendGrid.java file into your project. That file is available here: https://github.com/sendgrid/sendgrid-java/blob/master/src/main/java/com/github/sendgrid/SendGrid.java

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

import com.github.sendgrid.SendGrid;

Include the required dependencies

• You need to include the http-request library from kevinsawicki.
• You need to include the json library from chargebee

via Maven

I'd like to get this on Maven. Please +1 your support if you'd like to see it on Maven as well.

Example App

There is a sendgrid-java-example app to help jumpstart your development.

Usage

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

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

Add your message details.

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

Send it.

sendgrid.send();

To

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

You can add multiple tos as necessary. She will get the email as if it was sent solely to her.

To Name

SendGrid sendgrid = new SendGrid("sendgrid_username", "sendgrid_password");
sendgrid.addTo("[email protected]");
sendgrid.addToName("Example Guy");
sendgrid.addTo("[email protected]");
sendgrid.addToName("Other Gal");

You can add multiple tonames as necessary. They should be set in the same array order as the emails.

From

SendGrid sendgrid = new SendGrid("sendgrid_username", "sendgrid_password");
sendgrid.addTo("[email protected]");
...
sendgrid.setFrom("[email protected]");

From Name

SendGrid sendgrid = new SendGrid("sendgrid_username", "sendgrid_password");
sendgrid.addTo("[email protected]");
...
sendgrid.setFrom("[email protected]");
sendgrid.setFromName("Other Dude");

Reply To

SendGrid sendgrid = new SendGrid("sendgrid_username", "sendgrid_password");
sendgrid.addTo("[email protected]");
...
sendgrid.setReplyTo("[email protected]");

Subject

SendGrid sendgrid = new SendGrid("sendgrid_username", "sendgrid_password");
sendgrid.addTo("[email protected]");
...
sendgrid.setSubject("Hello World");

Text

SendGrid sendgrid = new SendGrid("sendgrid_username", "sendgrid_password");
sendgrid.addTo("[email protected]");
...
sendgrid.setText("This is some text of the email.");

Html

SendGrid sendgrid = new SendGrid("sendgrid_username", "sendgrid_password");
sendgrid.addTo("[email protected]");
...
sendgrid.setHtml(<h1>My first email through SendGrid");

Attachments

import java.io.File;
SendGrid sendgrid = new SendGrid("sendgrid_username", "sendgrid_password");
sendgrid.addTo("[email protected]");
...
sendgrid.addFile(new File("../path/to/file.txt"));

If you need to add files from an InputStream (maybe you're on Google App Engine and have the contents in a byte array), here is how.

import java.io.ByteArrayInputStream;
 
SendGrid sendgrid = new SendGrid("sendgrid_username", "sendgrid_password");
sendgrid.addTo("[email protected]");
...
byte[] contents = somehowGenerateAttachmentContents();

SendGrid.Attachment attachment1 = new SendGrid.Attachment("filename.txt", new ByteArrayInputStream(contents));
sendgrid.addFile(attachment1);

sendgrid.send();

Bcc

Use multiple addTos as a superior alternative to setBcc.

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

If you still absolutely need to use Bcc, you can use sendgrid.addBcc("[email protected]");

Headers

You can add custom headers.

SendGrid sendgrid = new SendGrid("sendgrid_username", "sendgrid_password");
sendgrid.addTo("[email protected]");
...
sendgrid.addHeader("X-Sent-Using", "SendGrid-API");
sendgrid.addHeader("X-Transport", "web");

To add SendGrid style headers for things such as categories or filters, do the following.

SendGrid sendgrid = new SendGrid("sendgrid_username", "sendgrid_password");
sendgrid.addTo("[email protected]");
...
sendgrid.addHeader("X-SMTPAPI", "{\"category\":\"My New Category\"}");

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:

gradle build

Generating the jar

gradle build

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

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. The example below is a spring based application.

github.com/scottmotte/spring-attack

License

Licensed under the MIT License.