We have released a v3 beta branch for this library that supports our new v3 Mail Send endpoint which is in open beta. The v3/mail/send/beta endpoint is not a production endpoint, so you should not integrate with it for your production email sending. However, when we make this an officially released feature it will be available at v3/mail//send.
Please try it out and let us know what you think about the endpoint and the library in the issues area of this repo, all of your feedback will be taken into account to influence the endpoint and this library.
Beginning with v3/mail/send/beta, the new version of our library will only support v3 endpoints. Once this endpoint is out of beta, we will update the endpoint, removing the “/beta” from the URI. At this point, the v3 beta branch will be merged to master and will be our official library going forward. This means that we will no longer formally support the v2 mail.send.json endpoint in any of our libraries.
So long as you are not automatically pulling new versions of the library into your production code base, your integration will not break regardless of which endpoint you’re using. By the way, don't pull new versions into your production code base, because breaking changes break things.
The /api/mail.send.json endpoint, known as v2 mail send, is NOT going away. It will continue to work as it always has, happily sending your emails along as if nothing happened.
This Java module allows you to quickly and easily send emails through SendGrid using Java.
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('YOUR_SENDGRID_API_KEY');
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:. SendGridExampleChoose 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 '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;mvn install
You can just drop the jar file in. It's a fat jar - it has all the dependencies built in.
import com.sendgrid.*;To begin using this library, initialize the SendGrid object with your SendGrid API Key. To configure API keys, visit https://sendgrid.com/docs/API_Reference/Web_API_v3/API_Keys/index.html.
import com.sendgrid.SendGrid;
SendGrid sendgrid = new SendGrid('YOUR_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);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");email.setTo(new String[]{"foo@other.com", "bar@other.com"});email.addToName("Foo");
// or
email.addToName(new String[]{"Foo", "Bar"});email.setToName(new String[]{"Foo", "Bar"});email.addCc("foo@example.com");
// or
email.addCc(new String[]{"foo@other.com", "bar@other.com"});email.setCc(new String[]{"foo@other.com", "bar@other.com"});email.addBcc("foo@example.com");
// or
email.addBcc(new String[]{"foo@other.com", "bar@other.com"});email.setBcc(new String[]{"foo@other.com", "bar@other.com"});email.setFrom("other@example.com");email.setFromName("Other Dude");email.setReplyTo("no-reply@nowhere.com");email.setSubject("Hello World");email.setText("This is some text of the email.");email.setHtml("<h1>My first email through SendGrid");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")));// 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>")SendGrid sendgrid = new SendGrid('YOUR_SENDGRID_API_KEY');
HttpHost proxy = new HttpHost("server", 3128);
CloseableHttpClient http = HttpClientBuilder.create().setProxy(proxy).setUserAgent("sendgrid/" + sendgrid.getVersion() + ";java").build();
sendgrid.setClient(http);The mail object extends the SMTPAPI object which is found in SMTPAPI-Java.
email.getSMTPAPI();email.addSmtpApiTo("foo@example.com");
// or
email.addSmtpApiTo(new String[]{"foo@other.com", "bar@other.com"});email.addSubstitution("key", "value");
JSONObject subs = header.getSubstitutions();email.setSubstitutions("key", new String[]{"value1", "value2"});
JSONObject subs = header.getSubstitutions();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();email.addCategory("category");
String[] cats = email.getCategories();email.addSection("key", "section");
JSONObject sections = email.getSections();You can enable and configure Apps.
email.addFilter("filter", "setting", "value");
email.addFilter("filter", "setting", 1);
JSONObject filters = email.getFilters();Example enabling bcc app:
SendGrid sendgrid = new SendGrid('YOUR_SENDGRID_API_KEY');
sendgrid.addTo("example@example.com");
...
sendgrid.addFilter("bcc", "enabled", 1);
sendgrid.addFilter("bcc", "email", "example@example.com");email.setASMGroupId(1);email.setSendAt(1409348513);email.setTemplateId("abc123-def456");- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Added some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request
The existing tests in the src/test directory can be run using gradle with the following command:
$ ./gradlew test -i$ ./gradlew buildWe 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
Licensed under the MIT License.