Segments

A segment is a filter saved on a list. Build it in the interface (Segments) or here, in JSON.

Create a segment

“VIP customers, or those who opened the back-to-school campaign, and active in the last 60 days”:

curl -X POST https://lekalao.example.com/api/v1/lists/$LIST/segments \
  -H "Authorization: Bearer $LEKALAO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Active VIPs",
    "conditions": {
      "operator": "and",
      "rules": [
        {
          "operator": "or",
          "rules": [
            { "type": "tags", "operator": "has_any", "value": ["vip"] },
            { "type": "campaign", "operator": "opened", "value": "0c9e3f5a-6b1d-4d2e-8a7f-1e2d3c4b5a69" }
          ]
        },
        { "type": "engagement", "operator": "active_within_days", "value": 60 }
      ]
    }
  }'

The 201 answer carries the segment and subscribers_count, how many people it names at that moment. Members are worked out again at every send: a segment is never frozen.

The shape

A group: { "operator": "and" | "or", "rules": [ … ] }.
A rule: { "type", "operator", "value", "key" }.
A group may hold rules and groups, two levels deep at most.
50 rules in all, at most.

Only subscribers of the list whose status is subscribed are counted.

The rules

Fields of the record

type: email, first_name, last_name.

`operator`	`value`
`equals`, `not_equals`	Text. Case is ignored.
`contains`, `not_contains`, `starts_with`, `ends_with`	Text.
`is_empty`, `is_not_empty`	None.

{ "type": "email", "operator": "ends_with", "value": "@mybakery.example" }

`operator`	`value`
`has_any`	At least one of these tags.
`has_all`	All of these tags.
`has_none`	None of these tags.

Language

type: language. operator: equals or not_equals. value: a code such as fr or pt-BR.

Attributes

type: attribute, with key the name of the attribute (letters, digits, _, ., -).

`operator`	`value`
`equals`, `not_equals`, `contains`	Text.
`greater_than`, `less_than`	A number.
`date_before`, `date_after`	A date, `YYYY-MM-DD`.
`is_set`, `is_not_set`	None.

{
    "type": "attribute",
    "key": "points",
    "operator": "greater_than",
    "value": 100
}

Subscription date

type: subscribed_at.

`operator`	`value`
`before`, `after`	A date, `YYYY-MM-DD`.
`within_last_days`, `more_than_days_ago`	A number of days.

Activity

`type`	`operator`	`value`
`campaign`	`received`, `not_received`, `opened`, `not_opened`, `clicked`, `not_clicked`	The campaign’s `id`.
`automation_mail`	the same ones	The automation e-mail’s `id`.
`link`	`clicked`, `not_clicked`	The link’s `id`.
`engagement`	`active_within_days` (opened or clicked), `inactive_within_days` (did nothing)	A number of days.

Other lists

type: list. operator: subscribed_to or not_subscribed_to. value: the id of another list of the team.

{ "type": "list", "operator": "not_subscribed_to", "value": "3e7d…" }

Read, change, delete

Call	Effect
`GET /lists/{id}/segments`	The segments of the list, without counts.
`GET /segments/{id}`	One segment, with `subscribers_count`.
`PUT /segments/{id}`	Changes `name` and/or `conditions`. The conditions you send replace the old ones.
`DELETE /segments/{id}`	Deletes the segment. Campaigns already sent keep their statistics.

In the answers, tags come back as names and the other references as ids, just as you sent them.

Errors

An invalid rule answers 422 with the exact path:

{
    "message": "There is no tag \"vipp\" on this list.",
    "errors": {
        "conditions.rules.0.rules.0.value": [
            "There is no tag \"vipp\" on this list."
        ]
    }
}

The API

Recipes

Integrations

Create a segment

The shape

The rules

Fields of the record

Tags

Language

Attributes

Subscription date

Activity

Other lists

Read, change, delete

Errors

​Create a segment

​The shape

​The rules

​Fields of the record

​Tags

​Language

​Attributes

​Subscription date

​Activity

​Other lists

​Read, change, delete

​Errors

Create a segment

The shape

The rules

Fields of the record

Tags

Language

Attributes

Subscription date

Activity

Other lists

Read, change, delete

Errors