## Getting started with the SparkPost Java Client Library

At SparkPost we know many of our largest customers interface to the REST API from a Java backend. Today we are pleased to announce our [J](https://github.com/SparkPost/java-sparkpost)[ava client library](https://github.com/SparkPost/java-sparkpost). This will make developing for SparkPost a breeze for Java developers. Let’s take a look at how to get started.

## Getting Started

Using java-sparkpost is as simple as including the following in your project’s pom.xml:

<dependency>
    <groupId>com.sparkpost</groupId>
    <artifactId>client-server-protocol-lib</artifactId>
    <version>0.8</version>
</dependency>

The version is 0.8 as of this writing. You may want to change the version to the latest version.

## Sending Your First Email

To follow along check out the source code and open it in Eclipse. You can [follow these instructions](https://github.com/SparkPost/java-sparkpost/blob/master/CONTRIBUTING.md#local-development) to help get you started. Once you have the project set up and running let’s configure the samples project:

1.  cd apps/sparkpost-samples-app
2.  Copy config.properties.example to config.properties
3.  Open config.properties in your favorite text editor
4.  Change `SPARKPOST_API_KEY` to contain your API key. Make sure to [create your API key](https://app.sparkpost.com/account/credentials) with the “Transmissions: Read/Write” permission.
5.  Enter a valid from address for the key `SPARKPOST_SENDER_EMAIL`. The domain should be a [verified sending domain](https://app.sparkpost.com/account/sending-domains).
6.  Modify `SPARKPOST_FROM` with a valid from address.
7.  Enter a comma delimited list of recipients for the key `SPARKPOST_RECIPIENTS`.
8.  Save the file.

Once the sample project has been configured open com.sparkpost.samples.SendEmailSample in Eclipse and let’s dive into the code.

## Common Sample Code

To keep the samples simple they extend a base helper class called [SparkPostBaseApp](https://github.com/SparkPost/java-sparkpost/blob/master/apps/sparkpost-samples-app/src/main/java/com/sparkpost/sdk/samples/helpers/SparkPostBaseApp.java), which reads in the config.properties file. The SparkPost client is configured like this:`client = this.newConfiguredClient()`. In your own code you will likely have your own configuration mechanism such as Spring or some other configuration system. The code is written to be easily adaptable. The base class also has some helpers to load email templates from the file systems and get the from and recipients addresses that we configured in config.properties.

This is how the client is setup and how to use some of the base class helpers:

public class SendEmailSample extends SparkPostBaseApp {
private void runApp() throws SparkPostException, IOException {

        client = this.newConfiguredClient();

        // Loads an email to send from the file system
        String template = getTemplate("sample\_sp\_email.eml");
        String fromAddress = getFromAddress();
        String\[\] recipients = getTestRecipients();
    }

}

## Send Email Sample

This `sendEmail` method takes a from address and an array of recipients:

private void sendEmail(String from, String\[\] recipients, String email) throws SparkPostException {

        TransmissionWithRecipientArray transmission = new TransmissionWithRecipientArray();

        // Populate Recipients
        List<RecipientAttributes> recipientArray = new ArrayList<RecipientAttributes>();

        for (String recipient : recipients) {
            RecipientAttributes recipientAttribs = new RecipientAttributes();
            recipientAttribs.setAddress(new AddressAttributes(recipient));
            recipientArray.add(recipientAttribs);
        }

        transmission.setRecipientArray(recipientArray);
        transmission.setReturnPath(from);

        // Populate Substitution Data
        Map<String, String> substitutionData = new HashMap<String, String>();
        substitutionData.put("from", from);
        transmission.setSubstitutionData(substitutionData);


        // Populate Email Body
        TemplateContentAttributes contentAttributes = new TemplateContentAttributes();
        contentAttributes.setEmailRFC822(email);
        transmission.setContentAttributes(contentAttributes);

        // Send the Email
        RestConnection connection = new RestConnection(client, getEndPoint());
        Response response = ResourceTransmissions.create(connection, 0, transmission);

        logger.debug("Transmission Response: " + response);
    }

This code is building up the transmission which describes the email campaign that is being sent. You build up your list of RecipientAttributes and populate the ‘from’ and the email on the `TemplateContentAttributes` object. Once configured, you use the `RestConnection` and `ResourceTransmissions` classes to send the email to the server. Once you run this sample you should see this email in your recipient’s inbox:
Login to your SparkPost account and open the [Summary Report](https://app.sparkpost.com/reports/summary) and you will see data for your email:

In my test I sent to 100 test users, so in this report there are 100 emails sent and 13 of which were opened. You can play around with config.properties to see what happens when you have bad email addresses or to test for other recipients.

## Your Turn

Now it’s your turn. We can’t wait to see how you use java-sparkpost. As you explore the library here are some other samples that may help you solve your specific task:

| Sample                     | Description                                                                                  |
| -------------------------- | -------------------------------------------------------------------------------------------- |
| SendEmailSample            | Basic example of sending a local RFC822 email from local file system to a list of recipients |
| CreateTemplateSimple       | Example of creating a very simple email template on the server                               |
| CreateTemplateFromFile     | Stores a raw RFC822 template on server                                                       |
| CreateTemplateFromFile2    | Stores an HTML template on server                                                            |
| ListAllSendingDomains      | Prints a list of domains that are configured for SparkPost account                           |
| ListAllTemplatesSample     | Displays the name and last updated date of templates stored on the server                    |
| ListAllTransmissionsSample | Logs a list of transmission summary object                                                   |
| ListAllWebhooksSample      | Demonstrates how to list all your webhooks                                                   |

## Want to Contribute?

We love pull requests for code enhancements, new samples, or better testing and documentation. Head on over to our Github repo and [create an issue](https://github.com/SparkPost/java-sparkpost/issues/new) or pull request. We look forward to hearing from you.