In this quickstart, you'll learn how to send your first email using the Twilio SendGrid Mail Send API and Java.
Be sure to perform the following prerequisites to complete this tutorial. You can skip ahead if you've already completed these tasks.
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.
To get started quickly, you may be able to skip Domain Authentication and begin by completing Single Sender Verification. Single Sender Verification is recommended for testing only. Some email providers have DMARC policies that restrict email from being delivered using their domains. For the best experience, please complete Domain Authentication. Domain Authentication is also required to upgrade from a free account.
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.
The Twilio SendGrid Java helper library supports Java 8 and 11.
Check your Java version by opening your terminal (also known as a command line or console) and typing the following command.
_10java -version
If you have Java installed, the terminal should print something like the following output.
_10java version "16.0.2" 2021-07-20_10Java(TM) SE Runtime Environment (build 16.0.2+7-67)_10Java 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.
_10mvn -v
The terminal should print something like the following output.
_10Apache Maven 3.8.1 (05c21c65bdfed0f71a2f2ada8b84da59348c4c5d)_10Maven home: /usr/local/Cellar/maven/3.8.1/libexec_10Java version: 16.0.1, vendor: Homebrew, runtime: /usr/local/Cellar/openjdk/16.0.1/libexec/openjdk.jdk/Contents/Home_10Default locale: en_US, platform encoding: UTF-8_10OS 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 w/ Gradle config, add this in build.gradle:
_10implementation '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.
_10mvn install sendgrid
The terminal should print something like
_14[INFO] Scanning for projects..._14[INFO] ------------------------------------------------------------------------_14[INFO] BUILD FAILURE_14[INFO] ------------------------------------------------------------------------_14[INFO] Total time: 0.052 s_14[INFO] Finished at: 2021-07-26T16:09:02-05:00_14[INFO] ------------------------------------------------------------------------_14[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]_14[ERROR]_14[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch._14[ERROR] Re-run Maven using the -X switch to enable full debug logging._14[ERROR]_14[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):
_26import com.sendgrid.*;_26import java.io.IOException;_26_26public class Example {_26 public static void main(String[] args) throws IOException {_26 Email from = new Email("test@example.com");_26 String subject = "Sending with Twilio SendGrid is Fun";_26 Email to = new Email("test@example.com");_26 Content content = new Content("text/plain", "and easy to do anywhere, even with Java");_26 Mail mail = new Mail(from, subject, to, content);_26_26 SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY"));_26 Request request = new Request();_26 try {_26 request.setMethod(Method.POST);_26 request.setEndpoint("mail/send");_26 request.setBody(mail.build());_26 Response response = sg.api(request);_26 System.out.println(response.getStatusCode());_26 System.out.println(response.getBody());_26 System.out.println(response.getHeaders());_26 } catch (IOException ex) {_26 throw ex;_26 }_26 }_26}
Your API call must have the following components:
https://api.sendgrid.com/v3/
)
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.
_10import 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.
_10import 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.
_10SendGrid 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.
_10from 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.
_10Email from = new Email("test@example.com"); // Change to your verified sender_10String subject = "Sending with Twilio SendGrid is Fun";_10Email to = new Email("test@example.com"); // Change to your recipient_10Content 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.
_10Mail 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.
_10Response response = sg.api(request);_10System.out.println(response.getStatusCode());_10System.out.println(response.getBody());_10System.out.println(response.getHeaders());
With all this code in place, you can run your java file in your terminal to send the email.
_10javac <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.