API
- Ongage OngageConnect
- Noam Rotem
- Stepin\ Shashin Petel
Table of Contents:
The Ongage API
General Introduction
IMPORTANT
Before starting here, please visit our API FAQ for all basics and getting started questions.
The Ongage UI is written completely on top of the Ongage API! Meaning anything you can do in the UI you can do with the API and more!
The Ongage API is a modern full-featured JSON REST API.
Here are some online resources about REST:
No SDK is required in order to use the Ongage API all you need is:
An Ongage account.
API User Login credentials and account code (see API FAQ).
The desired API method described in the subsection of this document.
About API Access and Access Permission Denied HTTP 403
Note: your account needs to be allowed to have API access. See our pricing page to see if your plan includes API access or ask your account manager. If you don't have API access you will get an HTTP 403 permission denied response. |
|---|
The Ongage API Endpoint
The API endpoint URL is: https://api.ongage.net/api/<followed by the requested entity>
For example:
Overview of Key API Controllers
The Ongage API is organized into the following key controllers:
List: contains all the methods required to add, update, delete, unsubscribe, import and export contacts from your Ongage Lists.
Campaign: contains all the API methods related to creating emails, campaigns as well as sending transactional messages.
Report: contains the query report method which you can use to create and extract any type of aggregated analytic report that you'd like. This is the method used behind many of the analytics screens in Ongage.
ESP: has the get method for retrieving info on your current ESP connections.
All API Methods Organized in Subsection Pages
API Error Codes
HTTP Error Codes
400 Bad Request (usually invalid JSON provided).
401 Unauthorized (Please check your Username/Password/Account Code).
403 Forbidden (permission denied, check if you account is allowed to issue API calls, check if the API user you are using is authorized for API, is at least a General User, and has access to the list they're trying to access).
404 Not Found (check your URL for any typo and/or make sure the end-point is correct).
408 Request timeout
412 Precondition Failed (this HTTP code is used for ALL validation errors in the API).
429 Too Many Requests (you're making more than your allotted number of API calls per minute. See Misc. Technical Specs).
500 Internal Server Error (something has gone wrong on the API server).
503 Service Unavailable (Ongage API might be in maintenance/temporary overloading and is unable to handle any request).
504 Gateway Timeout (probably the API server failed to retrieve all the requested information from another server in a timely fashion, therefore, the call has failed).
Appendix
Empty Object Fields
Empty Object Fields Return as Empty Arrays
Note: every object field in the API, will return an empty array when empty, and not an empty object.
API Calls and User/Account Time Zones
To ensure that dates and times match the user or account time zone as shown in the Ongage UI, you need to include the time zone parameter in your API calls.
We recommend using Unix time-stamp when using the API.
In summary: You can pass either a Date in the format of dd/mm/yyyy hh24:mi or a Unix timestamp (e.g., 1491748377). In both cases, you need to specify the Time Zone to ensure the dates match what is shown in the Ongage UI. If no Time Zone is provided, it will default to GMT (also known as UT – Universal Time).
Example, API call: https://ongage.atlassian.net/wiki/spaces/HELP/pages/868057089/Report+API+Method
{
"select":[
"mailing_name",
"mailing_id",
"delivery_date"
],
"filter":[
[
"stats_date",
">=",
"2017-03-22"
]
],
"time_zone": "America/New_York", // Add Timezone that you have in UI.
"from":"mailing",
"group":[
"mailing_id"
]
}