API reference

Segments

Create and manage EmailMarketer.io segments through the API, and write the rules that segments, searches and bulk actions use.

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.