JarCastingSendGrid Java Bindings
This library allows Java developers to easily send emails through SendGrid and programmatically manage their SendGrid accounts.
Visit https://sendgrid.com to create a SendGrid account.
Requirements
Java 1.6 and later.
Installation
Maven
Add this dependency to your project's POM:
<dependency>
<groupId>com.revinate</groupId>
<artifactId>sendgrid-java</artifactId>
<version>3.0.6</version>
</dependency>
Gradle
Add this dependency to your project's build script:
compile 'com.revinate:sendgrid-java:3.0.6'
Usage
Quick start
// SendGridExample.java
import com.revinate.sendgrid.SendGrid;
import com.revinate.sendgrid.exception.*;
import com.revinate.sendgrid.model.*;
public class SendGridExample {
public static void main(String[] args) {
SendGrid sendGrid = SendGrid.create("API_KEY").build();
Email email = new Email();
email.addTo("[email protected]");
email.setFrom("[email protected]");
email.setSubject("Hello World");
email.setText("My first email with SendGrid Java.");
try {
Response response = sendGrid.mail().send(email);
System.out.println(response);
} catch (SendGridException e) {
e.printStackTrace();
}
}
}
Initializing the library
To use this library, first create a new SendGrid object with your SendGrid API key:
SendGrid sendGrid = SendGrid.create("API_KEY").build();
If you don't have an API key, you can use your SendGrid username and password instead. You'll see how to create an API key using this library later in this document.
SendGrid sendGrid = SendGrid.create("USERNAME", "PASSWORD").build();
Behind the scenes, this library connects to the SendGrid APIs via HTTP. You can optionally specify the size of the HTTP connection pool:
SendGrid sendGrid = SendGrid.create("API_KEY").setMaxConnections(100).build();
Alternatively, you can supply your own HttpComponents CloseableHttpClient. This is useful, for example, if you want to specify a proxy server:
HttpHost proxy = new HttpHost("server", 8000);
CloseableHttpClient client = HttpClients.custom().setProxy(proxy).setUserAgent(SendGrid.USER_AGENT).build();
SendGrid sendGrid = SendGrid.create("API_KEY").setHttpClient(client).build();
Using the library
The SendGrid object has a number of methods, each corresponding to a resource you can interact with. Examples of resources are API keys, subusers, and IPs. Methods on a resource correspond to the operations you can perform on that resource. Common operations include:
list- retrieve all entities under this resource in your accountcreate- add a new entity under this resource to your account
For example:
List<ApiKey> apiKeys = sendGrid.apiKeys().list();
ApiKey apiKey = new ApiKey("My API Key");
ApiKey result = sendGrid.apiKeys().create(apiKey);
Some resources have subresources nested under them. Resources that correspond to a collection of entities, such as the API keys resource, each have a subresource that corresponds to a single entity in the collection. These collection-type resources have an entity method that returns the subresource. The entity method takes a single argument, which can be either the entity identifier or the entity itself. For example:
sendGrid.apiKeys().entity("api.key.id");
The SendGrid object also has some convenience methods that return some subresources directly, for example:
sendGrid.apiKey("api.key.id");
Common operations for resources that correspond to single entities include:
retrieve- retrieve the entityupdate- update the entitypartialUpdate- update some fields of the entitydelete- delete the entity from your account
For example:
ApiKey apiKey = sendGrid.apiKey("api.key.id").retrieve();
sendGrid.apiKey(apiKey).delete();
Not every resource support all of the above operations. And some resources support additional operations or have additional subresources. More detailed examples of performing operations on each resource supported by this library can be found later in this document.
Acting on behalf of subusers
If the library was initialized with the credentials of a parent SendGrid account, it's possible to use the same SendGrid object to perform operations on behalf of any of the subusers under the parent account. This is useful, for example, if you would like to create some API keys for a newly created subuser. For certain API operations, such as adding an IP to a subuser's IP pool, it is necessary to use the parent account credentials to initialize the library and invoke the operations on behalf of the subuser.
To act on behalf of a subuser, call onBehalfOf("SUBUSERNAME") on the SendGrid object before invoking the action. For example:
ApiKey apiKey = new ApiKey("Subuser API Key");
ApiKey result = sendGrid.onBehalfOf("subuser1").apiKeys().create(apiKey);
List<ApiKey> apiKeys = sendGrid.onBehalfOf("subuser1").apiKeys().list();
sendGrid.onBehalfOf("subuser1").apiKey(result).delete();
Sending email
Email email = new Email();
email.addTo("[email protected]", "Example User");
email.setFrom("[email protected]", "Test User");
email.setSubject("Hello Again");
email.setText("My second email with SendGrid Java.");
sendGrid.mail().send(email);
Email fields
Many methods are available on the Email object to set the fields of the email:
Recipients
email.addTo("[email protected]");
email.addToName("Example User");
email.addTo("[email protected]", "Example User");
email.setTos(Arrays.asList("[email protected]", "[email protected]"));
email.setToNames(Arrays.asList("Example One", "Example Two"))
email.addCc("[email protected]");
email.addCc("[email protected]", "Example User");
email.addBcc("[email protected]");
email.addBcc("[email protected]", "Example User");
Sender
email.setFrom("[email protected]");
email.setFromName("Test User");
email.setFrom("[email protected]", "Test User");
email.setReplyTo("[email protected]");
Subject
email.setSubject("Hello World");
Contents
email.setText("This is some text of the email.");
email.setHtml("<h1>This is some text of the email.</h1>");
Attachments
email.setAttachment("text.txt", "contents");
email.setAttachment("image.png", new File("./image.png"));
email.setAttachment("document.pdf", new InputStream(new File("./document.pdf")));
Content IDs
Attachments can be inlined in the email using content IDs:
email.setAttachment("image.png", new File("./image.png"), "ID_IN_HTML");
email.setHtml("<html><body><img src=\"cid:ID_IN_HTML\"></img></body></html>")
Custom SMTP headers
email.setHeader("x-custom-header-1", "example");
SendGrid SMTP API
The Email object implements the SendGrid SMTP API interface and supports all the SMTP API operations. For the full list of supported operations, refer to the SendGrid SMTP API Java Bindings project.
Template ID
The template filter can be configured with a template ID using the following convenience method:
email.setTemplateId("abc123-def456");
Managing API keys
// retrieve existing API keys
List<ApiKey> apiKeys = sendGrid.apiKeys().list();
// retrieve a single API key
ApiKey existing = sendGrid.apiKey("api.key.id").retrieve();
// create new API key, the result contains the API key value
ApiKey apiKey = new ApiKey("Mail API Key");
apiKey.addScope("mail.send");
ApiKey result = sendGrid.apiKeys().create(apiKey);
// update API key
result.addScope("stats.read");
sendGrid.apiKey(result).update(result);
// partially update API key
Map<String, String> request = Collections.singletonMap("name", "Mail and Stats API Key");
sendGrid.apiKey(result).partialUpdate(request);
// delete API key
sendGrid.apiKey(result).delete();
Managing subusers
// retrieve existing subusers
List<Subuser> subusers = sendGrid.subusers().list();
// create new subuser
Subuser subuser = new Subuser("subuser1", "[email protected]", "secretpassword");
subuser.addIp("127.0.0.1");
sendGrid.subusers().create(subuser);
// create subuser monitor
Monitor monitor = new Monitor("[email protected]", 5000);
sendGrid.subuser("subuser1").monitor().create(monitor);
// delete subuser monitor
sendGrid.subuser("subuser1").monitor().delete();
// delete subuser
sendGrid.subuser("subuser1").delete();
Managing IPs and IP pools
// retrieve existing IPs
List<Ip> ips = sendGrid.ips().list();
Ip ip = ips.get(0);
// retrieve existing IP pools under the subuser
List<IpPool> pools = sendGrid.onBehalfOf("subuser1").ipPools().list();
// create new IP pool for subuser
IpPool pool = new IpPool("transactional");
sendGrid.onBehalfOf("subuser1").ipPools().create(pool);
// add IP to IP pool
sendGrid.onBehalfOf("subuser1").ipPool(pool).ips().create(ip);
// remove IP from IP pool
sendGrid.onBehalfOf("subuser1").ipPool(pool).ip(ip).delete();
// delete IP pool
sendGrid.onBehalfOf("subuser1").ipPool(pool).delete();
Managing domain whitelabels
// create new domain whitelabel
Whitelabel whitelabel = new Whitelabel("email.com", "em");
whitelabel.setAutomaticSecurity(true);
whitelabel.setDefault(true);
Whitelabel result = sendGrid.domainWhitelabels().create(whitelabel);
// validate domain whitelabel
WhitelabelValidation validation = sendGrid.domainWhitelabel(result).validate();
Managing link whitelabels
// create new link whitelabel
Whitelabel whitelabel = new Whitelabel("email.com", "click");
whitelabel.setDefault(true);
Whitelabel result = sendGrid.linkWhitelabels().create(whitelabel);
// validate link whitelabel
WhitelabelValidation validation = sendGrid.linkWhitelabel(result).validate();
Managing mail settings
// retrieve all mail settings
List<MailSetting> settings = sendGrid.mailSettings().list();
// update spam forwarding setting
MailSetting setting = new MailSetting("forward_spam", true, "[email protected]");
sendGrid.mailSetting(setting).update(setting);
Managing event webhook settings
EventWebhookSettings settings = new EventWebhookSettings("http://event.webhook.receiver", true);
sendGrid.eventWebhookSettings().update(settings);
Retrieving account reputation
Account parentAccount = sendGrid.account().retrieve();
Account subuserAccount = sendGrid.onBehalfOf("subuser1").account().retrieve();
Testing
The tests in the src/test directory can be run using Gradle with the following command:
$ ./gradlew test
The tests in the file ApiTest.java are designed to be run against the live SendGrid API. They are disabled unless a environment variable named SENDGRID_API_KEY is set. To enable these tests, set the SENDGRID_API_KEY environment variable to your SendGrid API key before runing the Gradle task. Caution: these tests make several assumptions about the state of your SendGrid account and perform many modifications to the account. They should not be enabled unless you have a thorough understanding of the actions they perform, and have made adjustments to the tests to allow them to work with your live account.
License
This library is under the MIT License.
