Getting Started

This page includes information about connecting your application to the emfluence Marketing Platform to accomplish your marketing goals through the use of our API.

If you do not currently have an emfluence Marketing Platform account, please schedule a demo and an account representative will contact you.

Versions

The current version of the API is Version 1. Version 0 has been retired.

Changelog

General Guidelines

  • All API calls should be made with either HTTP POST or GET (some requests are limited to POST only).
  • HTTP status codes will always be 200. You can consider any non-200 HTTP status code an error.
  • All methods are accessed with the basic structure: https://api.emailer.emfluence.com/v1/{RESOURCE}/{METHOD}
  • All responses are serialized as JSON

Requests

All requests must be over https.

API Endpoint

https://api.emailer.emfluence.com/v1

All API URLs listed in this documentation are relative to https://api.emailer.emfluence.com/v1. For example, the /helper/ping API call is reachable at https://api.emailer.emfluence.com/v1/helper/ping.

URL Structure

https://api.emailer.emfluence.com/{VERSION}/{RESOURCE}/{METHOD}

For example, https://api.emailer.emfluence.com/v1/helper/ping will call the "ping" method on the "helper" resource.

List of available endpoints

Passing Request Data

POST requests must pass parameters as JSON in the request body with the content type set to application/json. The documentation for each call will provide details on the accepted parameters. Any request that modifies data must be a POST, so it may be simpler to always use POST from your application.

GET requests pass parameters as simple name/value pairs (just passing variables in the url). GET requests can be useful for simple testing of search/lookup calls which can even be done in the browser.

URL parameters take precedence over duplicate parameters passed in the request body.

Authentication

OAuth

The emfluence Marketing Platform API uses OAuth 2.0 for making authorized requests. A client ID and client secret are provided by emfluence and can be used for obtaining access tokens. Two types of access tokens are supported: application-only and user.

Application-Only Access Tokens

Application-only access tokens allow requests to be made on behalf of the application itself (as opposed to on behalf of a specific user). Actions performed with this access token will be executed as a system-generated "API User" which has the client administrator role.

To obtain an application-only access token, make a POST request to the application access token endpoint, passing your clientID and clientSecret as JSON in the request body. Content-Type should be application/json.

This is a manual process that should only be done when initially setting up your application, or if you need to renew your application's access token.
Application Access Token Endpoint
https://emailer.emfluence.com/login/oauth/applicationAccessToken

Parameters

Name Type Details
clientID string Required. The client ID that was provided by emfluence.
clientSecret string Required. The client secret that was provided by emfluence. Never share or expose the client secret!

Sample Request to Retrieve Application-Only Access Token

POST
https://emailer.emfluence.com/login/oauth/applicationAccessToken
cURL
Copy

Response

Your application should receive a JSON response with the access token. This access token should be saved and used when making API requests for your application. Access tokens should be treated with the sensitivity of passwords. Never share or expose them.

Response Data
{"accessToken":"3BC90A14-6647-479D-AEAF-52F05ED5EAFE"}

Errors

If there is an error retrieving an access token, you will receive a JSON response containing an error message. Some possible reasons for errors:

  • Request not over https
  • Request method not POST
  • Invalid JSON provided
  • Invalid clientID or clientSecret provided
Sample Error Response
{"error":"HELPFUL ERROR MESSAGE"}

User Access Tokens

User access tokens allow your application's users to identify themselves to the emfluence Marketing Platform. Your application does not store our user's login credentials. Each API call executes in the context of the user represented by the access token.

We do not currently expire access tokens. However, it is possible that the user's access token will become invalid if they explicitly reject your application.

You should plan that a user's access token may become invalid at any time and you will need to re-authorize for that user in the case that it does.

The following steps describe the flow that your application should implement if you would like to allow users to authorize your application for making API requests on their behalf.

Step 1: Direct the user's browser to the authorization URL

https://emailer.emfluence.com/login/oauth/authorize

Parameters

All requests to the authorization url must include the parameters clientID and redirectURI. Additional parameters can optionally be provided and will be appended to the URL when the user is sent back to the redirectURI.

Name Type Details
clientID string Required. The client ID that was provided by emfluence.
redirectURI string Required. The location that the user will be sent after granting or denying authorization for your application. Must be https.
Sample Authorization URL
https://emailer.emfluence.com/login/oauth/authorize/?clientID=16FC69C6-0306-434C-BD73-6F02FCBAB839&redirectURI=https://yourapp.com

Response

The user will first be prompted to login if they are not already logged in to the emfluence Marketing Platform. They will then be asked to either grant or deny authorization for your application.

If the user chooses not to authorize your application, they will be sent to the redirectURI along with an error parameter stating that authorization was denied.

Failed Authorization
https://yourapp.com?error=authorization_denied

If the user chooses to authorize your application they will be sent to the redirectURI along with a request token in a code parameter. You will exchange the request token for an access token in Step 2.

Successful Authorization
https://yourapp.com?code=3BC90A14-6647-479D-AEAF-52F05ED5EAFE

Step 2: Exchange request token for access token

Since this request includes your client secret, it should be made with server-side code so that your secret is not exposed.

After receiving the request token, your application should quickly exchange that for an access token. This is done by making a POST request to the user access token endpoint, passing your clientID, clientSecret, and the code you received from Step 1 as JSON in the request body.

User Access Token Endpoint
https://emailer.emfluence.com/login/oauth/accessToken

Parameters

Name Type Details
clientID string Required. The client ID that was provided by emfluence.
clientSecret string Required. The client secret that was provided by emfluence.
code string Required. The request token obtained in Step 1

Sample Request to Retrieve User Access Token

POST
https://emailer.emfluence.com/login/oauth/applicationAccessToken
cURL
Copy

Response

Your application should receive a JSON response with the access token. This access token should be saved and used when making API requests for the user.

Response Data
{"accessToken":"3BC90A14-6647-479D-AEAF-52F05ED5EAFE"}

Errors

If there is an error exchanging the code (request token) for an access token, you will receive a JSON response containing an error message. If you receive an error, you will need to restart the OAuth process. Some possible reasons for errors:

  • Request not over https
  • Request method not POST
  • Invalid JSON provided
  • Invalid code (request token) provided
  • Invalid clientID or clientSecret provided
Sample Error Response
{"error":"HELPFUL ERROR MESSAGE"}

Authenticating Requests

Never expose access tokens in client-side code. If you're using JavaScript, use a server-side proxy. Whoever has the access token has the ability to use the API, so keep it safe and secret.

Parameter "accessToken" must be passed with every request. Some example API calls in the documentation may exclude the accessToken parameter for the sake of brevity.

Pass accessToken in authorization header:

POST
/helper/ping
cURL
Copy
Request Headers
Authorization: bearer 3BC90A14-6647-479D-AEAF-52F05ED5EAFE

Pass accessToken with JSON data in request body:

POST
/helper/ping
cURL
Copy

Pass accessToken in the URL:

GET
/helper/ping?accessToken=3BC90A14-6647-479D-AEAF-52F05ED5EAFE
cURL
Copy

Responses

All responses are serialized as JSON. Content type is application/json; charset=UTF-8. Bulk export files are returned using application/zip (zipped plain text files).

HTTP Status Codes

The HTTP status code returned should always be 200 (OK). If it's not, something went wrong. Always check for a 200 and then analyze the response data to determine if your call was successful or not.

Requests blocked due to connection limits will return a 403.

Successful Response

GET
/helper/ping
cURL
Copy
Response Data

All responses will contain these 3 keys, no matter what.

Name Type Details
success boolean Did the call succeed? Always check this!
data struct Contains all data for response. Empty struct for calls that don't return anything.
code integer Always 0 on successful calls, otherwise an error code.

Failed Response

GET
/helper/missingmethod
cURL
Copy
Response Data

Note how code now contains the number of the error and errors has been added to the response.

All failed responses (success=0) will contain an errors array.
Name Type Details
errors array Array of error message strings. If success = 0, this key will always be available so check it for details about what happened

Some responses may contain additional keys based on various conditions. These may provide helpful information, but are not critical to the successful handling of a response.

Name Type Details
warnings array Array of warning message strings. Some requests can return warnings even if the request succeeded. For example, when importing contacts, 1 record might fail due to invalid data while all the others succeed.
extrainfo string Helpful information about the request. The purpose is to help with development and debugging.

Paging

All successful responses that can return multiple records (not lookups) will always contain a "paging" struct in the response data.

Name Type Details
next string URL to get the next page of results. Will be blank if on the last page.
prev string URL to get the previous page of results. Will be blank if on the first page.
page integer Page number of results returned.
rpp integer Records per page. Defaults to 20, and has a default max value of 50. Both of these values may vary depending on the specific call.
totalPages integer Total number of pages in results.
totalRecords integer Total number of records in results (you can check this to see if your call returned any results).

Example response with paging

GET
/contacts/search
cURL
Copy
Response Data

Handling Errors

All failed requests will return an error code that can be used to help identify the problem. Along with the error code, a helpful error message will be included in the response.

GET
/groups/lookup?groupID=0
cURL
Copy
Response Data

Error Codes

The details for each code shown here are generic and are for documentation purposes only. You are better off using the error message returned in the response because it will be specific to your request.

General Errors

Code Details
1 Unexpected error
2 Invalid HTTP request method (use GET or POST, some methods allow POST only)
3 Access denied
4 Request not over https
5 Too many concurrent requests

Resource Errors

Code Details
100 Invalid resource (check your URL)
101 Invalid method for resource (check your URL)

Authentication Errors

Code Details
200 Invalid access token
201 Invalid client account
202 Invalid user account
203 Invalid application
204 Insufficient permissions

Record Errors

Code Details
300 Record not found
301 Duplicate record
302 Invalid action for record (e.g. trying to send an email that's already sent)
303 Record forbidden (only applies to Restricted Users)

Parameter Errors

Code Details
500 Invalid parameter data type (e.g. passing "hello" for a date parameter)
501 Invalid parameter value (e.g. passing 100 for a parameter that cannot exceed 99)
502 Required parameter missing

Miscellaneous

Handling Dates/Times

Values for date input parameters should be passed in yyyy-mm-dd format. If a time portion is given for a date input parameter, it will be ignored.

All datetime values are based on GMT using the 24-hour format yyyy-mm-dd hh:mm:ss (e.g. "2018-07-21 02:07:51").

Values for datetime input parameters must be converted to GMT. You can pass the just date portion in yyyy-mm-dd format, however, the value will NOT be converted from GMT without a time portion which can produce unexpected results. For this reason, it is recommended to always include the time portion with datetime input parameters.

Connection Limits

Anything over 5 simultaneous connections per access token or IP address will return an HTTP status code of 403 (Forbidden). As a general rule, avoid making multiple simultaneous connections except when absolutely necessary.

Rate Limits

Our approach to rate limiting is to throttle (slow down) requests that exceed our threshold rather than block them outright.

More than 9 requests per second will result in throttling.

Throttling basically just forces you to slow down. It will not result in an error.

The header X-API-RateLimit-Throttled will be included in the response with details. For example:

X-API-RateLimit-Throttled: Request was throttled for 2 seconds. 2 requests are running.  The maximum is 5 requests.  4 requests processed in the last 1 second

User Permissions

When authenticating with a user access token, some endpoints require the associated user to have specific permissions. These permissions can be only managed through the emfluence Marketing Platform. If an endpoint requires a specific permission, it will be indicated in its documentation.

To retrieve a user's permissions, use the users/lookup endpoint.

If a call fails due to a permissions error, you will receive the following error:

{
		    "code": 204,
		    "success": 0,
		    "errors": [
		        "Access to this endpoint requires the permission '{permisison label}'"
		    ],
		    "data": {}
		}
		

List of available roles/permissions:

Roles
  • Restricted User

    User can only work with Contacts and Emails they create (own).

  • Client Administrator

    Administrator account for a given client. Has full access to all client functions.

Content
  • Manage Signatures

    User can manage their signatures

  • Upload Images

    User can upload images

  • Content Blocks

    User can manage content blocks

Email Management
  • Send Mail

    User can send emails.

  • Compose Mail

    User can compose emails.

  • Approve Mail

    User must approve emails.

  • Pre-Flight

    User can send Pre-Flight message tests

  • Manage Templates

    User can create and manage templates

  • Email Coder

    User can create emails without using a template

Group Management
  • Create Groups

    User can create contact groups.

  • Contacts (Delete)

    User can delete contact records

  • Contacts (Add)

    User can add contact records

  • Contacts (Edit)

    User can edit contact records

  • Contacts (Import)

    User can import contact groups

  • Contacts (Export)

    User can export contact groups

Pages
  • Manage Landing Pages

    User can create and manage landing pages

Social Media
  • Social Media Admin

    User can create, edit and delete social media accounts. User can access and send social media messages from social media accounts they have access to.

  • Social Media Contributor

    User can access and send social media messages from social media accounts they have access to.

Surveys
  • Survey Admin

    User can manage surveys and view responses

  • Survey Viewer

    User can only view survey responses

Common Tasks

An access token is required for the example API calls below. If you have not acquired one yet, please refer to the Authentication section for instructions.

Managing Contacts

In the emfluence Marketing Platform, email addresses (along with other information for an individual) are stored as contact records. This section will focus on the endpoints that you can use for managing contact records. View full list of endpoints for managing contacts.

Single Contact

Individual contact records can be saved using the contacts/save endpoint. The email parameter is the only required field when adding a new contact. Existing records can be updated by contactID or email address. Email addresses must be unique.

The example below saves a contact by providing the email, firstName, and lastName parameters.

POST
/contacts/save
cURL
Copy

Multiple Contacts

If you have multiple contacts that need to be saved, the contacts/import endpoint can be used to save them all in a single request. Like saving a single contact, this endpoint handles both adding new records and updating existing records.

The example below demonstrates how you could use this endpoint to save several contacts to your account.

POST
/contacts/import
cURL
Copy

Sending Emails

There are a several different ways that the API can be utilized to send emails to your contacts. Regardless of the type of email you are working with in the API, you will need to know how to build email content.

Transactional Emails

Transactional emails are intended for individual contacts and contain content that completes a transaction or process the recipient initiated (e.g. order receipt, password reset, etc...). Transactional emails should not be used to send marketing content.
Learn more about sending transactional emails

Marketing Emails

Marketing emails are sent to multiple contacts (or groups of contacts). The content is generally promotional in nature and is subject to CAN-SPAM and international laws governing email.
Learn more about sending marketing emails

Automated Emails

Automated (or auto-response) emails are associated with a single source group in the emfluence Marketing Platform and are sent/triggered when contacts are added to that group. Automated emails themselves are not managed through the API, however, you can trigger an automated email through the API by adding contacts to its source group.
Learn more about sending automated emails