Events & Trigger API Methods

Owned by Pratik Upadhyay
Last updated: Oct 22, 2024 by Stepin\ Shashin Petel
4 min read

Table of Contents:

(info) Note: Notice that in each API call you must provide the List ID that you are working on, otherwise the default List ID will be used. 

Methods Summary

DELETE /api/events/<Event ID>

Description 

This method deletes an event.

GET /api/events/<Event ID>

Description 

This method gets a single event.

GET /api/events

Description 

This method fetches a collection of events.

Request

name

Required string

Event's internal friendly name. For your use only.

sort

Optional string - Column name

order

Optional string - "ASC" or "DESC"

offset

Optional int

limit

Optional int

POST /api/events

Description 

This method creates a new event.

Request

name

Required string - Event's internal friendly name. For your use only.

description

Optional string - Event description. For your use only

based_on

Optional string - "mailing" / "date_field" / "recurring"

mailing_id

Required for events based_on mailing integer - Mailing ID

date_field_name

Required for events based_on date_field string - Date field name

annually_event

Optional for events based_on date_field boolean

ongoing_event

Optional boolean

start_date

Required for events with ongoing_event = FALSE

integer (UTC unix timestamp) OR string (date format)

end_date

Required for events with ongoing_event = FALSE

integer (UTC unix timestamp) OR string (date format)

status

Required boolean - Event status, TRUE for active, FALSE for inactive

segments

Required array of integers - Segments to associate with this event

segments_excluded

Optional array of integers - Segments to exclude from this event

distribution

Required array of arrays - ESP distribution configuration.

You can specify multiple ESPs with different percentage of delivery.

*domain: String of domain name or "default"

*esp_connection_id: Required only when domain is "default", Numeric ID

*esps: Required when domain is not "default". Array of key/value = esp_id/percent

triggers

Required array of triggers - Each trigger need to include the following parameters:

Trigger based_on = "list_field"

*based_on Required - string - "list_field"

*email_messages Required - array of integers - Array of email message IDs

*days_diff Required - integer

*send_on_days Required - array - Array of days in week [ "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" ]

*operator Required - string - "before" / "after"

*schedule_hour Required - integer - Schedule hour (0-23)

*schedule_minute Required - integer - Schedule minute (0-59)

Trigger based_on = "mailing"

*based_on Required - string - "list_field"

*email_messages Required - array of integers - Array of email message IDs

*days_diff Required - integer

*email_operator Required - string - "sent" / "opened" / "not_opened" / "clicked" / "not_clicked" / "open_not_clicked"

*operator Required - string - "after"

*schedule_hour Required - integer - Schedule hour (0-23)

*schedule_minute Required - integer - Schedule minute (0-59)

Trigger based_on = "trigger"

*based_on Required - string - "list_field"

*based_on_trigger Required - integer - The position of the trigger in the array that this trigger is based on (first=1)

*email_messages Required - array of integers - Array of email message IDs

*days_diff Required - integer

*email_operator Required - string - "sent" / "opened" / "not_opened" / "clicked" / "not_clicked" / "open_not_clicked"

*operator Required - string - "after"

*schedule_hour Required - integer - Schedule hour (0-23)

*schedule_minute Required - integer - Schedule minute (0-59)

Trigger based_on = "list"

*based_on Required - string - "list_field"

*email_messages Required - array of integers - Array of email message IDs

*schedule_hour Required - integer - Schedule hour (0-23)

*schedule_minute Required - integer - Schedule minute (0-59)

*recurrence Required - object - associative object of key & values with the following acceptable keys:

*pattern -string- (acceptable values: "daily")

Example - Event based on birth_date field

POST URL: https://api.ongage.net/<list_id>/api/events

  • First trigger will be sent at 10:30 on contact's birth date
  • Second trigger will be sent after 7 days only if the contact didn't open first trigger's message, the email will be sent at 19:45
{
 "name": "Birth date event",
 "based_on": "date_field",
 "date_field_name": "birth_date",
 "annually_event": true,
 "ongoing_event": true,
 "status": true,
 "segments": [ 60478 ],
 "distribution": [
  {
   "esp_connection_id": 60142,
   "domain": "default",
   "percent": 100
  }
 ],
 "triggers": [
  {
   "based_on": "list_field",
   "email_messages": [ 2381 ],
   "days_diff": 0,
   "operator": "after",
   "schedule_hour": 10,
   "schedule_minute": 30
  }
 ]
}
{
 "name": "Based on recurring campaign list",
 "based_on": "recurring",
 "status": true,
 "segments": [ 60478 ],
 "start_date": "18-02-2018",
 "end_date": "18-03-2018",
 "distribution": [
  {
   "esp_connection_id": 60142,
   "domain": "default",
   "percent": 100
  }
 ],
 "triggers": [
  {
   "based_on": "list",
   "email_messages": [ 2381 ],
   "operator": "after",
   "schedule_hour": 19,
   "schedule_minute": 45,
   "recurrence" : {
      "pattern":"daily"
   }
  }
 ]
}
{
 "name": "Based on mailing",
 "based_on": "mailing",
 "status": true,
 "segments": [ 60659 ],
 "mailing_id": 35847,
 "start_date": "2017-12-15",
 "end_date": "2017-12-25",
 "distribution": [
  {
   "esp_connection_id": 60142,
   "domain": "default",
   "percent": 100
  }
 ],
 "triggers": [
  {
   "based_on": "mailing",
   "email_messages": [ 2381 ],
   "days_diff": 0,
   "operator": "after",
   "email_operator": "not_opened",
   "schedule_hour": 10,
   "schedule_minute": 30
  }
 ]
}

PUT /api/events/<Event ID>

Description 

This method is used to update an existing event.

Request

name

Required string - Event's internal friendly name. For your use only.

description

Optional string - Event description. For your use only

esp_connections_quota

Optional array - Update ESP connections quota

emails_limit

Optional number - Update global emails quota

PUT /api/events/<Event ID>/status

Description 

This method is used to Toggle the event status.

The "status" flag acts as toggle to start/stop the event. When this call is made on an active event, this method will deactivate it, and vise versa.