A segment is a saved set of rules on one list. Campaigns and journeys can target it. All commands take APIKey and are sent to POST https://app.emailmarketer.io/api.php with Command, or to the /api/v1/ path shown.
segment.create
| Parameter | Type | Required | Description |
|---|---|---|---|
SubscriberListID |
int | Yes | |
SegmentName |
string | Yes | |
SegmentOperator |
string | Yes | and or or. How the top-level groups combine. See Rules |
RulesJSON |
string | No | The rules, as a JSON string, not an object |
Randomness |
bool | No | Pick a random sample of the matching subscribers |
RandomnessAudienceSize |
int | No | Sample size when Randomness is on |
curl https://app.emailmarketer.io/api.php \
-d Command=segment.create \
-d APIKey="$EM_API_KEY" \
-d SubscriberListID=123 \
-d SegmentName="Acme contacts" \
-d SegmentOperator=and \
--data-urlencode RulesJSON='[[{"type":"fields","field_id":"EmailAddress","operator":"ends with","value":"@acme.com"}]]'
{ "Success": true, "ErrorCode": 0, "ErrorText": "", "SegmentID": 456 }
| Code | Meaning |
|---|---|
| 1 | Missing list ID |
| 2 | Missing name |
| 3 | Missing operator |
| 4 | List not found |
| 5 | A rule field or operator is not allowed |
| 12 | Invalid RulesJSON (HTTP 422). It must be a JSON string holding a list, at most 3 levels deep |
segment.update
Requires SegmentID and SegmentName. Optional: SubscriberListID (moves the segment to another of your lists), SegmentOperator, RulesJSON, Randomness, RandomnessAudienceSize.
Errors: 1 missing ID, 2 missing name, 4 invalid segment ID, 5 invalid operator, 6 invalid list ID, 7 a rule field or operator is not allowed, 12 invalid RulesJSON.
curl https://app.emailmarketer.io/api.php \
-d Command=segment.update \
-d APIKey="$EM_API_KEY" \
-d SegmentID=456 \
-d SegmentName="Acme customers"
segments.get
GET /api/v1/segments.get. Requires SubscriberListID.
| Parameter | Description |
|---|---|
SegmentID |
Return one segment |
IncludeTotals |
Include subscriber counts. Default true |
ComputeMissingCount |
Count a segment that was never counted. Needs SegmentID |
OrderField |
SegmentName (default), SegmentID, SegmentOperator, SubscriberCount or SubscriberCountLastCalculatedOn |
OrderType |
ASC or DESC (default) |
curl -G https://app.emailmarketer.io/api/v1/segments.get \
-d APIKey="$EM_API_KEY" \
-d SubscriberListID=123 \
-d SegmentID=456
{ "Success": true, "ErrorCode": 0, "TotalSegmentCount": 5, "Segments": [{ "SegmentID": 456, "SegmentName": "Active buyers", "SegmentOperator": "and", "SubscriberCount": 1250, "SegmentRulesJson": "[...]" }] }
Counts are refreshed in the background. SubscriberCountIsStale and SubscriberCountLastCalculatedOn tell you how fresh a count is. Error 1: missing list ID.
segments.copy, segments.delete
| Command | Required | Errors |
|---|---|---|
segments.copy |
SourceListID, TargetListID |
1 missing source, 2 missing target, 4 invalid source or target |
segments.delete |
Segments (comma-separated IDs) |
1 missing IDs, 2 invalid IDs, nothing deleted |
Examples:
# segments.copy
curl https://app.emailmarketer.io/api.php \
-d Command=segments.copy \
-d APIKey="$EM_API_KEY" \
-d SourceListID=123 \
-d TargetListID=124
# segments.delete
curl https://app.emailmarketer.io/api.php \
-d Command=segments.delete \
-d APIKey="$EM_API_KEY" \
-d Segments=456,457
segments.rulevocabulary.get
GET /api/v1/segments.rulevocabulary.get. Returns the fields and operators the rules accept: DefaultFields, RuleOperators, ActivityFields, PhysicalFields and AllowedOperators. Call it before you build rules in code.
curl -G https://app.emailmarketer.io/api/v1/segments.rulevocabulary.get \
-d APIKey="$EM_API_KEY"
Rules
Rules are used by segments, subscribers.search, subscribers.export.post, bulk unsubscribe and delete, tagging, and journey enrolment. They are an array of groups. Each group is an array of rule objects.
[
[
{ "type": "fields", "field_id": "EmailAddress", "operator": "ends with", "value": "@acme.com" },
{ "type": "tags", "operator": "has this tag", "value": "12" }
],
[
{ "type": "campaign-events", "operator": "opened", "value": "" }
]
]
How groups combine
SegmentOperator (or Operator / RulesOperator on other commands) sets the logic:
| Operator | Between groups | Inside a group |
|---|---|---|
or |
OR | AND |
and |
AND | OR |
With or, the example above means: (address ends with @acme.com AND has tag 12) OR opened any campaign. Nesting is limited to 3 levels.
Rule types
type |
Operators | Value |
|---|---|---|
fields |
is, is not, contains, does not contain, begins with, ends with, less than, greater than (or equal), is set, is not set |
field_id is a custom field ID or EmailAddress |
tags |
has this tag, does not have this tag, has any of these tags, has all of these tags, has no tags |
Comma-separated tag IDs |
segments |
belongs to, does not belong to |
A segment ID |
journeys |
in journey, completed journey, not in journey, and opened, clicked, unsubscribed, complained or bounced in a journey, with negations |
A journey ID or a step ID |
suppressions |
exist, not exist |
none |
campaign-events |
opened, clicked, unsubscribed, complained, bounced, delivered, queued-recipients, failed, each with a not form |
A campaign ID, an array of IDs, or empty for any campaign |
website-events |
happened, did not happen, in the last X days, equals, contains, regex, greater or less than, set | event (pageView, identify, conversion or a custom event), event_parameter, value |
campaign-events rules can also take a time filter and a count:
{
"type": "campaign-events", "operator": "opened", "value": "",
"time_filter": { "type": "in_last_x_days", "value": 30 },
"aggregation": { "operator": "at_least", "count": 2 }
}
| Key | Values |
|---|---|
time_filter.type |
in_last_x_days, not_in_last_x_days (value: days), between, not_between (value: { "start", "end" }), after, before (value: a date) |
aggregation.operator |
at_least, at_most, exactly, with aggregation.count |
Aggregation is ignored for delivered, queued-recipients and failed.
Use segments.rulevocabulary.get for the exact operator strings your account accepts. To see the JSON for a complex segment, build it in the app and read it back with segments.get.