API Endpoint

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

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.

• 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

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

curl https://api.emailer.emfluence.com/v1/helper/ping \
	-H "Authorization: Bearer {{accessToken}}"

{"success":1,"data":{"message":"pong"},"code":0,"requestID":"8852D59F-6170-4D87-8444D44546F59F29"}

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

curl https://api.emailer.emfluence.com/v1/helper/ping \
	-H "Authorization: Bearer {{accessToken}}"

{"success":1,"data":{"message":"pong"},"code":0,"requestID":"0232523A-D3CC-4DD3-A428DF4B69C21B6C"}

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

Failed Response

curl https://api.emailer.emfluence.com/v1/helper/missingmethod \
	-H "Authorization: Bearer {{accessToken}}"

{"success":0,"errors":["Invalid method \"missingmethod\" specified for resource \"/helper/missingmethod\". Available method(s): ping"],"data":{},"code":101,"requestID":"4904AA2F-5376-4476-953EC01C751898A4"}

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

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.

Paging

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

Example response with paging

curl https://api.emailer.emfluence.com/v1/contacts/search \
	-H "Authorization: Bearer {{accessToken}}"

{"success":1,"code":0,"data":{"paging":{"next":"https://api.emailer.emfluence.com/v1/contacts/search?page=2","page":1,"rpp":20,"totalPages":12,"totalRecords":200,"prev":""},"records":[{"firstName":"John","dateModified":"2013-06-12 15:45:00","contactID":123,"suppressed":0,"held":0,"email":"john.doe@example.com","userID":1,"lastName":"Doe"},{"firstName":"Jane","dateModified":"2013-06-12 15:45:00","contactID":456,"suppressed":0,"held":0,"email":"jane.doe@example.com","userID":1,"lastName":"Doe"},{"...":"..."}]},"requestID":"093D776F-897E-4C96-BC997F81787E487F"}

Error Codes

General Errors

Resource Errors

Authentication Errors

Record Errors

Parameter Errors

Retrying Failed Requests

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.

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-11-20 16:11:02").

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.

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:

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.

curl https://api.emailer.emfluence.com/v1/contacts/save \
	-H "Authorization: Bearer {{accessToken}}" \
	-H "Content-Type: application/json" \
	-X POST \
	-d '{
			"email": "john.doe@example.com",
			"firstName": "John",
			"lastName": "Doe"
		}'

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.

curl https://api.emailer.emfluence.com/v1/contacts/import \
	-H "Authorization: Bearer {{accessToken}}" \
	-H "Content-Type: application/json" \
	-X POST \
	-d '{
			"contacts": [
				{
					"email":"john.doe1@example.com",
					"firstName":"John",
					"lastName":"Doe"
				},
				{
					"email":"john.doe2@example.com",
					"firstName":"John",
					"lastName":"Doe II"
				},
				{
					"email":"jane.doe@example.com",
					"firstName":"Jane",
					"lastName":"Doe"
				}
			]
		}'

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