Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents:

Table of Contents

API quick start

Want to get started with the Ongage API? Here's where to start! 


  • For adding/updating large amounts of contacts aka bulk import, use this class of API methods: Import API Methods.
  • This is the same CSV import as appears in the UI. This API, enables users to automate imports, rather than upload them manually.
  • When adding/updating more than a hundred contacts, and particularly when adding/updating big volumes list data fields, or if you're doing a daily or nightly batch update of your Ongage list, use the POST /api/import command – instead of the of the contacts methods above.

How to Issue a Transactional Email or SMS via the API

  • Transactional messages (email or SMS) can be issued using the following API method: POST /api/transactional/send
  • Typical scenarios for transactional emails are welcome emails upon registering or a receipt following a purchase transaction. 
    • (info) To be noted that welcome emails don't have to be API coded, as Ongage offers an automatic built-in welcome email feature, that can be setup from the List Settings Page (see there help section on "How to Setup a List Welcome Email").
  • Each List comes with 1 default transactional campaign already setup, but you can add additional campaigns for different types of transactional emails with the following method: 
    POST api/transactional which is used to create a new transactional mailing campaign.
  • If you don't indicate a mailing_id when calling the transactional mailing method, then all mailing stats and data will get associated with the default transactional campaign for that list.
  • By default when issuing a call to send a transactional message, the contact's status (unsub, bounce, complant status) is ignored, that's in order to accommodate sending receipts regardless if the contact is unsubscribed or not (similarly suppression lists are also ignored). The Transactional method does have flags to indicate whether to take into account the status and/or suppression list . See details about the check_status flag and check_global_and_list_suppression flag under the API method: POST /api/transactional/send
  • When issuing a Transactional message you can either indicate the Email/SMS Message ID or Send HTML/Text  Content in the body of API Call. In the latter case you will need to encode the HTML code passed in the body of the call by using some function like: json_encode($html-email); (See example here: POST /api/notify_transactions).


  • All of campaign/aggregated analytics reports that you see in the Ongage UI (User Interface), behind the scenes use the Ongage  API reporting method: POST /api/reports/query
    Image Modified

How can I retrieve the Ongage Contact Activity Report


How many API calls can I issue per minute

  1. The default limit is 300 API calls every 60 seconds (i.e., 300 API calls per minute). This limit can be increased (even by a lot), based on your Ongage package. Please consult Ongage support for more information on this matter. The API limit for you account, you can find in your Account → Profile Page, under the 'Account Limits' section of the page see: 'Maximum number of API calls allowed per minute'
    Image Modified

    1. If you issue more API calls beyond your account limit, you will get a denied response with HTTP 429 error (see below).
    2. This is done in order to ensure stable and continuous API service.
    3. Therefore in your code you should have a built-in retry and back-off mechanism, in order to manage that rate, so even if you breach the limit and get denied, you can resend it according to the allowed rate.
    4. Suggested exponential back-off: 1 minute, 2 minutes, 4 minutes, 8 minutes, 16 minutes.
  2. Moreover, you can have no more than 10 API calls running in parallel at any given time.

HTTP Error Code 429

See previous section right above this, for the context regarding this error message. Here is what the HTTP 429 error code looks like:

Code Block
    "metadata": {
        "error": true
    "payload": {
        "code": 429,
        "errors": [],
        "message": "Calls per minute exceeded"


How to Handle HTTP 5xx Error Codes


(info) For a list of all HTTP Error Codes see the Appendix at the bottom of this API Guide


API Exception response sample