icontact-api
v0.3.1
Published
Promisified interface for the iContact and iContact Pro REST APIs
Downloads
123
Readme
iContact API
icontact-api provides a pomisified interface for iContact and iContact Pro's REST APIs.
To install icontact-api, use npm:
$ npm install icontact-api
Examples
Instantiating an IContactAPI Object
import IContactAPI from 'icontact-api';
const iContactAPI = new IContactAPI('my app id', 'my username', 'my password');
iContactAPI.setAccountId(9999999);
iContactAPI.setClientFolderId(9999);
iContact and iContact Pro
By default, the IContactAPI object will attempt to connect to the iContact Pro REST API. To instantiate an object that will connect to regular iContact, pass false
for the optional fourth constructor parameter:
const iContactAPI = new IContactAPI('my app id', 'my username', 'my password', false);
Sandbox Account
To connect to an iContact Sandbox account, pass true
for the optional fifth constructor parameter.
const iContactAPI = new IContactAPI('my app id', 'my username', 'my password', false, true);
Note that iContact Pro doesn't have a sandbox and the fifth parameter will be ignored.
Searching for a Contact
// search by contactId
iContactAPI.getContacts({ contactId: 23 }).then((results) => {
console.log(results);
});
// search by state and firstName with pattern matching
iContactAPI.getContacts({ state: 'MD', firstName: 'John*' }).then((results) => {
console.log(results);
});
Add or Update a Contact and Subscribe It to a List
If you issue a contact creation request when a contact already exists (same email address), the old contact will be overwritten and any fields you don't provide will be blank on the resulting contact. To avoid this, see if a contact exists first and then issue either a create contacts request or an update contact request.
Note: Subscribing a contact to a list at the time of contact creation is a feature of version 2.3 of iContact's REST API. At the time of writing, only iContact Pro supports this version. If connecting to iContact, rather than iContact Pro, create a contact first and then subscribe it to a list using IContact.subscribeContactToList.
const contact = {
email: '[email protected]',
firstName: 'John',
lastName: 'Doe',
subscriptions: [
{
email: '[email protected]',
listId: 5,
status: 'normal'
},
],
};
iContactAPI.getContacts({ email: contact.email }).then((results) => {
if (results.total === 0) {
return iContactAPI.addContacts([contact]);
} else {
return iContactAPI.updateContact(results.contacts[0].contactId, contact);
}
}).then((results) => {
console.log(results);
});
Reference
- IContact.setTimeout
- IContact.getTimeout
- IContact.setAccountId
- IContact.getAccountId
- IContact.setClientFolderId
- IContact.getClientFolderId
- IContact.getContacts
- IContact.addContacts
- IContact.updateContact
- IContact.replaceContact
- IContact.deleteContact
- IContact.getLists
- IContact.createLists
- IContact.subscribeContactToList
setTimeout
IContact.setTimeout(timeout: number): void;
Sets the request timeout in miliseconds
getTimeout
IContact.getTimeout(): number;
Returns the current request timeout in miliseconds
setAccountId
IContact.setAccountId(accountId: number): void;
Sets the iContact account ID
getAccountId
IContact.getAccountId(): number | null;
Returns the current iContact account ID
setClientFolderId
IContact.setClientFolderId(clientFolderId: number): void;
Returns the current iContact client folder ID
getClientFolderId
IContact.getClientFolderId(): number | null;
Returns the current iContact client folder ID
getContacts
IContact.getContacts(searchParameters: IContact): Promise<IContactSearchResult>;
Retrieves the contacts matching the search parameters
addContacts
IContact.addContacts(contacts: IContact[]): Promise<any>;
Adds new contacts--remember to subscribe them to a list
updateContact
IContact.updateContact(id: number, contact: IContact): Promise<any>;
Updates a contact, replacing only the fields supplied
replaceContact
IContact.replaceContact(id: number, contact: IContact): Promise<any>;
Completely replaces a contact--must include email
deleteContact
IContact.deleteContact(id: number): Promise<any>;
Deletes a contact
getLists
IContact.getLists(searchParameters?: IList): Promise<IListSearchResult>;
Retrieves the lists matching the search parameters
createLists
IContact.createLists(lists: IList[]): Promise<any>;
Adds new lists
subscribeContactToList
IContact.subscribeContactToList(contactId: number, listId: number, status?: IListStatus): Promise<any>;
Subscribes a contact to a list
Testing
Tests were written with mocha and chai.
Run them with
$ npm test
Testing will require an iContact or iContact Pro account. Provide the credentials in an .env
file, following the example in .env.example
.