Page Comparison

Table of Contents:

API quick start

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

...

1. In order to connect to your Ongage account via the API, you'll need the Username and Password of the Ongage User who will be using and issuing the API commands, along with your Account Code, that you can find under the Account Profile page: 
   
   
    Note: the Account Code is a unique alphanumeric string and is not the numeric Account ID
   
   
   
   

2. These are the credentials you'll need to send in the request header:

   Code Block
   X_USERNAME: your_ongage_username X_PASSWORD: your_ongage_password X_ACCOUNT_CODE: your_ongage_account_code

   
   

 It is recommended that the API User be either an Admin or General User. For a list of user types see the User Management help guide.

 Also see our API Code Examples section.

How to Indicate List Id in Ongage API Calls

...

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. 
  •  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

...

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.
   
   1. If you issue more API calls beyond the 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:

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

...

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

Appendix

API Exception response sample 

...