##Description

Welcome Java developers! If you're looking to use or learn how to use Benchmark Email's Java wrapper to integrate with our API then you've come to the right place. The purpose of these files is to help you hit the ground running and start developing using our API quickly and effectively. This project will showcase how to:

• Login to a Benchmark Email account
  
• Retrieve the ID of a mailing list
  
• Create a new mailing list
  
• Prepare an array of contacts to add into a mailing list (using the list ID)
  

So whether you're new to Java or an experienced software dev, let our example project give you a running start on integrating with Benchmark Email. Good luck!

##Prerequisites In order to be able to run this example project you must have the following:

• Java v1.8 which comes included with JDK8 (Java Development Kit). You can download the JDK8 here: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html

• An Eclipse IDE that is compatible with Java v1.8. The Luna or Mars package will work just fine, Kepler and older packages
  would not be compatible. You can download the Eclipse IDE here:
  https://www.eclipse.org/downloads/packages/eclipse-ide-java-developers/lunasr1

• No money, our free and paid plans allow you to use our API at no cost. So follow the link and sign up for a free account to receive your API token:
  https://ui.benchmarkemail.com/Register

##Setting Up Your Environment for Java

• Run the JDK installer

• (If using Windows) Change your PATH variable
  http://docs.oracle.com/javase/tutorial/essential/environment/paths.html

• That should be it! You can verify if everything was installed correctly by:
  

1. Opening up your terminal (command line)
   
2. Type in "java -version" w/o the quotes
   
3. Then notice the version number. As long as it is v1.8 or greater then your environment should be all set to go !
   

#Configuring the Project for Eclipse

In order to setup thisproject on Eclipse follow these steps:

• Download the repository
  
  • Go to https://github.com/Benchmark-Email/bmejavawrapper
  • Click on the "Download ZIP" button located on the right hand side
• Once the download is finished, extract the zip file (possibly to your desktop for easy access)
  
• Open Eclipse
  
• Select a separate (empty) folder as your workspace
  
• Click on File -> Import...
  
  • Under the General folder select "Existing Projects into Workspace", then hit Next
    
  • (1) Make sure that the "Select root directory" option is ticked on the top and click on Browse...
    
  • Navigate to where you extracted the zip file and highlight the "javaWrapper" folder. Click OK
    
  • (2) The "javaWrapper" project should appear in the "Projects" section. Make sure javaWrapper is selected
    
  • (3) Under Options make sure to tick the "Copy projects into Workspace" option
    
  • Hit Finish
    

Your Package Explorer should look like this (we will take care of the errors in the next section):

##Importing XML-RPC Libraries Now the project is imported but we still need to add the xml-rpc libraries (hence the errors).
Never worked with xml-rpc before? No sweat, the files are in the "lib" folder. We just need to import them.

• In Eclipse
  
  • Click on Project -> Properties
    
  • Click on "Java Build Path" (will be on the left hand side)
    
  • Click the "Libraries" tab
    
  • Click on "Add External JARs..."
    
  • Navigate to your Workspace folder. Then go to /javaWrapper/lib
    
  • Highlight all 4 JARs then click the Open button
    

commons-httpclient-3.1

ws-commons-util-1.0.2

xmlrpc-client-3.1

xmlrpc-common-3.1
- Click OK
- Eclipse should show the added libraries under "Referenced Libraries" and all the errors should be gone
- If you still have an error restart Eclipse by clicking on File -> Restart

Congratulations! You have successfully installed and configured the Benchmark Email Java wrapper!

#Running the Project

Before we can run the program we need to add our Benchmark Email username and password.
Double click on the "MainBME.java" file under the javaWrapper package in the Package Explorer.

Let's take a look at lines 11 and 12:

In order to successfully connect to a Benchmark Email account you must write in your username and password in the variables 'userName' and 'password'.

The login() method will attempt to login to your Benchmark Email account and set the API token to the 'token' variable.
Once you have added in your username and password just hit the Run button (1) and click OK (2) . That's all there is to it!

#Contact Info

• Visit our API page to view our other wrappers and documentation:
  http://www.benchmarkemail.com/API/Library

#Licensing

Copyright (c) 2014 BenchmarkEmail, released under the MIT license

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.