Segment API

Table of Contents
Remote Lists
Warning - Not all Clauses are Supported
Get a List of Stored Segments
Create New Segment
Retrieve a Single Segment
Update a Segment
Delete a Segment

Remote Lists

This API is not available on Remote Lists. API calls to these endpoints will return an error message if attempted on a Remote List.

Warning - Not all Clauses are Supported

Only the clauses listed in the Segment Definition are supported by this API. Other clauses will cause an invalid_request error to be returned.

Get a List of Stored Segments

Get a list of the basic details of all segments available to the requesting API key’s organization.

URL

Get a list of stored segments on the current organization:

GET /ga/api/v2/segments

Get a list of stored segments on the requested mailing list:

GET /ga/api/v2/mailing_lists/:mailing_list_id/segments

Request Parameters

name string	Filter all segmentation criterias with that exact name (case insensitive).
name_contains string	Filter all segmentation criterias that contain that name (case insensitive).

Response

The response will be a JSON array where each element contains the following keys.

This endpoint returns paginated records with a default page size of 2000.

id integer	The `id` of the segment.
mailing_list_id integer	The `id` of the mailing list that this segment belongs to.
name string	The name of the segment.
description string	A text description of this segment.

Example

GET /ga/api/v2/mailing_lists/8/segments

HTTP/1.1 200 OK

{
  "success": true,
  "data": [
    {
      "id": 8,
      "mailing_list_id": 8,
      "name": "Active Subscribers",
      "description": "All of the following criteria ... (Status is Active)"
    },
    {
      "id": 9,
      "mailing_list_id": 8,
      "name": "In Other List",
      "description": "All of the following criteria ... (Subscriber is active in the mailing list \"Other Mailing List Name\")"
    },
    {
      "id": 10,
      "mailing_list_id": 8,
      "name": "Active / In Other List",
      "description": "All of the following criteria ... (Status is Active) (Subscriber is active in the mailing list \"Other Mailing List Name\")"
    }
  ],
  "error_code": null,
  "error_message": null
}

Create New Segment

Create new segment using the Segment Definition.

URL

POST /ga/api/v2/mailing_lists/:mailing_list_id/segments

Request Parameters

mailing_list_id integer	The mailing list to which this segment will be attached.
include_sql boolean, default: `false`	Turn this option on to include in the response the actual SQL query that is run for this segment. If this parameter is specified as `true` or `1`, the response will include this data in a `criteria_sql` attribute.

Request Payload

segmentation_criteria
array of hashes

name string / required	The user-specified descriptive name for this segment.
clause array of hashes / required	The Segment Definition of the new segment.

Response

segmentation_criteria
hash

id integer	The `id` of the segment.
mailing_list_id integer	The `id` of the mailing list that this segment belongs to.
name string	The name of the segment.
description string	A text description of this segment.
clause array of hashes	The Segment Definition of the segment.

Example

POST /ga/api/v2/mailing_lists/25/segments

{
  "segmentation_criteria": {
    "name": "Not in the other list",
    "clause": [
      {
        "type": "in_mailing_list",
        "operator": "is not in",
        "mailing_list_id": 26
      }
    ]
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "id": 21,
    "mailing_list_id": 25,
    "name": "Not in the other list",
    "description": "All of the following criteria ... (Subscriber is not in the mailing list \"Other Mailing List Name\")",
    "clause": [
      {
        "type": "in_mailing_list",
        "operator": "is not in",
        "mailing_list_id": 26,
        "mailing_list": {
          "id": 26,
          "name": "Other Mailing List Name"
        }
      }
    ]
  },
  "error_code": null,
  "error_message": null
}

Retrieve a Single Segment

Get all details of a single segment.

URL

GET /ga/api/v2/segments/:id

Request Parameters

id
integer

The id of the segment.

Response

segmentation_criteria
hash

id integer	The `id` of the segment.
mailing_list_id integer	The `id` of the mailing list that this segment belongs to.
name string	The name of the segment.
description string	A text description of this segment.
clause array of hashes	The Segment Definition of the segment.

Example

GET /ga/api/v2/mailing_lists/42/segments/25

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "id": 25,
    "mailing_list_id": 42,
    "name": "In Other List",
    "description": "All of the following criteria ... (Subscriber is active in the mailing list \"Other Mailing List Name\")",
    "clause": [
      {
        "type": "in_mailing_list",
        "operator": "is active in",
        "mailing_list_id": 43,
        "mailing_list": {
          "id": 43,
          "name": "Other Mailing List Name"
        }
      }
    ]
  },
  "error_code": null,
  "error_message": null
}

Update a Segment

Update an existing segment using the Segment Definition.

URL

PUT /ga/api/v2/segments/:id

Request Parameters

id
integer

The id of the segment.

Request Payload

segmentation_criteria
array of hashes

name string / required	The user-specified descriptive name for this segment.
clause array of hashes / required	The Segment Definition of the segment.

Response

segmentation_criteria
hash

id integer	The `id` of the segment.
mailing_list_id integer	The `id` of the mailing list that this segment belongs to.
name string	The name of the segment.
description string	A text description of this segment.
clause array of hashes	The Segment Definition of the segment.

Example

PUT /ga/api/v2/mailing_lists/48/segments/29

{
  "segmentation_criteria": {
    "name": "Renamed segment",
    "clause": [
      {
        "type": "in_mailing_list",
        "operator": "is in",
        "mailing_list_id": 49
      }
    ]
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "id": 29,
    "mailing_list_id": 48,
    "name": "Renamed segment",
    "description": "All of the following criteria ... (Subscriber is in the mailing list \"Other Mailing List Name\")",
    "clause": [
      {
        "type": "in_mailing_list",
        "operator": "is in",
        "mailing_list_id": 49,
        "mailing_list": {
          "id": 49,
          "name": "Other Mailing List Name"
        }
      }
    ]
  },
  "error_code": null,
  "error_message": null
}

Delete a Segment

Delete a segment that is no longer in use.

If the segment is still being used by an unfinished campaign or autoresponder, a validation_failed error will be returned.

URL

DELETE /ga/api/v2/segments/:id

Request Parameters

id
integer

The id of the segment.

Response

An empty successful response to this request indicates that the segment was successfully deleted.

Example

DELETE /ga/api/v2/mailing_lists/55/segments/33

HTTP/1.1 200 OK

{
  "success": true,
  "data": null,
  "error_code": null,
  "error_message": null
}