curl --request PUT \
  --url https://cloudapi.mailercloud.com/v1/segments/{id} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "name": "Active gmail subscribers - high rating",
  "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"
    },
    {
      "filter_type": "contact_details",
      "field": "contact_rating",
      "operator": "between",
      "value": {
        "from": 4,
        "to": 5
      }
    }
  ]
}
'

{
  "message": "Segment updated"
}

{
  "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"
    }
  ]
}

{
  "errors": [
    {
      "field": "id",
      "message": "Record not found with the given Id"
    }
  ]
}

Update a Segment

Update an existing segment by id. The full segment definition is replaced - this is NOT a partial update. Send the complete name, match, rules (and optional lists) on every call.

On success, the segment’s active_count is recomputed asynchronously. GET /v1/segments/{id} will return count_status: pending until the recount finishes (seconds to minutes), then ready.

Field vocabulary, operator families, and value shapes match the create endpoint - see POST /v1/segments for the full reference.

PUT

segments

{id}

curl --request PUT \
  --url https://cloudapi.mailercloud.com/v1/segments/{id} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "name": "Active gmail subscribers - high rating",
  "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"
    },
    {
      "filter_type": "contact_details",
      "field": "contact_rating",
      "operator": "between",
      "value": {
        "from": 4,
        "to": 5
      }
    }
  ]
}
'

{
  "message": "Segment updated"
}

{
  "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"
    }
  ]
}

{
  "errors": [
    {
      "field": "id",
      "message": "Record not found with the given Id"
    }
  ]
}

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

Path Parameters

string

required

Segment ID to update.

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. The full rule set replaces the existing rules - to keep a rule, include it in this array.

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. Pass an empty array to clear the list restriction.

Maximum array length: 150

Response

message

string

Create Segment List Senders

⌘I

Campaigns

Custom Properties

Contacts

Lists

Segments

Senders

Account

Webforms

Tags

Webhooks

Templates

Automations

Inbox Tracker

Update a Segment

Authorizations

Headers

Path Parameters

Body

Response