1 | P a g e

Getting Started with the iContact API

Contents

- Introduction - ........................................................................................................................................................ 2

- URIs, URLs, Resources, and Supported Actions - .................................................................................................. 3

Contacts Category ............................................................................................................................................... 3

Messages Category ............................................................................................................................................. 4

Track Category .................................................................................................................................................... 4

GET ...................................................................................................................................................................... 5

POST .................................................................................................................................................................... 5

PUT ...................................................................................................................................................................... 5

DELETE ................................................................................................................................................................. 5

- Creating a Sandbox Account - ............................................................................................................................... 6

- Register and Enable Your Application - ................................................................................................................ 8

- API Headers -....................................................................................................................................................... 11

- Account ID & Client Folder ID - ........................................................................................................................... 11

- Some Common Examples - ................................................................................................................................. 14

Create a List....................................................................................................................................................... 14

Create a Contact ............................................................................................................................................... 15

Subscribe a Contact .......................................................................................................................................... 16

Create a Message .............................................................................................................................................. 16

- Support for the iContact API - ............................................................................................................................. 17

2 | P a g e

- Introduction -

The purpose of this document is to give a step by step process on how to get started with using the iContact

API as well as give some basic examples of calls you can make to it for various information. It should be stated

ahead of time that to use the API, we recommend strong working knowledge of a web programming language

such as PHP. iContact does not provide project management services at this time, so many of our API users

will find it necessary to hire a developer to work on their API project.

First we need to start with some basic information that will help with understanding what the API is, what can

be done with it, and the policies concerning it.

- API stands for Application Programming Interface and is defined as “a particular set of rules (‘code’)

and specifications that software programs can follow to communicate with each other.” In this case

the software programs in question are the one(s) you are developing/using and the iContact

application.

- Communication to and from the iContact API can be in only two different programming languages –

XML (Extensible Markup Language) and JSON (JavaScript Object Notation).

- The API is most commonly used for Contact, List and Subscription Management purposes (adding,

deleting, and modifying Contacts). However, it can also be used to create messages and view message

statistics.

- Sandbox accounts can be opened for testing your application without affecting any real data in your

production account. The Sandbox is merely a testing environment. NOTE: Sandbox accounts are only

available to paid customers even though the API itself is available to all customers, Paid, Trial, and Free.

- To use the iContact API, you must adhere to iContact’s Terms and Conditions1. In addition, you must

also adhere to the iContact API’s request limiting and throttling limits (see next note). Failure to

adhere to these conditions may cause iContact to revoke your AppId or to disable your iContact

account.

- The request limit for the iContact API is 75,000 requests in a 24 hour period, with a maximum of 10,000

requests per hour. If you exceed the 75,000 requests per 24 hour period, you should wait 1 minute

before making another API request. If you exceed 10,000 requests per hour, you should wait at least 1

second before making another API request. NOTE: If you exceed the request limit, we will respond

with a 503 error code for any additional requests.

1 http://www.icontact.com/terms

3 | P a g e

- URIs, URLs, Resources, and Supported Actions -

When the acronyms “URI” or “URL” are used in reference to the API they are referring to the web addresses

that requests (or “calls”) are sent to. Once all of the necessary access information is gathered (see steps

below) you will use the appropriate URI/URL for the action you desire to take through the API. The URIs/URLs

vary based on which Resource you are making a call to. There are seventeen Resources that fall under three

main categories that you can make calls to:

Contacts Category

1) Client Folders Resource (http://developer.icontact.com/documentation/resource-call-references-

list/client-folders) - The client folders resource allows access to information in the client folders

within an account. Every iContact account contains at least one client folder, however some

accounts contain multiple client folders. The client folder contains all information regarding a

specific client, including messages, lists, sends, segments, subscribers, etc.

2) Contacts Resource (http://developer.icontact.com/documentation/resource-call-references-

list/contacts) - Use the contacts resource to create and view contacts, edit information about

individual contacts, and edit information about multiple contacts.

3) Custom Fields Resource (http://developer.icontact.com/documentation/resource-call-references-

list/custom-fields) - Custom fields allow an iContact user to store contact information other than

the standard fields provided by the system. For example, you might include a region custom field

that describes the geographical region in which a contact resides.

4) Subscriptions Resource (http://developer.icontact.com/documentation/resource-call-references-

list/subscriptions) - Subscriptions map the relationship between a contact and a list.

5) Uploads Resource (http://developer.icontact.com/documentation/resource-call-references-

list/uploads) - Use this resource to upload a list of contacts that exist in a .csv or .xls file.

6) Segments Resource (http://developer.icontact.com/documentation/resource-call-references-

list/segments) - Segments define a saved search of contacts on a given list, allowing you to send to

just the subscribers in that saved search. Use the segments resource to create, edit, and delete

segments.

7) Segment Criteria Resource (http://developer.icontact.com/documentation/resource-call-

references-list/segment-criteria) - Get and modify criteria for segments.

8) Lists Resource (http://developer.icontact.com/documentation/resource-call-references-list/lists) -

Use the lists resource to modify subscriber lists.

4 | P a g e

Messages Category

1) Sends Resource (http://developer.icontact.com/documentation/resource-call-references-

list/sends) - The sends resource defines an event: the date and time on which an email is sent

through iContact. This includes emails that are scheduled to be sent in the future.

2) Campaigns Resource (http://developer.icontact.com/documentation/resource-call-references-

list/campaigns) - Campaigns allow you to modify users’ sending profile and the address to their

blogs and archives.

3) Messages Resource (http://developer.icontact.com/documentation/resource-call-references-

list/messages) - A message is any email marketing communication created within iContact.

Track Category

1) Message Bounces Resource (http://developer.icontact.com/documentation/resource-call-

references-list/message-bounces) - Gather tracking data on how often specific emails are bouncing.

2) Message Clicks Resource (http://developer.icontact.com/documentation/resource-call-references-

list/message-clicks) - Use the message clicks resource to gather data on how many usersclicked the

links in your emails, and also who clicked the links.

3) Message Opens Resource (http://developer.icontact.com/documentation/resource-call-

references-list/message-opens) - This resource tracks the number of times an email was opened by

subscribers.

4) Statistics Resource (http://developer.icontact.com/documentation/resource-call-references-

list/statistics) - Use the statistics resource to gather data on specific emails, including: bounces,

clicks, forwards, delivered, unsubscribed, opens, comments, complaints

5) Unsubscribes Resource (http://developer.icontact.com/documentation/resource-call-references-

list/unsubscribes) - Provides data on who unsubscribed from a list.

6) Contact History Resource (http://developer.icontact.com/documentation/resource-call-references-

list/contact-history) - Use this resource to access data contained on the Contact History pages.

As mentioned above there are URIs/URLs associated with each of the seventeen Resources above. There are

only four different actions that can be performed in the iContact API, though. Not all actions can be

performed in all seventeen Resources2. The four supported actions (also known as “requests” or “calls”) are:

2 For information on which actions each Resource supports click on the link next to the Resource Name above to be taken to those

pages in the iContact Developer Portal.

5 | P a g e

GET Used primarily to retrieve general or specific information from your account using one of the

supported Resources. Examples included retrieving lists of contacts, specific contacts, messages,

subscriptions, etc.

POST Used primarily to add new data to your account. Examples include adding new contacts, modifying

subscriptions, creating new messages, and initiating message sends.

PUT Used primarily to overwrite existing data. Examples include moving contacts from one list to another

list or uploading a list of contacts.

DELETE Used to delete information from the account.

Now that you are familiar with the basics of understanding and using the iContact API we can move on to how

to start using it.

All of the screenshots below are going to be either of the iContact application and/or website itself, or of an

application called RESTClient, which is available from http://www.wiztools.org 3. The responses received by

the iContact API are displayed in XML and therefore may appear differently if you are using a program that

uses JSON.

3 http://code.google.com/p/rest-client/ (The version used is under the “Downloads” section to the left -

https://code.google.com/p/rest-client/downloads/detail?name=restclient-ui-3.1-jar-with-dependencies.jar

6 | P a g e

- Creating a Sandbox Account -

As mentioned in the Introduction above, Sandbox accounts are only available to paid customers. Trial and

Free Edition customers are free to use the API itself but cannot open a Sandbox account. If you are not a paid

customer you can skip the steps in this section and move on to the Register Your Application section below.

Follow these steps to create an iContact Sandbox account:

(1) Visit the iContact Developer Portal at http://developer.icontact.com and click on the “Sandbox Login” link:

7 | P a g e

(2) On the following page click on the link that says “If you need a Sandbox login, Sign Up”:

(3) On the following page enter in your iContact Username and Password for your paid account into the

spaces provided. You will also need to read and agree to iContact's Sandbox Terms of Service4. When you

have finished entering this information click the “Proceed to the next step” button:

4 http://sandbox.icontact.com/terms.php

8 | P a g e

(4) On the following page you will enter in your desired Sandbox login information. This includes a Sandbox

Username, Password, and Magic Recipient Email Address5. When you have finished entering this

information click the “Sign Up” button :

You have successfully set up your iContact Sandbox account! Proceed to the next section to acquire the

necessary information to access the iContact API.

- Register and Enable Your Application -

Each application that attempts to access the iContact API needs to have a unique identifier known as the

Application ID or Application Key. To acquire this Application ID you must register your application with

iContact. Use the following steps to register your application:

(1) Visit https://app.icontact.com/icp/core/registerapp (This is for your main Production account. For a

Sandbox account visit https://app.sandbox.icontact.com/icp/core/registerapp instead. The subsequent

steps are the same. To retrieve your Application ID at any time after generating it you will visit these same

links.)

5 The Magic Recipient Email Address is where all broadcast messages sent from the Sandbox account will be sent to no matter how

many contacts or which list(s) you choose.

9 | P a g e

(2) On the following page enter in your desired Application Name and Description. Both of these are required

fields. (NOTE: The Application Name and Description cannot be changed once entered) When you have

finished entering that information click the “Get App ID” button. (NOTE: There can only be one AppId per

account):

(3) The following page will repeat your Application Name and Description and give you the option to choose

between API 2.0 and 1.0 (make sure 2.0 is selected). It also has your 32-character API-AppId under the

heading “API 2.0 Authentication”. Write down this information somewhere and save it for future use:

10 | P a g e

(4) After you have written down your application information click on the link that says “enable this AppId for

your account”:

(5) Enabling your AppId for your account entails setting up a password that is specific to that AppId. Type

your desired password into the space provided and click the “Save” button.

11 | P a g e

You have successfully generated and enabled an Application ID (AppId/Key) for your account!

- API Headers -

If you have completed all of the steps above you have most of the information you need to start

communicating with the iContact API. To initiate a connection with the iContact API you must provide valid

headers. The necessary header information is as follows:

Accept: [this value can be either text/xml (for XML) or application/json (for JSON)]

Content-Type: [this value can be either text/xml (for XML) or application/json (for JSON)]

API-Version: [this value can be either 2.0, 2.1, or 2.2]

API-AppId: [this value is the 32-Character Application ID you generated and enabled above]

API-Username: [this value is your Production account username (or your Sandbox account username if

you are making calls to your Sandbox account)]

API-Password: [this value is the password you created when enabling your Application ID above not your

Production or Sandbox account password]

Here is a sample set of header information:

Accept: text/xml

Content-Type: text/xml

API-Version: 2.2

API-AppId: VDRXdzy2IkS35Ma4GVS6I5HGjlfUl88X

API-Username: icontactisawesome

API-Password: mysupersecurepassword

With all of this information you can now initiate a connection with iContact via the API.

[IMPORTANT NOTE: If you are attempting to make calls to your Production account and are getting an “Invalid

Username” error make sure to check the case of the characters in your username. When accessing your

Production account via the API the API-Username in your headers is case-sensitive. It is not case-sensitive

when you are trying to access the Sandbox. If you need to verify the case of your Username send a request to

api@icontact.com and API Support will email you the accurate information.]

- Account ID & Client Folder ID -

Using the accurate header information you can now retrieve the last two necessary pieces of information to

govern your account via the API. Each account in iContact is assigned its own Account ID. Within each

account there can be one or more Client Folders, each of which has their own ID. Standard accounts have one

12 | P a g e

Client Folder ID whereas Agency accounts can have multiple IDs. Use the following steps to retrieve your

Account and Client Folder IDs:

(1) Account ID

a. For Sandbox account – make a GET call to https://app.sandbox.icontact.com/icp/a/ and the response

will contain a tag with your accountId. The response from the RESTClient below is in xml:

b. For Production account – make a GET call to https://app.icontact.com/icp/a/ and the response will

contain a tag with your accountId. The only thing that changes is the URI/URL that you make the call

to. The response will be formatted the same (except with different information):

13 | P a g e

(2) Client Folder ID

Using the accountId you can now acquire the clientFolderId:

a. For Sandbox account – make a GET call to https://app.sandbox.icontact.com/icp/a/{accountId}/c/ and

the response will contain a tag with your clientFolderId. The response from the RESTClient below is in

xml:

b. For Production account – make a GET call to https://app.icontact.com/icp/a/{accountId}/c/ and the

response will contain a tag with your clientFolderId. The only thing that changes is the URI/URL that

you make the call to. The response will look the same (except with different information):

14 | P a g e

Now that you have your accountId and clientFolderId numbers you have the full URI/URL necessary to use all

Resources in the iContact API:

For Sandbox accounts: https://app.sandbox.icontact.com/icp/a/{accountId}/c/{clientFolderId}/

For Production accounts: https://app.icontact.com/icp/a/{accountId}/c/{clientFolderId}/

Fill in the {accountId} and {clientFolderId} sections in the URIs/URLs above with the information you retrieved

when making the GET calls and you are good to go!

- Some Common Examples -

The most common uses of the iContact API is to create lists, create new contacts, subscribe those contacts to a

list or lists, and create messages. Below are examples of how to do each in both XML and JSON (in blue font).

These examples are considered the “Body” of text passed through the API. Obviously the text contained in

each example would need to be modified to match your specific contacts’ information. For information on

what each of the fields mean, click on the name of the corresponding resource above to find the information

in the iContact Developer Portal.

Create a List XML:

<lists>

<list>

<name>LIST NAME HERE</name>

<description>LIST DESCRIPTION HERE</description>

<emailOwnerOnChange>1</emailOwnerOnChange>

<welcomeOnManualAdd>1</welcomeOnManualAdd>

<welcomeOnSignupAdd>0</welcomeOnSignupAdd>

<welcomeMessageId>DESIRED WELCOME MESSAGE ID HERE</welcomeMessageId>

</list>

</lists>

JSON:

[

{

"name":"LIST NAME HERE",

"description":"LIST DESCRIPTION HERE",

"emailOwnerOnChange":1,

"welcomeOnManualAdd":1,

"welcomeOnSignupAdd":0,

"welcomeMessageId":DESIRED WELCOME MESSAGE ID HERE

}

]

15 | P a g e

Create a Contact (NOTE: a “Subscriptions” request is still necessary after creating a contact to

add them to a particular list or lists.) XML:

<contacts>

<contact>

<email>j.contact@email.com</email>

<prefix> </prefix>

<firstName>Joe</firstName>

<lastName>Contact</lastName>

<suffix></suffix>

<street>123 Main St.</street>

<city>Somewhere</city>

<state>NY</state>

<postalCode>999999</postalCode>

<phone>919-555-1234</phone>

<business>iContact</business>

<status>normal</status>

</contact>

</contacts>

JSON:

[

{

"email":"j.contact@email.com",

"prefix":"",

"firstName":"Joe",

"lastName":"Contact",

"suffix":"",

"street":"123 Main St.",

"city":"Somewhere",

"state":"NY",

"postalCode":99999,

"phone":919-555-1234,

"business":"iContact",

"status":"normal"

}

]

16 | P a g e

Subscribe a Contact XML:

<subscriptions>

<subscription>

<contactId>CONTACT ID HERE</contactId>

<listId>LIST ID HERE</listId>

<status>normal</status>

</subscription>

</subscriptions>

JSON

[

{

"contactId":CONTACT ID HERE,

"listId":LIST ID HERE,

"status":"normal"

}

]

Create a Message XML:

<messages>

<message>

<campaignId>CAMPAIGN ID HERE</campaignId>

<subject>MESSAGE SUBJECT HERE</subject>

<messageType>normal</messageType>

<messageName>MESSAGE NAME HERE</messageName>

<htmlBody><![CDATA[<p>HTML CONTENT HERE </p>]]></htmlBody>

<textBody>TEXT CONTENT HERE</textBody>

</message>

</messages>

JSON:

{

"messages":[

{

"campaignId":CAMPAIGN ID HERE,

"subject":"MESSAGE SUBJECT HERE",

"messageType":"normal",

"messageName":"MESSAGE NAME HERE",

"htmlBody":"HTML CONTENT HERE",

"textBody":"TEXT CONTENT HERE"

17 | P a g e

}

]

}

- Support for the iContact API -

For more information on the iContact API you can visit http://developer.icontact.com.

If you cannot find the answer(s) to your question(s) there you may contact api@icontact.com or call 877-753-

6579 and our trained Technical Specialists will provide you with our award-winning Customer Support.

Thank you for choosing iContact for your

Email and Social Marketing Provider,

and thank you for using the iContact API!