sendgrid-java

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

License

Licensed under the MIT License.

Downloading

Installing the SendGrid package is as simple as adding it to your project's include path. If you're using git, you can just clone down the repo like this:

git clone [email protected]:sendgrid/sendgrid-google-java.git

Note: If you don't have git or would rather install by unpacking a Zip or Tarball, you can always grab the latest version of the package from the downloads page.

SendGrid API

SendGrid provides SendGrid library for sending email.

Mail Pre-Usage

Before we begin using the library, its important to understand a few things about the library architecture...

• The SendGrid object is the means of setting mail data. In general, data can be set in three ways for most elements:

  1. set - reset the data, and initialize it to the given element. This will destroy previous data
  2. set (List) - for array based elements, we provide a way of passing the entire array in at once. This will also destroy previous data.
  3. add - append data to the list of elements.

• Sending an email is as simple as :

  1. Creating a SendGrid object, and setting its data
  2. Sending the mail.

Mail Usage

To begin using this library, you must first include it

import packageName.Sendgrid;

Then, initialize the SendGrid object with your SendGrid credentials

Sendgrid mail = new Sendgrid("<sendgrid_username>","<sendgrid_password>");

Headers are enabled by default. If you do not want to use headers, the use_headers variable must be set to false

mail.use_headers = false;

Create a new SendGrid object and add your message details

mail.setTo("[email protected]")
    .setFrom("[email protected]")
    .setSubject("Subject goes here")
    .setText("Hello World!")
    .setHtml("<strong>Hello World!</strong>");

Send the email

mail.send();

Using Categories

You can mark messages with optional categories to give better visibility to email statistics (opens, clicks, etc.). You can add up to 10 categories per email message. You can read more about Categories here: http://docs.sendgrid.com/documentation/delivery-metrics/categories/

To add categories to your message, use the mail.addCategory() method and pass a category as parameter or mail.setCategories() and pass a list of category names. SendGrid will begin tracking statistics with these category names if the category name is new, or aggregate statistics for existing category names.

mail.addTo("[email protected]")
    ...
    .addCategory("Category 1")
    .addCategory("Category 2");

mail.addTo("[email protected]")
    ...
    .setCategories(new String[]{"Category 1","Category 2","Category 3"});

Using Substitutions

SendGrid also allows you to send multi-recipient messages with unique information per recipient. This is commonly used for sending unique URLs or codes to a list of recipients in a single batch. You can read more about Substitutions here: http://docs.sendgrid.com/documentation/api/smtp-api/developers-guide/substitution-tags/

mail.addTo("[email protected]")
    .addTo("[email protected]")
    .addTo("[email protected]")
    ...
    .setHtml("Hey %name%, we've seen that you've been gone for a while")
    .addSubstitution("%name%", new String[]{"John", "Harry", "Bob"});

Using Sections

Used in conjunction with Substitutions, Sections can be used to further customize messages for the end users, and acts like a second tier of substitution data. You can use mail.addSection() to add a single section, or mail.setSections() method to add several sections. You can read more about using Sections here: http://docs.sendgrid.com/documentation/api/smtp-api/developers-guide/section-tags/

mail.addTo("[email protected]")
    .addTo("[email protected]")
    .addTo("[email protected]")
    ...
    .setHtml("Hey %name%, you work at %place%")
    .addSubstitution("%name%", new String[]{"John", "Harry", "Bob"})
    .addSubstitution("%place%", new String[]{"%office%", "%office%", "%home%"})
    .addSection("%office%", "an office")
    .addSection("%home%", "your house");

Using Unique Arguments

Unique Arguments are used for tracking purposes on the message, and can be seen in the Email Activity screen on your account dashboard or through the Event API. Use the mail.addUniqueArgument() method, which takes two parameters, a key and a value. To pass multiple keys/values, use mail.setUniqueArguments() and pass a dictionary of key/value pairs. More information can be found here: http://docs.sendgrid.com/documentation/api/smtp-api/developers-guide/unique-arguments/

mail.addTo("[email protected]")
    ...
    .addUniqueArgument("Customer", "Someone")
    .addUniqueArgument("location", "Somewhere");

Using Filter Settings

Filter Settings are used to enable and disable apps, and to pass parameters to those apps. You can read more here: http://docs.sendgrid.com/documentation/api/smtp-api/filter-settings/ Here's an example of passing content to the 'footer' app:

mail.addTo("[email protected]")
    ...
    .addFilterSetting("footer", "enable", "1")
    .addFilterSetting("footer", "text/plain", "Here is a plain text footer")
    .addFilterSetting("footer", "text/html", "<p style='color:red;'>Here is an HTML footer</p>");