Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
SendGrid Java helper library
Java PHP Shell

README.md

SendGrid-Java

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

BuildStatus

Warning

Version 2.x.x, behaves differently in the addTo method. In the past this method defaulted to using the SMTPAPI header. Now you must explicitly call the addSmtpApiTo method. More on the SMTPAPI section.

// SendGridExample.java
import com.sendgrid.*;

public class SendGridExample {
  public static void main(String[] args) {
    SendGrid sendgrid = new SendGrid("SENDGRID USERNAME", "SENDGRID_PASSWORD");

    SendGrid.Email email = new SendGrid.Email();
    email.addTo("example@example.com");
    email.setFrom("other@example.com");
    email.setSubject("Hello World");
    email.setText("My first email with SendGrid Java!");

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

Compile and run this example with

$ javac -classpath sendgrid-2.2.1-jar.jar:. SendGridExample.java && java -classpath sendgrid-2.2.1-jar.jar:. SendGridExample

Installation

Choose your installation method - Maven w/ Gradle (recommended), Maven 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:2.2.1'
}

repositories {
  mavenCentral()
}
...

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

import com.sendgrid.SendGrid;

via Maven

mvn install

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 OR a SendGrid API Key. API Key is the preferred method. API Keys are in beta. To configure API keys, visit https://sendgrid.com/beta/settings/api_keys.

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

Add your message details.

Email email = new Email();
email.addTo("example@example.com");
email.addToName("Example Guy");
email.setFrom("other@example.com");
email.setSubject("Hello World");
email.setText("My first email through SendGrid");

Send it.

sendgrid.send(email);

To

addTo

email.addTo("foo@example.com");
// or
email.addTo(new String[]{"foo@other.com", "bar@other.com"});
// or
email.addTo("foo.bar@other.com", "Foo Bar");

setTo

email.setTo(new String[]{"foo@other.com", "bar@other.com"});

addToName

email.addToName("Foo");
// or
email.addToName(new String[]{"Foo", "Bar"});

setToName

email.setToName(new String[]{"Foo", "Bar"});

addCc

email.addCc("foo@example.com");
// or
email.addCc(new String[]{"foo@other.com", "bar@other.com"});

setCc

email.setCc(new String[]{"foo@other.com", "bar@other.com"});

addBcc

email.addBcc("foo@example.com");
// or
email.addBcc(new String[]{"foo@other.com", "bar@other.com"});

setBcc

email.setBcc(new String[]{"foo@other.com", "bar@other.com"});

From

setFrom

email.setFrom("other@example.com");

setFromName

email.setFromName("Other Dude");

setReplyTo

email.setReplyTo("no-reply@nowhere.com");

setSubject

email.setSubject("Hello World");

setText

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

setHtml

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

Attachments

addAttachment

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")));

Content IDs

addContentId

// First, add an attachment
email.addAttachment("image.png", new File("./image.png"));
// Map the name of the attachment to an ID
email.addContentId("image.png", "ID_IN_HTML")
// Map the ID in the HTML
email.setHtml("<html><body>TEXT BEFORE IMAGE<img src=\"cid:ID_IN_HTML\"></img>AFTER IMAGE</body></html>")

Proxy Server Setup

SendGrid sendgrid = new SendGrid("SENDGRID USERNAME", "SENDGRID_PASSWORD");
HttpHost proxy = new HttpHost("server", 3128);
CloseableHttpClient http = HttpClientBuilder.create().setProxy(proxy).setUserAgent("sendgrid/" + sendgrid.getVersion() + ";java").build();
sendgrid.setClient(http);

X-SMTPAPI

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

email.getSMTPAPI();

Recipients

addSmtpApiTo

email.addSmtpApiTo("foo@example.com");
// or
email.addSmtpApiTo(new String[]{"foo@other.com", "bar@other.com"});

Substitutions

addSubstitution

email.addSubstitution("key", "value");

JSONObject subs = header.getSubstitutions();

setSubstitutions

email.setSubstitutions("key", new String[]{"value1", "value2"});

JSONObject subs = header.getSubstitutions();

Unique Arguments

addUniqueAarg

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

JSONObject args = email.getUniqueArgs();

Categories

addCategory

email.addCategory("category");

String[] cats = email.getCategories();

Sections

addSection

email.addSection("key", "section");

JSONObject sections = email.getSections();

Filters / Apps

You can enable and configure Apps.

addFilter

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

JSONObject filters = email.getFilters();

Example enabling bcc app:

SendGrid sendgrid = new SendGrid("sendgrid_username", "sendgrid_password");
sendgrid.addTo("example@example.com");
...
sendgrid.addFilter("bcc", "enabled", 1);
sendgrid.addFilter("bcc", "email", "example@example.com");

ASM - Advanced Supression Manager

setASMGroupId

email.setASMGroupId(1);

Schedule Sending

setSendAt

email.setSendAt(1409348513);

Templates

setTemplateId

email.setTemplateId("abc123-def456");

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

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.

Something went wrong with that request. Please try again.