Email API Quickstart for Java

Be sure to perform the following prerequisites to complete this tutorial. You can skip ahead if you've already completed these tasks.

1. Sign up for a SendGrid account.
2. Enable Two-factor authentication.
3. Create and store a SendGrid API Key with Mail Send > Full Access permissions.
4. Complete Domain Authentication.
5. Install Java.

When you sign up for a free SendGrid account, you'll be able to send 100 emails per day forever. For more account options, see our pricing page.

Twilio SendGrid requires customers to enable Two-factor authentication (2FA). You can enable 2FA with SMS or by using the Authy app. See the 2FA section of our authentication documentation for instructions.

Unlike a username and password — credentials that allow access to your full account — an API key is authorized to perform a limited scope of actions. If your API key is compromised, you can also cycle it (delete and create another) without changing your other account credentials.

Visit our API Key documentation for instructions on creating an API key and storing an API key in an environment variable. To complete this tutorial, you can create a Restricted Access API key with Mail Send > Full Access permissions only, which will allow you to send email and schedule emails to be sent later. You can edit the permissions assigned to an API key later to work with additional services.

To ensure our customers maintain the best possible sender reputations and to uphold legitimate sending behavior, we require customers to verify their Sender Identities by completing Domain Authentication. A Sender Identity represents your 'From' email address—the address your recipients see as the sender of your emails.

If you do not already have a version of Java installed, visit the Java website to download and install a version appropriate for your operating system.

Check your Java version by opening your terminal (also known as a command line or console) and typing the following command.

java -version

If you have Java installed, the terminal should print something like the following output.

1
java version "16.0.2" 2021-07-20
2
Java(TM) SE Runtime Environment (build 16.0.2+7-67)
3
Java HotSpot(TM) 64-Bit Server VM (build 16.0.2+7-67, mixed mode, sharing)

Using a Twilio SendGrid helper library is the fastest way to deliver your first email.

Start by creating a project folder for this app. You can name the project anything you like.

To avoid writing your API key in your Java code, it is best to store it as an environment variable. That way you can share your code without exposing an API key that would give access to your SendGrid account. IntelliJ and Eclipse can manage environment variables for you, or you can set them manually. We will assume you have set an environment variable called SENDGRID_API_KEY.

The Maven package manager was included when you installed Java. You can use Maven to install the Twilio SendGrid helper library and save it as a project dependency. If you want to verify that Maven is installed, you can type the following into the terminal.

mvn -v

The terminal should print something like the following output.

1
Apache Maven 3.8.1 (05c21c65bdfed0f71a2f2ada8b84da59348c4c5d)
2
Maven home: /usr/local/Cellar/maven/3.8.1/libexec
3
Java version: 16.0.1, vendor: Homebrew, runtime: /usr/local/Cellar/openjdk/16.0.1/libexec/openjdk.jdk/Contents/Home
4
Default locale: en_US, platform encoding: UTF-8
5
OS name: "mac os x", version: "10.15.7", arch: "x86_64", family: "mac"

If Maven is still not installed, you can download and install Maven manually by following the instructions on the "Installing Apache Maven" page.

For those sending an email via Maven with Gradle config, add this in build.gradle:

implementation 'com.sendgrid:sendgrid-java:4.4.1'

Prefer to use Maven, Gradle, or another build tool? The Twilio Java Helper Library docs has information on how to install using a build automation tool.

To install the Twilio SendGrid helper library, type the following command into the terminal.

mvn install sendgrid

The terminal should print something like

1
[INFO] Scanning for projects...
2
[INFO] ------------------------------------------------------------------------
3
[INFO] BUILD FAILURE
4
[INFO] ------------------------------------------------------------------------
5
[INFO] Total time:  0.052 s
6
[INFO] Finished at: 2021-07-26T16:09:02-05:00
7
[INFO] ------------------------------------------------------------------------
8
[ERROR] The goal you specified requires a project to execute but there is no POM in this directory (/Users/user). Please verify you invoked Maven from the correct directory. -> [Help 1]
9
[ERROR]
10
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
11
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
12
[ERROR]
13
[ERROR] For more information about the errors and possible solutions, please read the following articles:
14
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MissingProjectException

You're now ready to write some code. First, create a file in your project directory.

The following Java block contains all the code needed to successfully deliver a message with the SendGrid Mail Send API. You can copy this code, modify the from and to variables, and run the code if you like.

The following is the minimum needed code to send an email with the /mail/send Helper (here is a full example):

Your API call must have the following components:

• A host (the host for Web API v3 requests is always https://api.sendgrid.com/v3/)
• An API key passed in an Authorization Header
• A request (when submitting data to a resource via POST or PUT, you must submit your request body in JSON format)

In your java file, import the SendGrid helper library. The library will handle setting the Host, https://api.sendgrid.com/v3/, for you.

import com.sendgrid.*;

Next, use the API key you set up earlier. Remember, the API key is stored in an environment variable, so you can use the main method to access it. This means we also need to import Java's library.

import java.io.IOException;

Assign the key to a variable named sg using the helper library's SendGrid() method. The helper library will pass your key to the v3 API in an Authorization header using Bearer token authentication.

SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY"));

Now you're ready to set up the from, to, subject, and message body content. These values are passed to the API in a "personalizations" object when using the v3 Mail Send API. You can assign each of these values to variables, and the SendGrid library will handle creating a personalizations object for you.

First, import the library's Mail, Email, To, and Content classes.

from sendgrid.helpers.mail import Mail, Email, To, Content

With the helpers imported, define and assign values for from, to, subject, and content variables. Assigning an email address like from = "test@example.com" will work. However, the constructors imported in the previous step allow you to pass data to them to be sure your final message is formatted properly. Be sure to assign the to to an address with an inbox you can access.

Note that the Content() helper takes two arguments: the content type and the content itself. You have two options for the content type: text/plain or text/html. The second parameter will take the plain text or HTML content you wish to send.

1
Email from = new Email("test@example.com");  // Change to your verified sender
2
String subject = "Sending with Twilio SendGrid is Fun";
3
Email to = new Email("test@example.com");  // Change to your recipient
4
Content content = new Content("text/plain", "and easy to do anywhere, even with Java");

To properly construct the message, pass each of the previous variables into the SendGrid library's Mail constructor. You can assign this to a variable named mail.

Mail mail = new Mail(from, subject, to, content);

You can assign this full call to a variable named response and print the response status code, body, and headers.

1
Response response = sg.api(request);
2
System.out.println(response.getStatusCode());
3
System.out.println(response.getBody());
4
System.out.println(response.getHeaders());

With all this code in place, you can run your java file in your terminal to send the email.

javac <yourfilename>

If you receive a 202 status code printed to the console, your message was sent successfully. Check the inbox of the to address, and you should see your demo message.

If you don't see the email, you may need to check your spam folder.

If you receive an error message, you can reference our response message documentation for clues about what may have gone wrong.

All responses are returned in JSON format. We specify this by sending the Content-Type header. The Web API v3 provides a selection of response codes, content-type headers, and pagination options to help you interpret the responses to your API requests.

• "How to Send Email with Java and Twilio SendGrid" video
• "How to Send Email in Java using Twilio SendGrid" blog post by Matthew Gilliard