eConnect Email API 1.0

Introduction

To help you in integrating eConnect Email into your external applications, we have exposed some of the functionalities in the form of API methods that will allow you to remotely carry out specific functions to manage your eConnect Email account. In this version of the API (version 1.0), we have included several methods for you to manage your lists and subscribers. The API is actively being enhanced, and we will be adding on more methods over the course of time.

Submitting to the API

The URL to use to submit to eConnect Email API 1.0 must be in this format:

http://api.startedm.com/1.0/<method>
[?api_key=<your_api_key>&param1=value1&param2=value2&...]

Examples:

To get a list of the mailing lists in your account, you will submit to the API like this:

http://api.startedm.com/1.0/getLists?api_key=abcdefghijklmnopqrstuvwxyz
To search for subscribers with the word “john” in their email addresses, you will submit to the API like this:

http://api.startedm.com/1.0/searchSubscribers?api_key=
abcdefghijklmnopqrstuvwxyz&email=john

The API Methods (eConnect Email API 1.0)

The table below shows the methods in eConnect Email API 1.0 that have been exposed for external applications to make use of. To learn more about the individual method, go to our API documentation page.

API Method	Description
getLists	Fetches all the lists or lists matching a given list name in the user’s account.
getSubscriber	Fetches the details of the subscriber specified by the subscriber ID.
searchSubscribers	Searches for subscribers by a set of criteria.
createSubscriber	Adds a new subscriber to a specific list.
updateSubscriber	Updates the email address and name of a specific subscriber.
deleteSubscriber	Deletes a specific subscriber from all the lists in the user’s account.
unsubscribeSubscriber	Unsubscribes a specific subscriber from all the lists in the user’s account.

Error Codes & Messages

When calling an API method, you should anticipate that sometimes you will receive an error due to occurrences such as invalid parameters being passed, or the item you are retrieving does not exist. When an error occurs, we will send back the error message and error code in the following XML format:

<response status="404">
   <errors>
      <error>
         <code>1101</code>
         <message>A valid API key is missing.</message>
      </error>
   </errors>
</response>

Note that we wrap the error item within an errors item, regardless of how many error items there are. In certain scenarios where there are multiple errors that have occurred, multiple error items will be returned wrapped inside a single errors item.

The following tables summarize the possible error codes and messages in eConnect Email API 1.0.

General System Errors (1xxx)

Authentication Errors (11xx)

Error code	Default error message	Description
1101	A valid API key is missing.	API key was not provided, or the provided API key was not a valid key.

Contact-Related Errors (2xxx)

List-Related Errors (21xx)

Error code	Default error message	Description
2101	List does not exist.	The list cannot be found in your account.

Subscriber-Related Errors (22xx)

Error code	Default error message	Description
2201	Subscriber cannot be added because the email address already exists in this list.	The email address already exists in your mailing list, and cannot be added again.
2202	Subscriber cannot be added because the email address is in the suppression list.	The email address exists in the suppression list, and cannot be added to your mailing list.
2203	Subscriber cannot be added because the email address is in the black list.	The email address exists in the black list, and cannot be added to your mailing list.
2204	Subscriber does not exist.	The subscriber cannot be found in your mailing lists.

Contact-Related Validation Errors (29xx)

Error code	Default error message	Description
2901	The required numeric list ID is missing.	The required numeric list ID was not provided.
2902	The provided list ID is not a numeric ID.	The list ID provided was not in numeric format.
2903	The required numeric subscriber ID is missing.	The required numeric subscriber ID was not provided.
2904	The provided subscriber ID is not a numeric ID.	The subscriber ID provided was not in numeric format.
2905	The required subscriber email address is missing.	The required subscriber email address was not provided.
2906	The provided subscriber email address is not a valid email address.	The subscriber email address provided was not in a valid email address format.
2907	The parameters passed are incomplete.	This method requires at least one or more of these to be provided: name, email address and list ID.
2908	The parameters passed are incomplete.	This method requires at least one or more of these to be provided: subscriber ID and email address.