> ## Documentation Index > Fetch the complete documentation index at: https://apidoc.mailercloud.com/llms.txt > Use this file to discover all available pages before exploring further. # 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`). ## OpenAPI ````yaml /openapi-v1.json post /segments openapi: 3.1.0 info: title: Mailercloud Marketing API version: 1.0.0 description: >- Campaigns, contacts, lists, segments, automations, and webhooks for the Mailercloud Marketing Platform. servers: - url: https://cloudapi.mailercloud.com/v1 security: - apiKey: [] tags: - name: Campaigns - name: Contacts - name: Lists - name: Tags - name: Segments - name: Custom Properties - name: Senders - name: Templates - name: Automations - name: Webhooks - name: Webforms - name: Inbox Tracker - name: Account paths: /segments: post: tags: - Segments summary: Create Segment description: >- 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`). operationId: create-segment parameters: - name: Content-Type in: header required: true description: Request body type schema: type: string default: application/json requestBody: required: true content: application/json: schema: type: object required: - name - match - rules properties: name: type: string minLength: 1 maxLength: 100 description: |- Segment display name. Must be unique within the account. Minimum: 1 Maximum: 100 match: type: string enum: - all - any description: |- How rules combine. all: every rule must match (AND) any: at least one rule must match (OR) Supported values: all, any lists: type: array items: type: string maxItems: 150 description: >- Optional. Restrict the segment to contacts in these lists. Provide list names (cid-scoped). Maximum 150 lists. rules: type: array minItems: 1 description: Filter rules. At least one rule is required. items: type: object required: - filter_type properties: filter_type: type: string enum: - contact_details - contact_property - tag - activity description: >- Type of filter rule. contact_details: built-in contact fields (email_status, contact_rating, email_domain, etc.) contact_property: custom field defined in your account tag: contact tags (encrypted tag IDs) activity: campaign / automation / engagement events Supported values: contact_details, contact_property, tag, activity field: type: string description: >- Field name. Required for contact_details and contact_property. For contact_details, allowed values: email_status, verification_status, contact_rating, email_domain, mailbox_provider, signup_source For contact_property, use the property mapping_name (e.g. custom_1, country, salary). Must match ^[A-Za-z0-9_]+$ Note: verification_status is a write-side alias and collapses to email_status in storage; GET round-trip always returns field=email_status. property_type: type: string enum: - text - number - date description: >- For contact_property only. Picks the operator family. Defaults from the custom field's type in gyh_custom_fields if omitted. operator: type: string description: >- Comparison operator. Allowed values depend on the filter_type / field / property_type. Text operators: equal_to (also accepts is, equals), not_equal_to (also is_not), exact_match, contains, does_not_contain, starts_with, does_not_start_with, ends_with, does_not_end_with, any_of, is_known, is_unknown Number operators (per PR #142 operator-canonical fix): equal_to (canonical, also accepts equal_to_number, is_number), not_equal_to (canonical, also accepts not_equal_to_number), less_than, less_than_number (verbatim - kept distinct because of its SQL > 0 guard), greater_than, between, is_known_number, is_unknown_number Date operators: in_the_last_days (also in_last_days), not_in_the_last_days, date_between, on_a_specific_date, is_after, is_before, date_is_not, date_is_known, date_is_unknown Tag operators: is_tagged, is_not_tagged email_status field: equal_to, not_equal_to, any_of signup_source field: was, was_not value: description: >- Filter value. Type depends on operator. Text/number equality: string or number any_of: array of strings between: { from: number, to: number } date_between: { from: YYYY-MM-DD, to: YYYY-MM-DD } in_the_last_days / not_in_the_last_days: integer 1-365 is_known / is_unknown / is_known_number / is_unknown_number / date_is_known / date_is_unknown / is_empty / is_not_empty: omit value email_status enum: valid, unknown, suppressed, unsubscribed, spam, bounced, external_group_mailbox, spam_trap, external_abusers, external_invalid, spam_complaints, frequent_abusers, external_verified, blacklisted, account_level_bounce signup_source enum: admin_add, import, api, webform filter_by: type: string description: >- Sub-selector for tag and activity rules. For tag filter_type with is_tagged / is_not_tagged: any_of, all_of For activity filter_type: any_of_the_last_five, all_of_the_last_five, any_of_last_seven_day, any_of_last_one_month, any_of_last_three_month, between, in_the_last_days, not_in_the_last_days, count, count_between, order_by_count, before, after, on, for, between_time category: type: string enum: - campaign - automation - webform - list - audience - engagement_status - global_engagers - global_openers - subscriber_opened - subscriber_clicked description: >- Activity category. Required when filter_type=activity. Supported values: campaign, automation, webform, list, audience, engagement_status, global_engagers, global_openers, subscriber_opened, subscriber_clicked activity: type: string description: >- Activity event name. Required for some activity categories (campaign, automation, webform, list, audience). Supported values: opened, not_opened, clicked, not_clicked, sent, not_sent, started, completed, not_started, not_completed, happened, not_happened examples: Example-1---Active-gmail-subscribers: value: 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 Example-2---High-rated-US-contacts-engaged-last-30-days: value: name: Engaged US contacts - last 30 days match: all rules: - filter_type: contact_details field: contact_rating operator: between value: from: 3 to: 5 - filter_type: contact_property field: country property_type: text operator: equal_to value: United States - filter_type: activity category: campaign activity: opened filter_by: in_the_last_days value: 30 Example-3---VIP-tag-OR-signed-up-via-API-in-last-7-days: value: name: VIP or recent API signups match: any rules: - filter_type: tag operator: is_tagged filter_by: any_of value: - enc_t1 - enc_t2 - filter_type: contact_details field: signup_source operator: was value: api - filter_type: activity category: list activity: happened filter_by: in_the_last_days value: 7 responses: '201': description: Created content: application/json: schema: type: object properties: {} examples: Example-1: value: id: EKZwS '400': description: Bad Request - validation, name resolution, or operator-shape failure content: application/json: schema: type: object properties: errors: type: array items: type: object properties: field: type: string message: type: string examples: Example-1: value: errors: - field: rules[0].field message: Unknown contact_details field 'foo' - field: rules[1].value message: between requires { from, to } '401': description: Unauthorized content: application/json: schema: type: object properties: errors: type: array items: type: object properties: field: type: string message: type: string examples: Example-1: value: errors: - field: '' message: Authorization failed '403': description: Forbidden - caller's plan does not include segmentation content: application/json: schema: type: object properties: errors: type: array items: type: object properties: field: type: string message: type: string examples: Example-1: value: errors: - field: '' message: Plan does not include segmentation '500': description: Internal Server Error content: application/json: schema: type: object properties: message: type: string examples: Example-1: value: message: Internal server error components: securitySchemes: apiKey: type: apiKey in: header name: Authorization description: >- Your Mailercloud API key (plain text, no Bearer prefix). Create keys in Settings → API. ````