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",
  "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).

POST

segments

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",
  "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

Authorization

string

header

required

Your Mailercloud API key (plain text, no Bearer prefix). Create keys in Settings → API.

Headers

Content-Type

string

default:application/json

required

Request body type

Body

application/json

name

string

required

Segment display name. Must be unique within the account.

Minimum: 1 Maximum: 100

Required string length: 1 - 100

match

enum<string>

required

How rules combine.

all: every rule must match (AND) any: at least one rule must match (OR)

Supported values: all, any

Available options:

all,

any

rules

object[]

required

Filter rules. At least one rule is required.

Minimum array length: 1

Show child attributes

lists

string[]

Optional. Restrict the segment to contacts in these lists. Provide list names (cid-scoped). Maximum 150 lists.

Maximum array length: 150

Response

Created

The response is of type object.

List Segment Update a Segment

⌘I

Campaigns

Custom Properties

Contacts

Lists

Segments

Senders

Account

Webforms

Tags

Webhooks

Templates

Automations

Inbox Tracker

Create Segment

Authorizations

Headers

Body

Response