curl --request POST \
--url https://cloudapi.mailercloud.com/v1/segments \
--header 'Authorization: <api-key>' \
--header 'Content-Type: <content-type>' \
--data '
{
"name": "Active gmail subscribers",
"match": "all",
"lists": [
"Newsletter Subscribers"
],
"rules": [
{
"filter_type": "contact_details",
"field": "email_status",
"operator": "equal_to",
"value": "valid"
},
{
"filter_type": "contact_details",
"field": "email_domain",
"operator": "contains",
"value": "gmail"
}
]
}
'{
"id": "EKZwS"
}{
"errors": [
{
"field": "rules[0].field",
"message": "Unknown contact_details field 'foo'"
},
{
"field": "rules[1].value",
"message": "between requires { from, to }"
}
]
}{
"errors": [
{
"field": "",
"message": "Authorization failed"
}
]
}{
"errors": [
{
"field": "",
"message": "Plan does not include segmentation"
}
]
}{
"message": "Internal server error"
}Create Segment
API to create a segment in a single request. name, match and rules are required. lists is optional - if omitted, the segment evaluates against all contacts.
A segment is a dynamic contact filter built from a list of rules. Each rule belongs to one of 4 filter_types: contact_details (built-in contact fields), contact_property (custom properties), tag (contact tags), or activity (campaign / automation / engagement events). The match field controls whether ALL rules must match (all) or ANY rule is enough (any).
curl --request POST \
--url https://cloudapi.mailercloud.com/v1/segments \
--header 'Authorization: <api-key>' \
--header 'Content-Type: <content-type>' \
--data '
{
"name": "Active gmail subscribers",
"match": "all",
"lists": [
"Newsletter Subscribers"
],
"rules": [
{
"filter_type": "contact_details",
"field": "email_status",
"operator": "equal_to",
"value": "valid"
},
{
"filter_type": "contact_details",
"field": "email_domain",
"operator": "contains",
"value": "gmail"
}
]
}
'{
"id": "EKZwS"
}{
"errors": [
{
"field": "rules[0].field",
"message": "Unknown contact_details field 'foo'"
},
{
"field": "rules[1].value",
"message": "between requires { from, to }"
}
]
}{
"errors": [
{
"field": "",
"message": "Authorization failed"
}
]
}{
"errors": [
{
"field": "",
"message": "Plan does not include segmentation"
}
]
}{
"message": "Internal server error"
}Authorizations
Your Mailercloud API key (plain text, no Bearer prefix). Create keys in Settings → API.
Headers
Request body type
Body
Segment display name. Must be unique within the account.
Minimum: 1 Maximum: 100
1 - 100How rules combine.
all: every rule must match (AND) any: at least one rule must match (OR)
Supported values: all, any
all, any Filter rules. At least one rule is required.
1Show child attributes
Show child attributes
Optional. Restrict the segment to contacts in these lists. Provide list names (cid-scoped). Maximum 150 lists.
150Response
Created
The response is of type object.