Learn more about how to download and implement our Java API Integration Library to your system.

Overview - what this Library is?

We want to provide our clients a way to use our system however they like. That is why we have introduced the Integration Libraries - a group of functions and declarations to help you implementing our API to your system.

How to download and implement the Library

All of our libraries are available here, whereas the specific library for Java can be found at the following link.

After you have downloaded the library (which is a whole project), you might want to put it in your Java directory to have a quick and easy access to it manually or through your own code.

We will be using Eclipse. We also suggest creating a Maven project to easily import external packages needed to start using our library.
Extract the whole project to your existing project directory. If you do not have a project set up yet, please do this now. One of the ways to include our library in your project would be selecting the Import... option available under right-click on one of your project folders and selecting the File System import source type:

screenshot from maven showing how to set up a project

The image below shows a sample Maven project with our Library all set up:

screenshot from maven showing full project import

You will be using the import functionality to access any classes and methods that you need. The code below is a standard classes import that will be enough for us to start working with the library:

import com.elasticemail.app.API;
import com.elasticemail.app.ApiTypes;
import com.elasticemail.app.functions.*;

We are also going to need some external dependencies of fastxml.jackson. You can import them by adding the following code to the dependencies section of your pom.xml file:

<!-- https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-core -->
<dependency>
	<groupId>com.fasterxml.jackson.core<groupId>
	<artifactId>jackson-core</artifactId>
	<version>2.8.7</version>
</dependency>

<!-- https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-databind -->
<dependency>
	<groupId>com.fasterxml.jackson.core</groupId>
	<artifactId>jackson-databind</artifactId>
	<version>2.8.7</version>
</dependency>

How to start working with the Library on your project

All of our library's methods are available using the static class named API. Whether you want to send an email or modify your template, you can do it using the API class. You can use the ApiTypes class to create the desired object that would be used as a parameter in some calls. Refer to our API documentation or use Eclipse's auto-suggestion functionality. Use whichever you like.

But first of all, we need to setup an ApiKey, that is the unique identifier of your account. You can do this in two ways:

First option: open up API.java in your editor. Then, in the API class, you can find two fields API_KEY and API_URI. Change the former's value to your ApiKey available to you here. Don't mind the API_URI field, it is best to leave it untouched.

Second option: simply overwrite the API_KEY field's value of the API class at the start of your code. Remember to import the API class first:

import com.elasticemail.app.API;
import com.elasticemail.app.ApiTypes;
import com.elasticemail.app.functions.*;

public class App {
	public static void main(String[] args) {
		API.API_KEY = "11111111-2222-3333-4444-555555555555";
	}
}

This can also be used to swap between the accounts while your program is running, so you can keep this line in mind.

Some basic API calls made using this Library

Sending a merge email to multiple recipients, provided as an attachment:

import com.elasticemail.app.*;
import com.elasticemail.app.API;
import com.elasticemail.app.ApiTypes;
import com.elasticemail.app.functions.*;

public class App 
{
    public static void main( String[] args )
    {
    	API.API_KEY = "11111111-2222-3333-4444-555555555555";
    	
    	Email email = new Email();
    	ApiTypes.EmailSend response = null;
        String subject = "Your subject";
        String fromEmail = "test1@test.com";
        String fromName = "Your Company Name";
        String bodyText = "Text body";
        String bodyHtml = "<h1>Hello, {username}.</h1>";

        FileData attachmentFile = FileData.CreateFromFile("C:/Users/recipients.csv");
        List<FileData> files = new ArrayList<FileData>();
        files.add(attachmentFile);
    	
        String filenameWithRecipients = "recipients.csv"; // same as the file above

    	try {
		response = email.send(subject, fromEmail, fromName, "", "", "", "", "", "", null, 
					null, null, null, null, null, filenameWithRecipients, "", bodyHtml, bodyText, "",
					"", "", ApiTypes.EncodingType.BASE64, "", files, null, "", null, "", "", false);
	} catch (Exception e) {
		e.printStackTrace();
		System.out.println(e.getMessage());
	}
    	
    	if (response != null)
    	{
    		System.out.println("MsgID to store locally: " + response.messageid); // Available only if sent to a single recipient
    		System.out.println("TransactionID to store locally: " + response.transactionid);
    	}
    }
}

An example of loading info about your own account and displaying the price per email:

import com.elasticemail.app.API;
import com.elasticemail.app.ApiTypes;
import com.elasticemail.app.functions.*;

public class App 
{
    public static void main( String[] args )
    {
    	API.API_KEY = "11111111-2222-3333-4444-555555555555";
    	
    	Account account = new Account();
    	ApiTypes.Account response = null;
    	try {
		response = account.load();
	} catch (Exception e) {
		e.printStackTrace();
		System.out.println(e.getMessage());
	}
    	
    	if (response != null)
    	{
    		System.out.println(response.priceperemail); // what a deal!
    	}
    }
}

One of many ways to save your contacts:

import java.util.Date;

import com.elasticemail.app.API;
import com.elasticemail.app.ApiTypes;
import com.elasticemail.app.functions.*;

public class App 
{
    public static void main( String[] args )
    {
    	API.API_KEY = "11111111-2222-3333-4444-555555555555";
    	
    	Contact contact = new Contact();
    	ApiTypes.StringList contacts = new ApiTypes.StringList();
    	contacts.add("test1@test.com");
    	Date consentDate = new Date();
    	
    	try {
    		contact.quickAdd(contacts, "", "", "", "", "", "", "", "", "", "", "", ApiTypes.ContactStatus.ACTIVE, "", consentDate, "", "");
	} catch (Exception e) {
		e.printStackTrace();
		System.out.println(e.getMessage());
	}    	
    }
}

License

All code samples are licensed under MIT license.