This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Segments

Segments endpoints of the MailWizz API.

List segments endpoint

// CREATE THE ENDPOINT
$endpoint = new EmsApi\Endpoint\ListSegments();

# CREATE THE ENDPOINT
endpoint = ListSegments.new

from mailwizz.endpoint.list_segments import ListSegments

"""
CREATE THE ENDPOINT
"""
endpoint = ListSegments()

Get all list segments

// GET ALL ITEMS
$response = $endpoint->getSegments('LIST-UNIQUE-ID');

// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';

# GET ALL SEGMENTS OF A LIST
response = endpoint.get_segments('LIST_UID')

# DISPLAY RESPONSE
puts response.body

"""
GET ALL SEGMENTS OF A LIST
"""
response = endpoint.get_segments(list_uid='LIST_UID')

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "count": "1",
    "total_pages": 1,
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "records": [
      {
        "segment_uid": "yx536w32xt946",
        "name": "test",
        "subscribers_count": 289
      }
    ]
  }
}

This endpoint retrieves all the segments of a list.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/segments

URL Segments

Segment	Required	Description
LIST-UNIQUE-ID	yes	The list unique identifier

Query Parameters

Parameter	Default	Description
page	1	Current page to retrieve.
per_page	10	Items per page to retrieve.

Get one list segment

// GET ONE ITEM
$response = $endpoint->getSegment('SEGMENT-UNIQUE-ID');

// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "record": {
      "segment_uid": "sx795qzttl9bb",
      "segment_id": "11",
      "name": "my segment with cond updated",
      "operator_match": "any",
      "date_added": "10/23/23, 2:36 PM",
      "subscribers_count": 0,
      "conditions": [
        {
          "field_id": "96",
          "operator_id": "3",
          "value": "keyword"
        }
      ],
      "campaign_conditions": []
    }
  }
}

This endpoint retrieves the list segment with the given SEGMENT-UNIQUE-ID.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/segments/SEGMENT-UNIQUE-ID

URL Segments

Segment	Required	Description
LIST-UNIQUE-ID	yes	List unique id to retrieve segment for.
SEGMENT-UNIQUE-ID	yes	Segment unique id to retrieve

Get all subscribers

// GET ALL SUBSCRIBERS OF A LIST SEGMENT
$response = $endpoint->getSubscribers('LIST-UNIQUE-ID', 'SEGMENT-UNIQUE-ID', $pageNumber = 1, $perPage = 10);

// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';

# GET ALL SUBSCRIBERS OF A LIST SEGMENT
response = endpoint.get_subscribers(list_uid = 'LIST-UNIQUE-ID', segment_uid = 'SEGMENT-UNIQUE-ID', page = 1, per_page = 10)

# DISPLAY RESPONSE
puts response.body

"""
GET ALL SUBSCRIBERS OF A LIST SEGMENT
"""
response = endpoint.get_subscribers(list_uid='LIST-UNIQUE-ID', segment_uid='SEGMENT-UNIQUE-ID', page=1, per_page=10)

"""
DISPLAY RESPONSE
"""
print(response.content)

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "count": "13",
    "total_pages": 2,
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "records": [
      {
        "subscriber_uid": "ll381bxshm01e",
        "EMAIL": "dmacmeartyd@jugem.jp",
        "FNAME": "",
        "LNAME": "",
        "status": "unsubscribed",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:18"
      },
      {
        "subscriber_uid": "tl269bw0ol42e",
        "EMAIL": "gsteblesc@hp.com",
        "FNAME": "",
        "LNAME": "",
        "status": "unsubscribed",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:18"
      },
      {
        "subscriber_uid": "gs870cmwgve71",
        "EMAIL": "lruterb@prlog.org",
        "FNAME": "",
        "LNAME": "",
        "status": "unsubscribed",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:17"
      },
      {
        "subscriber_uid": "nz753vyrm0f86",
        "EMAIL": "kwheildona@tmall.com",
        "FNAME": "",
        "LNAME": "",
        "status": "confirmed",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:17"
      },
      {
        "subscriber_uid": "sf449a4k7n193",
        "EMAIL": "dshorrock9@hp.com",
        "FNAME": "",
        "LNAME": "",
        "status": "confirmed",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:16"
      },
      {
        "subscriber_uid": "op6219zx1s149",
        "EMAIL": "slorenz8@drupal.org",
        "FNAME": "",
        "LNAME": "",
        "status": "confirmed",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:16"
      },
      {
        "subscriber_uid": "zz449poqsr2af",
        "EMAIL": "mhanlon7@wikispaces.com",
        "FNAME": "",
        "LNAME": "",
        "status": "confirmed",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:16"
      },
      {
        "subscriber_uid": "jl349100yda86",
        "EMAIL": "elacroutz6@youku.com",
        "FNAME": "",
        "LNAME": "",
        "status": "confirmed",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:15"
      },
      {
        "subscriber_uid": "kw647a5n8l516",
        "EMAIL": "mstephenson5@trellian.com",
        "FNAME": "",
        "LNAME": "",
        "status": "confirmed",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:15"
      },
      {
        "subscriber_uid": "vo155s4b0d0ad",
        "EMAIL": "ldefew4@dailymail.co.uk",
        "FNAME": "",
        "LNAME": "",
        "status": "confirmed",
        "source": "import",
        "ip_address": "",
        "date_added": "2021-02-20 17:26:14"
      }
    ]
  }
}

This endpoint retrieves all the subscribers of a list segment.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/segments/SEGMEMT-UNIQUE-ID/subscribers

URL Segments

Segment	Required	Description
LIST-UNIQUE-ID	yes	The list unique identifier for which we retrieve the subscribers
SEGMENT-UNIQUE-ID	yes	Segment unique identifier

Query Parameters

Parameter	Default	Description
page	1	Current page to retrieve.
per_page	10	Items per page to retrieve.

Create a list segment

// create a new list segment
$response = $endpoint->create('LIST-UNIQUE-ID', [
    // required
    'name'           => 'My list segment created from the API', // required
    'operator_match' => 'any', // required (any/all)
    // optional
    'conditions' => [
        [
            'field_id'    => '96', // required . 
            'operator_id' => '3', // required .  See the API-URL/lists/segments/condition-operators endpoint
            'value'       => 'domain.com', // required
        ],
        [
            'field_id'    => '95', // required . 
            'operator_id' => '4', // required .  See the API-URL/lists/segments/condition-operators endpoint
            'value'       => 'keyword', // required
        ]
    ],
    'campaign_conditions' => [
        [
            'action'                   => 'click', // required (click/open)
            'campaign_id'              => '100', // required
            'time_comparison_operator' => 'lte', // required (lte/lt/gte/gt/eq)
            'time_value'               => '3', // required
            'time_unit'                => 'day' // required (day/month/year)
        ],
        [
            'action'                   => 'open', // required (click/open)
            'campaign_id'              => '99', // required
            'time_comparison_operator' => 'gte', // required (lte/lt/gte/gt/eq)
            'time_value'               => '3', // required
            'time_unit'                => 'month' // required (day/month/year)
        ]
    ],
]);

// and get the response
echo '<pre>';
print_r($response->body);
echo '</pre>';

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "record": {
      "segment_uid": "sx795qzttl9bb",
      "segment_id": "11",
      "name": "my segment with cond updated",
      "operator_match": "any",
      "date_added": "10/23/23, 2:36 PM",
      "subscribers_count": 0,
      "conditions": [
        {
          "field_id": "96",
          "operator_id": "3",
          "value": "keyword"
        }
      ],
      "campaign_conditions": []
    }
  }
}

This endpoint creates a list segment.

The data param can contain following indexed arrays:

-> conditions - optional

-> campaign_conditions - optional

HTTP Request

POST API-URL/lists/LIST_UID/segments

POST Parameters

Parameter	Type	Required	Description
data	array	yes	Array with the list segment details. The following indexed arrays are accepted: conditions, campaign_conditions,

General block - required

Parameter	Type	Required	Description
name	string	yes	List segment name
operator_match	string	yes	Operator to match all the conditions: any/all

Conditions block - optional

Parameter	Type	Required	Description
field_id	string	yes	List custom field id. Can be retrieved using the list fields endpoint
operator_id	string	yes	Operator id. See the API-URL/lists/segments/operators endpoint
value	string	yes	Value to compare with

Campaign conditions block - optional

Parameter	Type	Required	Description
action	string	yes	Campaign action: click/open
campaign_id	integer	yes	Campaign id.
time_comparison_operator	string	yes	Time comparison operator: (lte/lt/gte/gt/eq)
time_value	integer	yes	Time value
time_unit	string	yes	Time unit day/month/year

Update a list segment

// update list segment
// Only the conditions present here will be kept. All other existing conditions will be removed
$response = $endpoint->update('LIST-UNIQUE-ID', 'SEGMENT-UNIQUE-ID', [
    // required
    'name'           => 'My list segment created from the API updated', // required
    'operator_match' => 'any', // required (any/all)
    // optional
    'conditions' => [
        [
            'field_id'    => '96', // required . 
            'operator_id' => '3', // required .  See the API-URL/lists/segments/condition-operators endpoint
            'value'       => 'domain.com', // required
        ],
        [
            'field_id'    => '95', // required . 
            'operator_id' => '4', // required .  See the API-URL/lists/segments/condition-operators endpoint
            'value'       => 'keyword', // required
        ]
    ],
    'campaign_conditions' => [
        [
            'action'                   => 'click', // required (click/open)
            'campaign_id'              => '100', // required
            'time_comparison_operator' => 'lte', // required (lte/lt/gte/gt/eq)
            'time_value'               => '3', // required
            'time_unit'                => 'day' // required (day/month/year)
        ],
        [
            'action'                   => 'open', // required (click/open)
            'campaign_id'              => '99', // required
            'time_comparison_operator' => 'gte', // required (lte/lt/gte/gt/eq)
            'time_value'               => '3', // required
            'time_unit'                => 'month' // required (day/month/year)
        ]
    ],
]);

// and get the response
echo '<pre>';
print_r($response->body);
echo '</pre>';

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "record": {
      "segment_uid": "sx795qzttl9bb",
      "segment_id": "11",
      "name": "my segment with cond updated",
      "operator_match": "any",
      "date_added": "10/23/23, 2:36 PM",
      "subscribers_count": 0,
      "conditions": [
        {
          "field_id": "96",
          "operator_id": "3",
          "value": "keyword"
        }
      ],
      "campaign_conditions": []
    }
  }
}

This endpoint updates a list segment.

HTTP Request

PUT API-URL/lists/LIST-UNIQUE-ID/segments/SEGMENT-UNIQUE-ID

URL Segment

Segment	Type	Required	Description
LIST-UNIQUE-ID	string	yes	List unique identifier
SEGMENT-UNIQUE-ID	string	yes	List segment unique identifier

PUT Parameters

Parameter	Type	Required	Description
data	array	yes	Array with the list segment details. The following indexed arrays are accepted: conditions, campaign_conditions. See the create section for details

General block - required

Parameter	Type	Required	Description
name	string	yes	List segment name
operator_match	string	yes	Operator to match all the conditions: any/all

Conditions block - optional

Parameter	Type	Required	Description
field_id	string	yes	List custom field id. Can be retrieved using the list fields endpoint
operator_id	string	yes	Operator id. See the API-URL/lists/segments/operators endpoint
value	string	yes	Value to compare with

Campaign conditions block - optional

Parameter	Type	Required	Description
action	string	yes	Campaign action: click/open
campaign_id	integer	yes	Campaign id.
time_comparison_operator	string	yes	Time comparison operator: (lte/lt/gte/gt/eq)
time_value	integer	yes	Time value
time_unit	string	yes	Time unit day/month/year

Delete a list segment

// Delete SEGMENT
$response = $endpoint->delete('LIST-UNIQUE-ID', 'SEGMENT-UNIQUE-ID');

// DISPLAY RESPONSE
echo '<hr /><pre>';
print_r($response->body);
echo '</pre>';

The above command returns an object structured like this JSON:

{
  "status":"success"
}

This endpoint will delete the list segment with the given SEGMENT-UNIQUE-ID for the LIST-UNIQUE-ID.

HTTP Request

DELETE API-URL/lists/LIST-UNIQUE-ID/segments/SEGMENT-UNIQUE-ID

URL Segments

Segment	Required	Description
LIST-UNIQUE-ID	yes	List unique id to delete.
SEGMENT-UNIQUE-ID	yes	List segment unique id to delete

Get all list segment condition operators

// GET ALL ITEMS
$response = $endpoint->getConditionOperators();

// DISPLAY RESPONSE
echo '<pre>';
print_r($response->body);
echo '</pre>';

The above command returns an object structured like this JSON:

{
  "status": "success",
  "data": {
    "count": "10",
    "records": [
      {
        "operator_id": "1",
        "name": "is",
        "slug": "is"
      },
      {
        "operator_id": "2",
        "name": "is not",
        "slug": "is-not"
      },
      {
        "operator_id": "3",
        "name": "contains",
        "slug": "contains"
      },
      {
        "operator_id": "4",
        "name": "not contains",
        "slug": "not-contains"
      },
      {
        "operator_id": "5",
        "name": "starts with",
        "slug": "starts"
      },
      {
        "operator_id": "6",
        "name": "ends with",
        "slug": "ends"
      },
      {
        "operator_id": "7",
        "name": "is greater than",
        "slug": "greater"
      },
      {
        "operator_id": "8",
        "name": "is less than",
        "slug": "less"
      },
      {
        "operator_id": "9",
        "name": "not starts with",
        "slug": "not-starts"
      },
      {
        "operator_id": "10",
        "name": "not ends with",
        "slug": "not-ends"
      }
    ]
  }
}

This endpoint retrieves all the list segment condition operators.

HTTP Request

GET API-URL/lists/segments/condition-operators