Welcome to the Ezepo API. These services will allow you to extend your application to leverage the newest and most powerful email compliance technology available today. We're always here to help integrate your technology with ours. You may contact us through our Support Center or via email at support@ezepo.com.
Building a full featured integration between your platform and Ezepo involves simple, secure and structured access from both parties. The Ezepo APIs described in this document will allow your platform to obtain the required data on demand for integrations ranging from very basic through fully fledged seamless user experiences.
Access to Ezepo
Integration with Ezepo only requires very simple communication from the software partner. Users should be able to supply the software partner with the endpoint of their Ezepo instance and the administrative API key for their Ezepo instance within your user interface. Ezepo has available a simple Test API to verify the communication between the software partner and the Ezepo instance.
When a new offer is added to the partner system Ezepo requires that a request for a new list be sent via the New List API.
Access to the Partner Platform
Integration will require basic access to the software partner. This basic access will allow Ezepo to provide analytics, compliance monitoring and streamlined data entry. The minimum required API access is as follows.
Authentication is required for each request you send to the Ezepo API. Each request you make to Ezepo must be made to your specific endpoint domain and include your administrative API key or a valid affiliate API key. These values can be found in the Admin Settings in your Ezepo control panel.
The Ezepo Test API is used to verify connectivity with the Ezepo instance. This API is accessible at the administrative level as well as the affiliate level.
GET Request Endpoint
| https://YOURENDPOINT/api/test/ |
Required Fields
| key | Your administrative API key or a valid affiliate API key. |
System Responses
All responses are returned in JSON format with proper HTTP status codes. For example, requests that fail authentication will return with a "401 Unauthorized" status code in the HTTP header. The data fields which will be returned upon a successful GET request are as follows.
| status | Possible responses are (1 = Valid Administrative Key | 2 = Valid Affiliate Key) |
Example Use
A basic test request would be made similar to the following example.
https://YOURENDPOINT/api/test/?key=00000000000000000000000000000000The expected response would be similar to the following example.
{ "status": 1 }If the request is met with an error, for example an invalid key the HTTP response code would be "401 Unauthorized" and the response will be similar to the following example.
{ "error": "Access denied. Please check your API Key and try again." }The links API may be used to obtain both unsubscribe and data access links from Ezepo. This API is available at both the affiliate and administrative levels.
GET Request Endpoint
| https://YOURENDPOINT/api/links/ |
Required Fields
| key | Your administrative API key or a valid affiliate API key. |
| affid | The ID of the affiliate you would like to generate links for. |
| src | The numeric source platform ID your link should reference. Available options are (1 = Internal | 2 = Cake | 3 = Everflow | 4 = LeadsPedia). |
| listid | The ID of the list you would like to generate links for. |
| link_type | The type of link you would like to generate with this request. Available options are (download | unsub). |
System Responses
All responses are returned in JSON format with proper HTTP status codes. For example, requests that fail authentication will return with a "401 Unauthorized" status code in the HTTP header. The data fields which will be returned upon a successful GET request are as follows.
| link | The full URL requested from the system. |
Example Use
A basic data access link request would be made similar to the following example.
https://YOURENDPOINT/api/links/?key=00000000000000000000000000000000&affid=000&src=1&listid=000&link_type=downloadThe expected response would be similar to the following example.
{ "link": "http://YOURENDPOINT/download/000/000/1/00000000000000000000000000000000" }A basic unsubsribe link request would be made similar to the following example.
https://YOURENDPOINT/api/links/?key=00000000000000000000000000000000&affid=000&src=1&listid=000&link_type=unsubThe expected response would be similar to the following example.
{ "link": "http://YOURENDPOINT/unsubscribe/000/000/000/1/00000000000000000000000000000000" }If the request is met with an error, for example an invalid key the HTTP response code would be "401 Unauthorized" and the response will be similar to the following example.
{ "error": "Access denied. Please check your API Key and try again." }The list info API may be used to obtain information on all the opt-out lists in the system or on a single list. This is both an administrative and affiliate level API, however the affiliate API key will return a limited data set while the administrative API key will provide access to all list information. Requests made without a listid value specified will return records for all lists in the Ezepo instance.
GET Request Endpoint
| https://YOURENDPOINT/api/lists/ |
Required Fields
| key | Your administrative API key or a valid affiliate API key. |
Optional Fields
| listid | The ID of the list you would like to obtain information about. |
System Responses
All responses are returned in JSON format with proper HTTP status codes. For example, requests that fail authentication will return with a "401 Unauthorized" status code in the HTTP header. The data fields which will be returned upon a successful GET request are as follows.
| listid | The list ID within the Ezepo system. |
| name | The public name for the list. |
| active | The active setting for the list. |
| format | The download type for the list. |
| count * | The current number of addresses on the list. |
| last_upload * | The last date data was manually uploaded to the list. |
| notes * | Any internal notes for the list. |
* These fields are only available when making a request using the administrative API key.
Example Use
A list query made using the administrative API key without a list ID specified would be similar to the following example.
https://YOURENDPOINT/api/lists/?key=00000000000000000000000000000000The expected response would be similar to the following example.
{ "lists": [
{
"listid": "1",
"name": "List 1",
"active": "Y",
"format": "txt",
"count": "1000",
"last_upload": "00/00/0000",
"notes": "Plain text notes."
},
{
"listid": "2",
"name": "List 2",
"active": "Y",
"format": "txt",
"count": "2000",
"last_upload": "00/00/0000",
"notes": "Plain text notes."
}
] }The same request performed using an affiliate API key would produce a response similar to the following.
{ "lists": [
{
"listid": "1",
"name": "List 1",
"active": "Y",
"format": "txt"
},
{
"listid": "2",
"name": "List 2",
"active": "Y",
"format": "txt"
}
] }If the request is met with an error, for example an invalid key the HTTP response code would be "401 Unauthorized" and the response will be similar to the following example.
{ "error": "Access denied. Please check your API Key and try again." }The list data API consists of three primary components which allow you to obtain opt-out list data on demand. These three components are an initial data request, a job status query and finally a download request. This is both an administrative and affiliate level API.
To obtain opt-out data you must first send a request for a specific list using the fetch endpoint.
GET Request Endpoint
| https://YOURENDPOINT/api/lists/fetch/ |
Required Fields
| key | Your administrative API key or a valid affiliate API key. |
| listid | The ID of the list you would like to fetch data from. |
| format | The data format you would like to download for this list. Available options are (txt | md5) |
System Responses
All responses are returned in JSON format with proper HTTP status codes. For example, requests that fail authentication will return with a "401 Unauthorized" status code in the HTTP header. The data fields which will be returned upon a successful GET request are as follows.
| status | The status code for this request. |
| jobid | The job ID for your specific fetch process. |
| message | A plain text status message for this transaction. |
Example Use
Your initial list data request would be made similar to the following example.
https://YOURENDPOINT/api/lists/fetch/?key=00000000000000000000000000000000&listid=000&format=txtThe expected response would be similar to the following example.
{ "status": 1, "jobid": "XXXXXXXXXXXXXXXX", "message": "A new job has been created with id XXXXXXXXXXXXXXXX" }Once the initial request has been processed Ezepo will return a jobid as in the example above. This jobid value will allow you to check on the status of your job. The Ezepo system will prepare your data and provide status information in real time as part of the second step of this procedure. Using the status endpoint your application should be designed to loop and wait for this process to be completed before moving on to the third and final step of this procedure. The recommended interval for status requests is 30 seconds though longer polling times are acceptable.
GET Request Endpoint
| https://YOURENDPOINT/api/lists/fetch/status/ |
Required Fields
| key | Your administrative API key or a valid affiliate API key. |
| jobid | The jobid value returned from your initial fetch request. |
System Responses
All responses are returned in JSON format with proper HTTP status codes. For example, requests that fail authentication will return with a "401 Unauthorized" status code in the HTTP header. The data fields which will be returned upon a successful GET request are as follows.
| status | The status value for this job. (working | complete) |
Example Use
Your status request would be made similar to the following example.
https://YOURENDPOINT/api/lists/fetch/status/?key=00000000000000000000000000000000&jobid=XXXXXXXXXXXXXXXXThe expected response would be similar to the following example if the job is still running.
{ "status": "working" }The expected response would be similar to the following example if the job is complete and ready for download.
{ "status": "complete" }After your job has been completed and the status request has returned the string "completed" as shown in the above example your application may move to the third and final step of this procedure, downloading the data. This request will return a zip archive of the requested which is ready to use. No JSON response will be issued unless there is an error.
GET Request Endpoint
| https://YOURENDPOINT/api/lists/fetch/download/ |
Required Fields
| key | Your administrative API key or a valid affiliate API key. |
| jobid | The jobid value returned from your initial fetch request. |
Example Use
Your download request would be made similar to the following example.
https://YOURENDPOINT/api/lists/fetch/download/?key=00000000000000000000000000000000&jobid=XXXXXXXXXXXXXXXXThe expected response would be a zip archive containing the requested data.
The new list API is used to create lists within an Ezepo instance. This API is only accessible at the administrative level.
GET Request Endpoint
| https://YOURENDPOINT/api/newlist/ |
Required Fields
| key | Your administrative API key. |
| listid | The ID of the list you would like to create. |
| name | The name of the list you would like to create. |
Optional Fields
Passing these two additional fields of data in your request will allow the new list to bypass the New List Queue as no additional configuration is required. Requests which do not pass both of these optional fields or contain invalid values for these fields will still be serviced, the newly created list will be available in the New List Queue awaiting final configuration by a user.
| type |
The numeric list type. Defines if the opt-out site is enabled to collect new data.
Available options are (1 = Opt-Out Site On | 2 = Opt-Out Site Off). |
| format |
The format in which data should be stored for this list.
Available options are (txt = Plain Text | md5 = MD5 Hashed) |
System Responses
All responses are returned in JSON format with proper HTTP status codes. For example, requests that fail authentication will return with a "401 Unauthorized" status code in the HTTP header. The data fields which will be returned upon a successful GET request are as follows.
| status | Possible responses are (1 = Success) |
Example Use
A new list request would be made similar to the following example.
https://YOURENDPOINT/api/newlist/?key=00000000000000000000000000000000&listid=000&name=List%20NameThe expected response would be similar to the following example.
{ "status": 1 }If the request is met with an error, for example an invalid key the HTTP response code would be "401 Unauthorized" and the response will be similar to the following example.
{ "error": "Access denied. Please check your API Key and try again." }The affiliates API may be used to obtain information about all affiliates in your Ezepo system or information about a specific affiliate. This is an administrative level API, requests made using affiliate API keys will not be serviced. Requests made without an affid value specified will return records for all affiliates in the Ezepo instance.
GET Request Endpoint
| https://YOURENDPOINT/api/affiliates/ |
Required Fields
| key | Your administrative API key. |
Optional Fields
| affid | The ID of the affiliate you would like to request information about. |
System Responses
All responses are returned in JSON format with proper HTTP status codes. For example, requests that fail authentication will return with a "401 Unauthorized" status code in the HTTP header. The data fields which will be returned upon a successful GET request are as follows.
| link | The full URL requested from the system. |
Example Use
An affiliate query made without an affiliate ID specified would be similar to the following example.
https://YOURENDPOINT/api/affiliates/?key=00000000000000000000000000000000The expected response would be similar to the following example.
{ "affiliates": [
{
"affid": "1",
"source": "Manual",
"name": "Affiliate 1",
"affiliate_key": "00000000000000000000000000000000"
},
{
"affid": "2",
"source": "Manual",
"name": "Affiliate 2",
"affiliate_key": "00000000000000000000000000000000"
}
] }If the request is met with an error, for example an invalid key the HTTP response code would be "401 Unauthorized" and the response will be similar to the following example.
{ "error": "Access denied. Please check your API Key and try again." }