API

Owned by Ongage OngageConnect
Last updated: Sept 02, 2024 by Stepin\ Shashin Petel
3 min read

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:

  1. Representational state transfer
  2. Using HTTP Methods for RESTful Services 

(info) No SDK is required in order to use the Ongage API all you need is:

  1. An Ongage account.
  2. API User Login credentials and account code (see API FAQ).
  3. The desired API method described in the subsection of this document.

About API Access and Access Permission Denied HTTP 403

(warning) 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

(info) Note: every object field in the API, will return an empty array when empty, and not an empty object.

Do API calls take into account the time zone of the Ongage user issuing the API call 

  • Yes when a user supplies a date format and not Unix time-stamp. If a Unix time-stamp is supplied in API call, then the time-zone adjustment is not performed.
    • Having said that we recommend using Unix time-stamp when using the API.
  • When you issues a call to an API method that includes a date and/or date time-stamp (e.g., dd/mm/yyyy hh24:mi) that is not a Unix time-stamp (e.g., 1491748377), the API will automatically reconfigure those to the time-zone setting of the API user. 
  • So for example, in the following sample JSON the analytics report will be based on the day according to the time zone of the user who issued this 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"
      ]
   ],
   "from":"mailing",
   "group":[
      "mailing_id"
   ]
}

Json Formatters and Validators