Constant Contact Labs Developer Blog

• CTCT Web Services Java Client Library Posted Wednesday, December 23, 2009 Huan Lai 13 Comments

  

  As a result of working on the Android app, I wrote a relatively generic client library in Java for accessing the Constant Contact web services that might be useful for anyone out there writing something in Java that needs to access the CTCT API. The library uses a model similar to that of a typical Object-Relational Mapper to access the resources. Because the library was written before the latest version of the API was released and was written for use by the Android QuickView, there isn’t a 100% coverage of the API, but most of the use cases, barring bulk activities, should be covered. The library is being open-sourced under the Apache 2.0 license.

  NOTE: This library is open source and is maintained and supported by the open source developer community only.  Constant Contact and Constant Contact Labs will NOT provide support for this library.

  The library is posted on SourceForge or you can check out the repository using subversion:

  svn co https://ctctwsjavalib.svn.sourceforge.net/svnroot/ctctwsjavalib 
  

  
  Usage of the library is pretty straight forward; below is a tutorial and some sample code on using the library. Eventually these tutorials will be moved over to the projects section once that is created:

  Authentication

  Before doing anything, you need to initialize a CTCTConnection object and authenticate using your API Key, username and password. The authenticate() method returns true if the authentication was successful.

  CTCTConnection conn = new CTCTConnection();
  conn.authenticate(API_KEY, USERNAME, PASSWORD);
  

  Contact Lists

  Retrieving All ContactLists

  As with all of the other ModelObjects, to retrieve all of the Contact Lists, you must get an ModelIterator from the CTCTConnection object, already authenticated with the account that you want to query.

  ContactListIterator iterator = conn.getContactLists();
  

  After retrieving the ModelIterator, you can get the first page of ContactList ModelObjects. The library (and API) automatically paginates, with 50 entries per page. You can check if there are more pages to load using the ModelIterator’s hasNextPage() method and you can load the next page using the ModelIterator’s loadNextPage() method.

  // Retrieve all ContactList objects
  while(iterator.hasNextPage()) {
      iterator.loadNextPage();
  }
  ArrayList lists = iterator.getLoadedEntries();
  

  Retrieving an Individual ContactList

  You can also retrieve an individual contact list, if you happen to know the ContactList’s Link.

  ContactList contactList = conn.getContactList("/ws/customers/huanlai/lists/1");
  

  Getting Attributes of a ContactList

  As with all other ModelObjects, once you get a ModelObject object, you can retrieve attributes of the object using its getAttribute() method

  contactList.getAttribute("ContactListId")
  

  The ContactList object has the following attributes:

  • ContactListId
  • Link
  • Name

  Modifying a ContactList

  As with all other MutableModelObjects, you can also modify the attributes of the ContactList object and write the changes back to the server

  contactList.setAttribute("Name", "ThisIsATempName");
  // list.isDirty() should now be true
  contactList.commit();
  

  Creating a New ContactList

  The creation of new ModelObjects is done through the CTCTConnection object, passing in a HashMap

  that holds all of the attributes of the new object

  HashMap hashMap = new HashMap();
  hashMap.put("Name", testName);
  ContactList list = conn.createContactList(hashMap);
  list.commit();
  

  Getting the Contact List Members

  You get all of members of a Contact List in the same way you get all of the Contact Lists, by first getting a ModelIterator from the CTCTConnection object and then loading all of the pages. This will give you a list of Contact objects, which I will explain in the next section

  ContactIterator iterator = conn.getContactListMembers("/ws/customers/huanlai/lists/1");
  while(iterator.hasNextPage()) {
      iterator.loadNextPage();
  }
  ArrayList lists = iterator.getLoadedEntries();
  

  Contacts

  Retrieving All Contacts

  As with all of the other ModelObjects, to retrieve all of the Contacts, you must get an ModelIterator from the CTCTConnection object, already authenticated with the account that you want to query.

  ContactIterator iterator = conn.getContacts();
  

  After retrieving the ModelIterator, you can get the first page of Contact ModelObjects. The library (and API) automatically paginates, with 50 entries per page. You can check if there are more pages to load using the ModelIterator’s hasNextPage() method and you can load the next page using the ModelIterator’s loadNextPage() method.

  while(iterator.hasNextPage()) {
      iterator.loadNextPage();
  }
  ArrayList contacts = iterator.getLoadedEntries();
  

  Retrieving an Individual Contact

  You can retrieve an individual Contact if you know either its Link or the email address associated with that Contact.

  Contact contact = conn.getContactByEmail("hlai@constantcontact.com");
  

  or

  Contact contact = conn.getContactByLink("/ws/customers/huanlai/contacts/1");
  

  Getting Attributes of a ContactList

  As with all other ModelObjects, once you get a ModelObject object, you can retrieve attributes of the object using its getAttribute() method

  contact.getAttribute("ContactId")
  

  The ContactList object has the following attributes:

  • ContactId
  • Link
  • Updated
  • Status
  • EmailAddress
  • EmailType
  • Name
  • OptInTime
  • OptInSource
  • FirstName
  • MiddleName
  • LastName
  • JobTitle
  • CompanyName
  • HomePhone
  • WorkPhone
  • Addr1
  • Addr2
  • Addr3
  • City
  • StateCode
  • StateName
  • CountryCode
  • PostalCode
  • SubPostalCode
  • Note
  • ContactLists (ArrayList)
  • Confirmed
  • LastUpdateTime

  Modifying a Contact

  As with all other MutableModelObjects, you can also modify the attributes of the Contact object and write the changes back to the server

  contact.setAttribute("LastName", "ThisIsATempName");
  // list.isDirty() should now be true
  contact.commit();
  

  Adding a Contact to a ContactList

  To add a Contact to a ContactList, you first must retrieve the said Contact and ContactList. Next you must modify the Contact, adding the ContactList to its list of ContactLists.

  Contact contact = conn.getContactByLink("/ws/customers/huanlai/contacts/1");
  ContactList list = conn.getContactList("/ws/customers/huanlai/lists/1");
  ArrayList contactLists = (ArrayList)contact.getAttribute("ContactLists");
  contactLists.add(list);
  contact.setAttribute("ContactLists", contactLists);
  contact.commit();
  

  Creating a New Contact

  The creation of new ModelObjects is done through the CTCTConnection object, passing in a HashMap

  that holds all of the attributes of the new object

  HashMap hashMap = new HashMap();
  hashMap.put("EmailAddress", "test@example.com");
  
  // New Contacts must be in at least one ContactList
  ArrayList contactLists = new ArrayList();
  contactLists.add(conn.getContactList("/ws/customers/huanlai/lists/1"));
  hashMap.put("ContactLists", contactLists);
  
  Contact contact = conn.createContact(hashMap);
  contact.commit();
  

  Getting All Events Associated With a Contact

  You get all of ContactEvents in the same way you get all of the Contact, by first getting a ModelIterator from the CTCTConnection object and then loading all of the pages. This will give you a list of ContactEvent objects, which I will explain in a later section. You must specify the EventType you would like to retrieve: BOUNCES, CLICKS, FORWARDS, OPENS, OPTOUTS, SENDS

  ContactEventIterator iterator = conn.getContactEvents("/ws/customers/huanlai/contacts/1", CTCTConnection.EventType.SENDS);
  while(iterator.hasNextPage()) {
      iterator.loadNextPage();
  }
  ArrayList lists = iterator.getLoadedEntries();
  

  Campaigns

  Retrieving All Campaigns

  As with all of the other ModelObjects, to retrieve all of the Campaigns, you must get an ModelIterator from the CTCTConnection object, already authenticated with the account that you want to query. You must specify the CampaignType you want to retrieve, or if you want to retrieve all of them: SENT, SCHEDULED, DRAFT, RUNNING, ALL

  CampaignIterator iterator = conn.getCampaigns(CTCTConnection.CampaignType.ALL);
  

  After retrieving the ModelIterator, you can get the first page of Campaign ModelObjects. The library (and API) automatically paginates, with 50 entries per page. You can check if there are more pages to load using the ModelIterator’s hasNextPage() method and you can load the next page using the ModelIterator’s loadNextPage() method.

  // Retrieve all ContactList objects
  while(iterator.hasNextPage()) {
      iterator.loadNextPage();
  }
  ArrayList campaigns = iterator.getLoadedEntries();
  

  Retrieving an Individual Campaign

  You can also retrieve an individual campaign, if you happen to know the Campaign’s Link.

  Campaign campaign = conn.getCampaign("/ws/customers/huanlai/campaigns/1102553060150");
  

  Getting Attributes of a Campaign

  As with all other ModelObjects, once you get a ModelObject object, you can retrieve attributes of the object using its getAttribute() method

  campaign.getAttribute("CampaignId")
  

  The ContactList object has the following attributes:

  • CampaignId
  • Link
  • Updated
  • Name
  • Date
  • LastEditDate
  • LastRunDate
  • NextRunDate
  • Status
  • Sent
  • Opens
  • Clicks
  • Bounces
  • Forwards
  • OptOuts
  • Urls

  Getting All Events Associated With a Campaign

  Getting all events associated with a Campaign is slightly different from getting all events associated with a Contact. The CTCTConnection object will return an ArrayList of CampaignEventIterators, each one associated with the events for each of the URLs in that Campaign. The ordering of the ArrayList will correspond to the ordering of the Urls attribute of the campaign

  ArrayList iterators = conn.getCampaignEvents("/ws/customers/huanlai/campaigns/1102661315432", CTCTConnection.EventType.SENDS);
  

  After you get a CampaignEventIterator, it behaves in the same way as all the other ModelIterators.

  Event ModelObjects

  ContactEvent

  ContactEvent objects behave just like any other ModelObject objects. The ContactEvent object has the following attributes:

  • EmailAddress
  • ContactLink
  • CampaignLink
  • EventTime

  CampaignEvent

  CampaignEvent objects behave just like any other ModelObject objects. The CampaignEvent object has the following attributes:

  • EmailAddress
  • ContactLink
  • CampaignLink
  • EventTime

   

  The opinions expressed here represent those of the author and not those of Constant Contact, Inc. Read Blog Terms

  Share

  | More

  Tags

  Libraries • Open Source • Web Services
  Next Post Previous Post

   

Comments (13) +comment on this post

 

• KEVIN DEVON | 1:52 PM August 30, 2010

  i am just the man imam and i treat people just the way i wanna be treated

• andreau | 3:01 AM September 20, 2010

  Very useful! Has this library been updated recently to handle other CTCT API like managing activites or creating a campaign?

• Jim Garretson | 9:04 AM September 20, 2010

  Hi Andreau, I’m not sure that it has - but please check the Sourceforge site for the latest info.

• Alan Comeau | 3:32 PM October 24, 2011

  I was getting errors verifying the ssl cert on CT, the resolution was the change the CTCTConnection() to this
  public CTCTConnection() {
        SchemeRegistry schemeRegistry = new SchemeRegistry();
    schemeRegistry.register(new Scheme(“http”, 80, PlainSocketFactory.getSocketFactory()));
    schemeRegistry.register(new Scheme(“https”, 443, SSLSocketFactory.getSocketFactory()));
   
    HttpParams params = new BasicHttpParams();
    ThreadSafeClientConnManager cm = new ThreadSafeClientConnManager(schemeRegistry);
    httpclient = new DefaultHttpClient(cm, params);
    }

  I hope this helps

• Mohd Ali | 11:45 AM November 20, 2011

  Hi,
    Friend,
  Logical Infotech is an information technology company, providing customized software’s and web based applications. We are a team of dedicated and highly skilled software professionals focused on providing world class IT solutions. We offer a variety of services in the area of Software and Web development

• Marudhar Arts | 12:41 AM December 17, 2011

  world coins
  warrior gallops
  War soldiers
  VVIP Set
  VIP Set Of INDIA
  Vijayana Nagar Coin Of INDIA
  value of old indian coins
  valuable coins of india
  Unique temple tokens of INDIA
  UNC Sets of INDIA
  Unc Sets of INDIA
  tipu sultan coins
  three swami pagoda coins
  Temple Tokens Of INDIA
  Temple Token
  Sultanate Coins Of INDIA
  Sultanate Coins of india
  sultanate coins of INDIA
  Sultanate Coins of delhi
  Sultanate Coins of Bengal
  Sultanate Coins of bahmani
  Stamps Of Worldwide Of INDIA
  stamps of the world
  stamps of india 2011
  Stamps of India
  stamps of different countries
  stamps india
  stamps collection
  stamps
  stamp of india
  stamp collection

• lucivaldo | 3:34 PM December 17, 2011

  estamos desponivel nesse site quem quiser nos encontra é aqui.

• Corazon | 12:49 PM February 3, 2012

  Constant Contact is a exciting web tools for my business, It helps my business to spread the news, and my new creation. it is a fun social media networking communication, I love to learn more about the web site,

• Corazon | 12:51 PM February 3, 2012

  Learned new tools from my business.

• lat | 10:14 AM July 11, 2012

  Can I get any sample for Authentication with post request? Please please help me out if anyone has any ideas. I appreciate your help.

• lat | 10:18 AM July 11, 2012

  Can anyone provide me sample code in java for ‘Creating a New Contact’, with authentication and post request with creating contact. Thank you!!

• lat | 10:50 AM July 11, 2012

  For just creating a contact I have code in java something like this. Does it make any sense to anyone? Please help me out if I need to do any corrections. thank you!!

  
    DefaultHttpClient httpClient = new DefaultHttpClient();

    String loginUsername = apiKey + “%” + username;
    httpClient.getCredentialsProvider().setCredentials(AuthScope.ANY, new UsernamePasswordCredentials(loginUsername, password));

    HttpPost httppost = new HttpPost(“https://api.constantcontact.com/ws/customers/” + username + “/contacts”);
    httppost.addHeader(“Content-Type”, “application/atom+xml”);

    StringBuilder builder = new StringBuilder();
    builder.append(”<entry >”);
    builder.append(”<title type=\“text\”> </title>”);
    builder.append(”<updated>2012-07-10T14:21:06.407Z</updated>”);
    builder.append(”<author></author>”);
    builder.append(”<id>data:,none</id>”);
    builder.append(”<summary type=\“text\”>Contact</summary>”);
    builder.append(”<content type=\“application/vnd.ctct+xml\”>”);
    builder.append(”<Contact >”);
    builder.append(”<EmailAddress>”);
    builder.append(“example@gmail.com”);
    builder.append(”</EmailAddress>”);
    builder.append(”<OptInSource>ACTION_BY_CUSTOMER</OptInSource>”);
    builder.append(”<ContactLists>”);
    builder.append(”<ContactList id=\“http://api.constantcontact.com/ws/customers/” + username + “/lists/1\”>”);
    builder.append(”</ContactLists>”);
    builder.append(”</Contact>”);
    builder.append(”</content>”);
    builder.append(”</entry>”);

    ByteArrayEntity entity = new ByteArrayEntity(builder.toString().getBytes());
    httppost.setEntity(entity);
    HttpResponse response = httpClient.execute(httppost);

    int status = response.getStatusLine().getStatusCode();

• nishant | 9:10 AM July 23, 2012

  Hi, Can we get list of all triggered mail’s of the user?

  Thanks
  Nishant

Add your comment below