List API Methods

Owned by Pratik Upadhyay
Last updated: Oct 07, 2024 by Stepin\ Shashin Petel
6 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. You can review the possible ways to provide List ID in this link.

Methods Summary

GET /api/lists/<List ID>

Description 

This method fetches a list.

Response Example

GET URL: https://api.ongage.net/api/lists/<list_id>

{
  "metadata": {
    "error": false
  },
  "payload": {
    "id": 12345,
    "name": "Another List",
    "notification_email": null,
    "description": "",
    "type": "sending",
    "hash_type": "",
    "last_count": 0,
    "last_active_count": 0,
    "unsubscribes": 0,
    "unsubscribe_default_link": true,
    "complaints": 0,
    "last_stats_date": null,
    "last_events_stats_date": null,
    "last_transactional_stats_date": null,
    "bounces": 0,
    "unsubscribe_success_html": null,
    "unsubscribe_confirmation_html": null,
    "unsubscribe_confirmation_button": "",
    "unsubscribe_redirect_url": null,
    "frequencies": null,
    "frequency_active": false,
    "frequency_html": null,
    "frequency_button": "",
    "frequency_field_id": null,
    "external_url_wrapper": "",
    "expiration_date": 0,
    "scope": null,
    "default_transactional_id": 12345,
    "welcome_email_id": null,
    "welcome_email_active": false,
    "welcome_email_esp_connection_id": null,
    "welcome_sms_id": null,
    "welcome_sms_active": false,
    "welcome_sms_connection_id": null,
    "welcome_sms_per_segment": null,
    "allowed_provider_connection_ids": null,
    "public_key": null,
    "image_host_base": null,
    "tracking_domain": null,
    "sms_field_id": null,
    "modified_counts": 0,
    "archive": false,
    "segment_welcome_emails": null,
    "included_segment_cache": null,
    "excluded_segment_cache": null,
    "header_template_id": null,
    "footer_template_id": null,
    "cke_keep_spaces_empty_blocks": false,
    "preprocess_minutes": null,
    "imports_concurrent_limit": 2,
    "demo_list_step": "",
    "link_query_params": null,
    "account_id": 1,
    "created": 1617541368,
    "modified": 1617541368,
    "deleted": null
  }
}

GET /api/lists

Description 

This method returns a collection of all lists in a given account, along with info regarding list type and accompanying settings of each list.

Request

name

Optional string - List name

type

Optional string - "sending" or "suppression"

sort

Optional string - List column name

order

Optional string - "ASC" or "DESC"

offset

Optional int

limit

Optional int

Possible Filters

  • "name" - list name exactly matches the given value
  • "name_like" - list name contains the given value
  • "type" - list type (sending/suppression)
  • "hash_type" - hash type applicable for suppression type only (md5/sha256/sha512)
  • "scope" - suppression list scope (global/list/campaign)
  • "archive" - filtering archived lists (true/false)
  • "deleted" - filtering deleted lists (true/false)

Response Example - Sending List

GET URL: https://api.ongage.net/api/lists?type=sending

{
"metadata": {
  "error": false,
  "total": 1
},
"payload": [
{
  "id": 60299,
  "account_id": 60306,
  "name": "my sending list",
  "description": "",
  "type": "sending",
  "last_count": 0,
  "last_active_count": 0,
  "unsubscribes": 0,
  "complaints": 0,
  "last_stats_date": null,
  "bounces": 0,
  "unsubscribe_success_html": null,
  "unsubscribe_confirmation_html": null,
  "unsubscribe_confirmation_button": "",
  "frequencies": null,
  "frequency_active": false,
  "frequency_html": null,
  "frequency_button": "",
  "external_url_wrapper": "",
  "expiration_date": 0,
  "scope": null,
  "welcome_email_id": null,
  "welcome_email_active": true,
  "public_key": null,
  "image_host_base": "",
  "tracking_domain": "",
  "welcome_email_esp_connection_id": null,
  "sms_field_id": null,
  "frequency_field_id": null,
  "modified_counts": 0,
  "archive": false,
  "segment_welcome_emails": null,
  "included_segment_cache": null,
  "excluded_segment_cache": null,
  "default": false,
  "created": 1448288565,
  "modified": 1448536004,
  "deleted": null
  }
 ]
}

Response Example - Suppression List

GET URL: https://api.ongage.net/api/lists?type=suppression&hash_type=md5 (To fetch MD5 Suppression lists Only)
GET URL: https://api.ongage.net/api/lists?type=suppression&hash_type=sha256 (To fetch SHA256 Suppression lists Only)
GET URL: https://api.ongage.net/api/lists?type=suppression&hash_type=sha512 (To fetch SHA512 Suppression lists Only)

{
 "metadata": {
   "error": false,
   "total": 1
 },
 "payload": [
 {
   "id": 60300,
   "account_id": 60306,
   "name": "my suppression list",
   "description": "",
   "type": "suppression",
   "last_count": 0,
   "last_active_count": 0,
   "unsubscribes": 0,
   "complaints": 0,
   "last_stats_date": null,
   "bounces": 0,
   "unsubscribe_success_html": null,
   "unsubscribe_confirmation_html": null,
   "unsubscribe_confirmation_button": "",
   "frequencies": null,
   "frequency_active": false,
   "frequency_html": null,
   "frequency_button": "",
   "external_url_wrapper": "",
   "expiration_date": 0,
   "scope": "campaign",
   "welcome_email_id": null,
   "welcome_email_active": false,
   "public_key": null,
   "image_host_base": null,
   "tracking_domain": null,
   "welcome_email_esp_connection_id": null,
   "sms_field_id": null,
   "frequency_field_id": null,
   "modified_counts": 0,
   "archive": false,
   "segment_welcome_emails": null,
   "included_segment_cache": null,
   "excluded_segment_cache": null,
   "default": false,
   "created": 1448373288,
   "modified": 1448373288,
   "deleted": null
  }
 ]
}

POST /api/lists

Description 

This method creates a new List.

Request

name

Required string

type

Required string - "suppression" or "sending"

description

Optional string

create_segment

Optional boolean - Will create a "All List Contacts" segment

fields

Optional array - Default: Copy the fields from the default list

expiration_date

Optional timestamp or date format - For "suppression" list only

scope

Optional string - For "suppression" list only, "global" or "list" or "campaign". Default: "global"

suppress_in_lists

Optional array - For "suppression" list only. It is need when creating list level Suppression lists to provide "sending_list_id" that you want to connect this suppression with. 

hash_type

Optional string - For "suppression" list only, indicates if lists support contacts in md5, sha256, or sha512 format.  

Request Example - Sending list with Default Fields

POST URL: https://api.ongage.net/api/lists

{
"name":"test",
"type":"sending"
}

Request Example - Sending list Additional Fields

{
 "name": "my_list_name",
 "type": "sending",
 "description": "This is my list",
 "create_segment": true,
 "fields":
 [
  {
   "name": "email",
   "title": "email",
   "type": "email",
   "mandatory": true,
   "position": 0
  },
  {
   "name": "full_name",
   "title": "Full Name",
   "type": "string",
   "mandatory": false,
   "position": 1
  },
  {
   "name": "field3",
   "title": "field3",
   "type": "numeric",
   "mandatory": true,
   "position": 2
  }
 ]
}

Request Example - Suppression List

POST URL: https://api.ongage.net/api/lists

{
"name": "suppression list test",
"description": "",
"type": "suppression"
}

Request Example - Suppression List with MD5 hashing

POST URL: https://api.ongage.net/api/lists

{
"name": "suppression MD5 hash",
"description": "",
"type": "suppression",
"hash_type": "md5",
"expiration_date": ""
}

Request Example - List Level Suppression List

POST URL: https://api.ongage.net/api/lists

{
"name": "list level suppression",
"description": "",
"type": "suppression",
"scope": "list",
"suppress_in_lists": [
"<list_id>" 
],
"expiration_date": ""
}


PUT /api/lists/<List ID>

Description 

This method updates and existing list.

Request

name

Required string

description

Optional string

expiration_date

Optional timestamp or date format - For "suppression" list only

scope

Optional string - For "suppression" list only, "global" or "list" or "campaign". Default: "global"

unsubscribe_default_link

Optional boolean - An unsubscribe link is mandatory for each email. if you set the default unsubscribe link to false, you must define an unsubscribe link yourself in the content_html part

unsubscribe_confirmation_html

Optional string - Unsubscribe confirmation page displayed after pressing the unsubscribe link

unsubscribe_confirmation_button

Optional string - The text on the Unsubscribe confirmation button. The confirmation button will appear at the bottom of the page, centralized

unsubscribe_success_html

Optional string - Unsubscribe success page displayed after a successful unsubscribe

frequency_active

Optional boolean - activate list level frequencies (the defa)

frequency_html

Optional string - must be provided if frequency_active is set to true. the text that will be displayed before the frequencies select box

frequencies

Optional array of objects - must be provided if frequency_active is set to true.

*active : true/false

*title : "string"

*value : "Frequency1"/"Frequency2"/"Frequency3"

Request Example - List with unsubscribe part

PUT URL: https://api.ongage.net/api/lists/<list_id>

{
 "name": "my_list_name",
 "type": "sending",
 "description": "This is my list",
 "welcome_email_active": false,
 "unsubscribe_default_link": true,
 "unsubscribe_confirmation_html" : "<p>Are you sure you wannt to unsubscribe?</p>",
 "unsubscribe_confirmation_button" : "Unsubscribe",
 "unsubscribe_success_html": "<p>you have been successfully unsubscribe</p>",
 "frequency_active": true,
 "frequency_html" "<p>Choose how frequent would you like to receive our email</p>",
 "frequencies" : [
     {
         "active":true,
         "title":"Weekly",
         "value":"Frequency1"
     },
     {
         "active":true,
         "title":"Twice a month",
         "value":"Frequency2"
     },
     {
         "active":true,
         "title":"Monthly",
         "value":"Frequency3"
     }
  ]
}

POST /api/lists/<List ID>/copy

Description 

This method copies a list.

Example

POST api/lists/<list_id>/copy?
  Request = array (
  'create' => true,
  'name' => '<name>',
  'description' => '',
  'type' => 'sending',
  'default' => false,
)

DELETE /api/lists/<List ID>

Description 

This method deletes a list.