Developer Documentation - FireDrum Email Marketing
Developer Documentation
live_help

API v2 Documentation

The API provides a way to integrate your system with ours, keeping all your data in sync. It allows you to retrieve and manipulate your data just as you can on the web site but without the fancy interface.

Actions

The API is comprised of many individual actions. Each API request must specify an action using the action parameter. To see a complete list of the actions, go to the Actions tab. Action names start with a prefix that indicates the type of data involved, which can help you find the action you want.

Accessing the API

You can access the API using standard web protocols. API requests are made using either HTTP GET or HTTP POST.

The API is located at the following URL:

https://api.firedrumemailmarketing.com/api/v2.jsp

A typical API request using HTTP GET looks like the following:

https://api.firedrumemailmarketing.com/api/v2.jsp?action=<ActionName>&authAPIKey=<YourAPIKey>&paramN=<ValueN>

Parameters

The API parameters are extracted from the query parameters of an HTTP GET or from the request body of an HTTP POST. There is a special, optional parameter — params — that can be a JSON object containing parameters. The parameters in the params object will be overriden by any parameters of the same name in the query string or request body.

Arrays

Parameters whose names end with [] support multiple values (arrays).

Some JSON frameworks, such as JSON.NET, might have problems mapping parameters with brackets in the name to object properties. To work around this limitation, name your object properties with a suffix like "_Array" in place of the square brackets. Then after serializing the object for the request, or before deserializing the response, swap our your suffix for the square brackets.

Authentication

There are three different types of authentication used in the API — API Key, username and password, and none.

API Key

To access the majority of the API, you will need an API key. You can get a key and manage your keys using the API itself, but the easiest way to get a key is by using the API Key panel in your Configure Account page. Provide your API key using the authAPIKey parameter. Here's an example API request URL that uses an API Key:

https://api.firedrumemailmarketing.com/api/v2.jsp?action=Category_Add&authAPIKey=1234567890abcdef&name=New+Category&sortSequence=3&publicDisplay=true

Username/Password

Actions that retrieve or manipulate your API Keys require username and password for authentication instead of an API key. Here's an example API request URL that uses username and password:

https://api.firedrumemailmarketing.com/api/v2.jsp?action=APIKey_List&username=scott&password=tiger

None

There are a couple of actions that provide public information and do not require authentication. Here's an example API request URL that requires no authentication:

https://api.firedrumemailmarketing.com/api/v2.jsp?action=API_ActionSchemas

Response

The API responses are always in JSON (JavaScript Object Notation) format. JSON can represent complex data structures yet still be easily readable by humans, which is handy for debugging. The response is a JSON object comprised of three things — the properties unique to each action, the response code, and the echoed request parameters.

Response Code

A response always includes a response code object under the responseCode property. The response code object has two properties — id and name. The response code indicates whether the request was successful or encountered errors. Response code ID 0 indicates success. All other response codes indicate an error condition.

To see the full list of response codes, go to the Response Codes tab.

Parameter Echo

Under the params property, a response includes a copy of the parameters given in the request. This can be useful for debugging, but it can also be convenient when handling the responses.

Pretty Output

A response does not normally include any unnecessary whitespace. This can be difficult to read, however, when you need to do testing or debugging. To have the API return its responses with structural whitespace, add the prettyOutput=true parameter to any request. Here's an example using pretty output:

https://api.firedrumemailmarketing.com/api/v2.jsp?action=API_ActionSchemas&prettyOutput=true

Time Zones

Some parameters in a requested action, as well as some data fields in the response, are made up of a date and time. The format for these request parameters is listed in the schema as "dateTime".

The time zone for all input DateTimes and output DateTimes will be in the time zone associated with the account of the authenticating API key, unless the "useUTC" parameter is set to true.

The "useUTC" parameter is an optional boolean parameter that can be provided for any requested action. The "useUTC" parameter defaults to false. When the "useUTC" parameter is true, the time zone for all input DateTimes and output DateTimes will be UTC.

For example:

https://api.firedrumemailmarketing.com/api/v2.jsp?action=APIKey_List&username=scott&password=tiger&useUTC=true

Parameters and fields that are dates without a time portion are not affected by time zones or the "useUTC" parameter.

API Changes

There are times when we need to make changes to the API. These changes come in 3 forms:

  • New Actions - Actions will be added to expand the capabilities of the API. These additions will not affect your existing use of the API.
  • Additions to an Existing Action - When possible, any changes to an existing Action will be done as additional, optional parameters. The defaults to the new parameters will be implemented in such a way that any existing use of the API will not break or have significant, unreasonable behavior changes.
  • Changes to an Existing Action - In cases where changes are necessary to the parameters or behavior of an existing Action, we will try to provide these as new versions of the API when possible. If the change must be made to an existing version of the API, then we will try to provide API users with as much advance notice as possible so that they can adjust their integration code if necessary.

Assistance

While we strive to make the API easy to understand and use, it does still require some technical skill, so if you don't have a programmer available, please contact us for a quote on API integration assistance.