Segment API

Segment API

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
}