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.

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
  • All requests must pass an accessToken parameter in the Authorization header. To get an access token, please contact support.

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 header set to application/json and should include a valid Content-Length header. 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

  • An access token must be passed in the Authorization header with every request.
  • Each API call executes in the context of the user represented by the access token.
  • We do not currently expire access tokens.
  • Access tokens are managed from user records within the emfluence Marketing Platform. Learn more
  • Retrieving Application-Only access tokens has been deprecated. Learn more
  • Passing access tokens in the request body or querystring has been deprecated. Learn more
Access tokens should be treated with the sensitivity of passwords. Never share or expose them. If you are 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.

Some sample API calls in the documentation may exclude the accessToken parameter for the sake of brevity.

GET
/helper/ping
cURL
Copy
Response Data

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

The response will always contains the success, data, and code keys.

Name Type Details
success boolean Did the call succeed? Always check this!
data object Contains all data for response. Empty object for calls that don't return anything.
code integer Always 0 on successful calls, otherwise an error code.
requestID guid Unique identifier of the request. Useful for debugging.

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" object 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 should 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 (e.g. a user trying to lookup a record they don't have access to)

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

Retrying Failed Requests

Errors that are related to the request (URI, request method, data, etc...) should not be retried without addressing the cause of the error.

When to retry a failed request:

  • The request was not processed. This can be due to a network issue (e.g. connection timeout) or if you received a non-200 HTTP status code.
  • Unexpected error (error code: 1)
  • Connection limits (error code: 5)

Error Handling Best Practices

  • Never assume your code will work! Always use try/catch logic.
  • Log failed requests and capture as much information about the request and response you can.
  • Use a notification system so someone knows requests are failing.

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. "2024-03-19 02:03:08").

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 IP address may 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 '{permission label}'"
		    ],
		    "data": {}
		}
		

List of available roles/permissions:

Roles
  • Restricted user

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

  • Notifications-only user

    User can only receive system notifications.

Roles
  • Client admin

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

Connections
  • Connections Admin

    User can manage connections to 3rd party applications

Content
  • Manage Signatures

    User can manage their signatures

  • Upload Images

    User can upload images

  • Content Blocks

    User can manage content blocks

  • Manage QR Codes

    User can manage QR codes

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

  • List Cleanse

    User can run list cleanses on contacts and view the results

Pages
  • Manage Landing Pages

    User can create and manage landing pages

Reseller
  • Reseller Admininistrator

    Reseller Administrator

SMS
  • SMS Admin

    User can view, create, and send SMS messages

  • SMS Viewer

    User can only view SMS messages

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