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.
This method fetches a single segment including rules and associated mailings.
GET URL: https://api.ongage.net/<list_id>/api/segments/1112223334
{ "metadata": { "error": false }, "payload": { "id": "12345", "list_id": "12345", "name": "list fields segment", "type": "Active", "description": "", "favorite": "0", "last_count": "345", "last_count_date": "1502005048", "last_count_request_date": null, "isp_breakdown": "", "last_sent": "0", "segment_quota": "0", "is_quota_percent": "0", "created_by": "1234", "created": "1502005048", "modified_by": "1234", "modified": "1502005048", "user_modified": "1502005048", "deleted": "0", "included_segment_cache": null, "excluded_segment_cache": null, "default_include_segment": "0", "default_exclude_segment": "0", "is_external": "0", "external_url": null, "external_insert_missing": "0", "external_include_unsubscribes": "0", "rules": [ { "id": "1234", "segment_id": "12345", "position": "0", "left_parenthesis": "0", "field_id": "63337", "field_name": "email", "operator": "=", "operand": "[\"test@test.test\"]", "is_external_operand": "0", "right_parenthesis": "0", "condition": "and", "case_sensitive": "0", "type": "email", "group": "" }, { "id": "5678", "segment_id": "12345", "position": "1", "left_parenthesis": "0", "field_id": "63347", "field_name": "product_id", "operator": ">", "operand": "[\"12345\"]", "is_external_operand": "0", "right_parenthesis": "0", "condition": "and", "case_sensitive": "0", "type": "numeric", "group": "" }, { "id": "2696", "segment_id": "64548", "position": "2", "left_parenthesis": "0", "field_id": "63555", "field_name": "date", "operator": "=", "operand": "[1502966280]", "is_external_operand": "0", "right_parenthesis": "0", "condition": "and", "case_sensitive": "1", "type": "date_absolute", "group": "" } ], "mailings": [], "can_delete": true } } |
HTTP_Exception_404
list_id
Optional integer - List ID
sort
Optional string - Segment column name
order
Optional string - "ASC" or "DESC"
offset
Optional integer
limit
Optional integer (The default value is 50).
GET URL: https://api.ongage.net/<list_id>/api/segments
{ "metadata":{ "error":false, "total":"2" }, "payload":[ { "id":"35114", "list_id":"23939", "list_name":"My List", "name":"My segment 1", "type":"Active", "description":"Description for segment", "favorite":"0", "last_sent":"1403796208", "last_count":"214", "last_count_date":"1403796208", "created_by":"868", "created":"1403796208", "modified":"1403796208", "deleted":"0", "modifier":"John Doe" }, { "id":"34939", "list_id":"23939", "list_name":"My List", "name":"My segment 2", "type":"Active", "description":"", "favorite":"0", "last_sent":"1403016334", "last_count":"99", "last_count_date":"1403016334", "created_by":"868", "created":"1403016334", "modified":"1403016334", "deleted":"0", "modifier":"John Doe" } ] } |
This method is used to create a segment.
list_id
Optional number - The list id to which the segment should be saved under. Default - Default list ID
name
Required string - Segment name
type
Required string - Segment type (Active / Deleted)
is_whitelist
Optional boolean - Flag the segment as Whitelist Segment -this segment stakeholders will receive the campaign message under all circumstances
description
Optional string - Segment description
favorite
Optional boolean - Flag the segment as favorite
is_external
Optional boolean - External segment
external_url
Optional string - The URL from which to retrieve the external segment The 'criteria' parameter needs to be provided as empty with such segments. Once the segment is created, it can only be used as a campaign segment.
external_insert_missing
Optional boolean - Flag that equals TRUE tells the system that if contacts in the external Segment, that don't exist in your List database, should be added to the List (default FALSE), so that all opens, clicks, unsubscribes, bounces, etc. can be attributed to all the contacts in the external segment.
external_include_unsubscribes
Optional boolean - Flag that equals TRUE if unsubscribed contacts should be included in the segment (default FALSE)
criteria
Optional array - Segment rules criteria should include an array of segment rules, having:
Important: In case segment is a Whitelist Segment - the only allowed criteria type is "email" and the only allowed operator is "=".
POST URL: https://api.ongage.net/<list_id>/api/segments
{ "name":"My segment", "type":"Active", "description":"This is my segment", "criteria":[ { "field_id":1234, // Email "type":"email", "position":0, "operator":"LIKE", "operand":[ "gmail" ], "condition":"and" }, { "field_id":1235, // Birthdate "position":1, "operator":"<", "type":"date_absolute", "operand":[ 884404800 ], "condition":"and" } ] } |
Any configuration that does not follow the above requirements, will not be supported by GUI.
This method updates segments based on id from request and also saves in segment_rules table values in criteria. It returns single row with updated details.
list_id
Optional number - The list id to which the segment should be saved under. Default - Default list ID
name
Required string - Segment name
type
Required string - Segment type (Active / Deleted)
is_whitelist
Optional boolean - Flag the segment as Whitelist Segment -this segment stakeholders will receive the campaign message under all circumstances
description
Optional string - Segment description
favorite
Optional boolean - Flag the segment as favorite
criteria
Optional array - Segment rules criteria should include an array of segment rules, having:
Important: In case segment is a Whitelist Segment - the only allowed criteria type is "email" and the only allowed operator is "=".
For code examples see POST /api/segments method additional examples on this page.
Any configuration that does not follow the above requirements, will not be supported by GUI.
This feature is designed to serve customers, that do email marketing from within their own CRM and don't need the Ongage segmentation management feature, as they do their own segmentation directly from within their CRM. After creating a segment, as an external segment (using the POST api/segments with the external flag set to true) use this method to then populate the external segment with email addresses and their accompanying dynamic list field data. For more about external segments see "What are External Segments" in our Segments documentation.
PUT URL: https://api.ongage.net/<list_id>/api/segments/1112223334/populate_external
{ "recipients":[ { "email":"jane.doe1@somedomain.com", "first_name":"Jane", "last_name":"Doe-1" }, { "email":" jane.doe2@somedomain.com ", "first_name":"Jane", "last_name":"Doe-2" }, { "email":" jane.doe3@somedomain.com", "first_name":"Jane", "last_name":"Doe-3" }, { "email":" jane.doe4@somedomain.com ", "first_name":"Jane", "last_name":"Doe-4" } ] } |
This method deletes a segment. By deleting segment, this method will also unschedule any scheduled campaign using this segment.
This endpoint is deprecated, please use POST /api/export instead.
This endpoint is deprecated, please use GET /api/export/<Export ID>/retrieve instead.
GET URL: https://api.ongage.net/<list_id>/api/segments/1112223334
{ "metadata": { "error": false }, "payload": { "id": "12345", "list_id": "12345", "name": "list fields segment", "type": "Active", "description": "", "favorite": "0", "last_count": "345", "last_count_date": "1502005048", "last_count_request_date": null, "isp_breakdown": "", "last_sent": "0", "segment_quota": "0", "is_quota_percent": "0", "created_by": "1234", "created": "1502005048", "modified_by": "1234", "modified": "1502005048", "user_modified": "1502005048", "deleted": "0", "included_segment_cache": null, "excluded_segment_cache": null, "default_include_segment": "0", "default_exclude_segment": "0", "is_external": "0", "external_url": null, "external_insert_missing": "0", "external_include_unsubscribes": "0", "rules": [ { "id": "2697", "segment_id": "64549", "position": "0", "left_parenthesis": "0", "field_id": "0", "field_name": "ocx_created_date", "operator": "<=", "operand": "[\"13\"]", "is_external_operand": "0", "right_parenthesis": "0", "condition": "and", "case_sensitive": "0", "type": "date_relative", "group": "" }, { "id": "2698", "segment_id": "64549", "position": "1", "left_parenthesis": "0", "field_id": "0", "field_name": "ocx_unsubscribe_date", "operator": "=", "operand": "[1503705600]", "is_external_operand": "0", "right_parenthesis": "0", "condition": "and", "case_sensitive": "0", "type": "date_absolute", "group": "" }, { "id": "2699", "segment_id": "64549", "position": "2", "left_parenthesis": "0", "field_id": "0", "field_name": "ocx_resubscribe_date", "operator": ">=", "operand": "[1503705600]", "is_external_operand": "0", "right_parenthesis": "0", "condition": "and", "case_sensitive": "0", "type": "date_absolute", "group": "" }, { "id": "2700", "segment_id": "64549", "position": "3", "left_parenthesis": "0", "field_id": "0", "field_name": "ocx_import_id", "operator": "=", "operand": "[\"13\",\"23456\"]", "is_external_operand": "0", "right_parenthesis": "0", "condition": "and", "case_sensitive": "0", "type": "numeric", "group": "" } ], "mailings": [], "can_delete": true } } |
GET URL: https://api.ongage.net/<list_id>/api/segments/1112223334
{ "metadata": { "error": false }, "payload": { "id": "12345", "list_id": "12345", "name": "list fields segment", "type": "Active", "description": "", "favorite": "0", "last_count": "345", "last_count_date": "1502005048", "last_count_request_date": null, "isp_breakdown": "", "last_sent": "0", "segment_quota": "0", "is_quota_percent": "0", "created_by": "1234", "created": "1502005048", "modified_by": "1234", "modified": "1502005048", "user_modified": "1502005048", "deleted": "0", "included_segment_cache": null, "excluded_segment_cache": null, "default_include_segment": "0", "default_exclude_segment": "0", "is_external": "0", "external_url": null, "external_insert_missing": "0", "external_include_unsubscribes": "0", "rules": [ { "id": "2701", "segment_id": "64550", "position": "0", "left_parenthesis": "0", "field_id": "0", "field_name": "sent", "operator": "=", "operand": { "mailing_ids": [ "84715", "84668", "84666" ], "esp_connection_ids": [], "time_range": [], "repeat": { "operator": "<", "counter": "5" }, "browsers": [], "countries": [], "platforms": [] }, "is_external_operand": "0", "right_parenthesis": "0", "condition": "and", "case_sensitive": "0", "type": "behavioral", "group": "" }, { "id": "2702", "segment_id": "64550", "position": "1", "left_parenthesis": "0", "field_id": "0", "field_name": "opened", "operator": "!=", "operand": { "mailing_ids": [ "84715", "84668", "84666" ], "esp_connection_ids": [ "60129", "60128", "60367" ], "time_range": { "operator": "between", "in_last": "10", "in_last_unit": "day", "to": "1", "to_unit": "month" }, "repeat": { "operator": "<", "counter": "5" }, "browsers": [ "Chrome" ], "countries": [ "AF", "BD", "IO" ], "platforms": [ "Linux" ] }, "is_external_operand": "0", "right_parenthesis": "0", "condition": "and", "case_sensitive": "0", "type": "behavioral", "group": "" }, { "id": "2703", "segment_id": "64550", "position": "2", "left_parenthesis": "0", "field_id": "0", "field_name": "clicked", "operator": "=", "operand": { "mailing_ids": [], "esp_connection_ids": [ "60129" ], "time_range": { "operator": "custom", "from_date": 1501545600, "to_date": 1504137600 }, "repeat": [], "browsers": [], "countries": [], "platforms": [] }, "is_external_operand": "0", "right_parenthesis": "0", "condition": "and", "case_sensitive": "0", "type": "behavioral", "group": "" } ], "mailings": [], "can_delete": true } } |
POST URL: https://api.ongage.net/<list_id>/api/segments
{ "name":"My segment", "type":"Active", "description":"This is my segment", "criteria":[ { "field_id":1234, // First name "type":"string", "position":0, "operator":"LIKE", "case_sensitive":"1", "operand":[ "James", "Peter", "David" ], "condition":"and" } ] } |
POST URL: https://api.ongage.net/<list_id>/api/segments
{ "name":"My Group segment", "type":"Active", "description":"This is my segment", "criteria":[ { "field_id":1233, // Email "type":"string", "position":0, "operator":"LIKE", "operand":[ "@gmail" ], "condition":"and" }, { "field_id":1234, // First name "type":"string", "group":"First name or last name or address", "position":1, "left_parenthesis":1, "operator":"notempty", "condition":"and" }, { "field_id":1235, // Last name "type":"string", "group":"First name or last name or address", "position":1, "operator":"notempty", "condition":"or" }, { "field_id":1236, // Address "type":"string", "group":"First name or last name or address", "position":2, "right_parenthesis":1, "operator":"notempty", "condition":"or" } ] } |
POST URL: https://api.ongage.net/<list_id>/api/segments
{ "name":"Behavioral Segment", "type":"Active", "criteria":[ { "type":"behavioral", "position":1, "field_name":"opened", "operator":"=", "operand":{ "mailing_ids":[ 85362, 85360 ], "esp_connection_ids":[ 60133, 60387 ], "time_range":{ "operator":"between", "in_last":30, "in_last_unit":"day", "to":2, "to_unit":"month" }, "browsers":[ "Chrome" ], "countries":[ "AZ", "BH" ], "platforms":[ "Linux", "Win8.1" ] }, "condition":"and" }, { "type":"behavioral", "position":1, "field_name":"clicked", "operator":"=", "operand":{ "time_range":{ "operator": "custom", "from_date": 2017-02-01 10:30:00, "to_date": 2017-02-23 10:30:00 } }, "condition":"and" } ] } |
POST URL: https://api.ongage.net/<list_id>/api/segments
{ "name":"Segment Based on Import ID", "type":"Active", "description":"Segment based on Import ID", "criteria":[ { "condition":"and", "field_name":"ocx_import_id_all", "type":"numeric", "position":0, "operator":"=", "operand":[ "11111111" ] } ] } |
POST URL: https://api.ongage.net/<list_id>/api/segments
{ "name":"Whitelist Segment", "type":"Active", "description":"This is a Whitelist Segment", "is_whitelist": true, "criteria":[ { "field_id":1234, // Email "type":"email", "position":0, "operator":"=", "operand":[ "james@test.com", "peter@test.com", "david@test.com" ], "condition":"and" } ] } |
POST URL: https://api.ongage.net/<list_id>/api/segments
{ "name":"Segment with date relative rules", "type":"Active", "description":"This segment has relative rules", "criteria":[ { "field_id":1234, // Some date field "type":"date_relative", "position":0, "operator":"<=", "operand":{ "days": 6 }, "condition":"and" }, { "field_id":5678, // Another date field "type":"date_relative", "position":0, "operator":">", "operand":{ "hours": 16 }, "condition":"and" } ] } |