List API Methods
Table of Contents:
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"
Request Example - Sending list with Default Fields
POST URL: https://api.ongage.net/<list_id>/api/lists
{
"list_id":32,
"name":"testttt",
"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
}
]
}
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.