> This page is for Mailchimp Marketing API. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://mailchimp.com/developer/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://mailchimp.com/developer/_mcp/server. # Add Segment POST https://api.mailchimp.com/3.0/segments Content-Type: application/json Create an advanced segment from a segment definition. The account's plan must include advanced segmentation. If it does not, the API returns a 403 error. Reference: https://mailchimp.com/developer/marketing/api/segments/create-segment ## Authentication - `Authorization` header (bearer token, required) — Authorization using a Mailchimp API key (a.k.a. Bearer token) - `Authorization` header (bearer token, required) — Authorization using OAuth ## Request ### Body (application/json) This endpoint expects an object. - `definition` (SegmentDefinition, required) — A node in a segment definition. A node is a group or a condition. A group contains the `match` property and combines the nodes in its `conditions` array. A condition contains the `field` property and tests one contact attribute. A node cannot contain both `match` and `field`. The root node of a definition is always a group. In a request, the root group must contain `match` and `conditions`. This schema shows the properties of both node types together. Limits: A definition can contain a maximum of 100 conditions, including the conditions in `filters`. A definition can contain a maximum of 2 levels of groups. The root group is level 1. The Mailchimp segment builder uses the same group limit. If a definition is more than a limit, the API returns a 400 error. In this API version, Mailchimp does not change or remove existing fields, but Mailchimp can add new fields. Make sure that your client ignores fields that it does not know. - `list_id` (string, required) — The unique ID of the list that contains the segment. - `name` (string, required) — The name of the segment. ## Response ### 200 - `created_at` (datetime, optional) — The date and time when Mailchimp created the segment, in ISO 8601 format. - `definition` (map from string to any, optional) — The segment definition. Read-only segments do not have a definition, so the response does not include this property for them. It contains the `match` and `conditions` that you sent, the current `schema_version`, and the `contacts` object. In the `contacts` object, each entry selects exactly one subscription status. The request body of Add Segment shows all properties of a definition. - `id` (string, optional) — The unique ID of the segment. Do not parse or change this value. Use it exactly as you received it. - `list_id` (string, optional) — The unique ID of the list that contains the segment. - `read_only` (boolean, optional) — If true, you can read, count, and snapshot the segment, but you cannot update or delete it. Segments that other Mailchimp tools made, for example Google Analytics segments, are read-only. A read-only segment does not have a definition. - `name` (string, optional) — The name of the segment. ## Types ### SegmentDefinition A node in a segment definition. A node is a group or a condition. A group contains the `match` property and combines the nodes in its `conditions` array. A condition contains the `field` property and tests one contact attribute. A node cannot contain both `match` and `field`. The root node of a definition is always a group. In a request, the root group must contain `match` and `conditions`. This schema shows the properties of both node types together. Limits: A definition can contain a maximum of 100 conditions, including the conditions in `filters`. A definition can contain a maximum of 2 levels of groups. The root group is level 1. The Mailchimp segment builder uses the same group limit. If a definition is more than a limit, the API returns a 400 error. In this API version, Mailchimp does not change or remove existing fields, but Mailchimp can add new fields. Make sure that your client ignores fields that it does not know. - `conditions` (list of SegmentDefinitionConditionsItems, required) — Only for groups. The nodes in the group. Each item is a condition or a group, and one array can contain both. Each item has the same properties as this node. A definition can contain a maximum of 100 conditions, including the conditions in `filters`. A definition can contain a maximum of 2 levels of groups. The root group is level 1. - `match` (enum, required) — Only for groups. How the group combines its nodes. `all` selects contacts that agree with all nodes. `any` selects contacts that agree with one or more nodes. The `match` property identifies a node as a group. - Allowed values: `all`, `any` - `contacts` (SegmentDefinitionContacts, optional) — The contacts that the segment can include, by channel and subscription status. Use this object only in the root group. If you do not include it, the segment can include all contacts on all channels: email, SMS, and WhatsApp. In a request, one entry can select more than one subscription status. For example, `{"sendable": false}` selects all statuses that cannot receive marketing on that channel. In a response, each entry selects exactly one subscription status. If you send a response object in a request, it selects the same contacts. - `extra` (any, optional) — Only for conditions. More data for some conditions (a string or an array). Its meaning changes with the field. - `field` (string, optional) — Only for conditions. The contact attribute that the condition tests. The `field` property identifies a node as a condition. Each field has its own operators, values, and filters. Contact data: `merge0` (email address), `merge` (merge field by `merge_id`; its operators change with its type), `language`, `gmonkey` (VIP), `rating` (1-5), `timestamp_opt` (subscription date), `info_changed`, `metadata_created` (date the contact was added), `original_signup_source`, `static_segment` (tags, by tag ID), `interests-` (groups; beta), `list_email_status`, `marketing_preference` (beta), `age_gating`, `ipgeo` (predicted location; uses `location`). Messages: `email_campaign_activity` (sent, opened, clicked, bounced; filter by campaign `web_id` and time period), `email_marketing_engagement`, `sms_campaign_activity`, `sms_bounce_reason`, `sms_contact_status`, `sms_timestamp_opt`, `sms_country_code`, `whatsapp_campaign_interaction`, `whatsapp_contact_status`, `whatsapp_timestamp_opt`. E-commerce (connected store): `ecomm` (purchases; filter by date, campaign, store, product, variant, vendor, collection, total, and count), `total_spent`, `spent_avg`, `orders_count`, `ecomm_page_viewed`, `ecomm_product_viewed`, `ecomm_collection_viewed`, `ecomm_search_submitted`, `ecomm_product_added_to_cart`, `ecomm_checkout_started`, `ecomm_review_submitted`, `ecomm_back_in_stock_request`. Predictions and integrations: `predicted_clv`, `likelihood_to_purchase` (0-1000), `time_to_next_purchase`, `ecomm_churn_risk`, `clv_lifetime_value` and `clv_lifecycle` (earlier customer lifetime value fields), `age_range`, `gender`, `lead_ad`, `booking_activity`, `qbo_invoice_activity`, `qbo_sales_receipt_activity`. Events: `contact_event` (events from the Events API; filter by name, time period, and property), `custom_event__` (with `namespace`, `event_name`, and typed `custom_event_property_*` filters). To count how many times an event occurred, use the `number_events` filter. - `filters` (list of SegmentDefinitionFiltersItems, optional) — Only for conditions. Filters that limit what the condition selects, for example the campaign and time period filters of `email_campaign_activity`. A filter can contain more filters. A filter cannot contain a group. Each filter has the same properties as a condition. - `location` (SegmentDefinitionLocation, optional) — The geographic limits of a predicted location (`ipgeo`) condition. - `op` (string, optional) — Only for conditions. The comparison that the condition uses. Each condition and each filter must have an operator. Each field has its own operators, for example `is`, `contains`, `greater`, or `date_within`. On some fields, the operator `any` applies no limit. - `schema_version` (integer, optional) — Reserved for later versions of this format. Use it only in the root group. The API accepts all values. Responses always show the current version, 2. - `value` (any, optional) — Only for conditions. The value that the condition compares with. Its type (string, number, boolean, or array) changes with the field and the operator. For a campaign, use its `web_id` from `/campaigns`. For a tag, use its integer tag ID. Interest groups, marketing permissions, and e-commerce stores use Mailchimp's own ID values (beta). To get one of these IDs, make a segment in Mailchimp. Then read the segment through this API and copy the ID. - `value_op` (enum, optional) — Only for conditions. How the condition combines the items in `value`, for merge field conditions that accept more than one value. `or` selects contacts that agree with one or more items. `and` selects contacts that agree with all items. - Allowed values: `and`, `or` ### SegmentDefinitionConditionsItems ### SegmentDefinitionContacts The contacts that the segment can include, by channel and subscription status. Use this object only in the root group. If you do not include it, the segment can include all contacts on all channels: email, SMS, and WhatsApp. In a request, one entry can select more than one subscription status. For example, `{"sendable": false}` selects all statuses that cannot receive marketing on that channel. In a response, each entry selects exactly one subscription status. If you send a response object in a request, it selects the same contacts. - `email` (SegmentDefinitionContactsEmail, optional) - `sms` (SegmentDefinitionContactsSms, optional) - `whatsapp` (SegmentDefinitionContactsWhatsapp, optional) ### SegmentDefinitionFiltersItems ### SegmentDefinitionLocation The geographic limits of a predicted location (`ipgeo`) condition. - `city` (string, optional) - `country_code` (string, optional) — The two-letter country code. - `lat` (double, optional) - `lng` (double, optional) - `region` (string, optional) ### SegmentDefinitionContactsEmail - `marketing` (list of SegmentDefinitionContactsEmailMarketingItems, optional) — The marketing subscription statuses that the segment includes on this channel. Each entry selects one or more statuses. The segment includes the contacts of all entries. - `transactional` (list of SegmentDefinitionContactsEmailTransactionalItems, optional) — The transactional email statuses that the segment includes. This is an array, the same as `marketing`. Only one entry has an effect. ### SegmentDefinitionContactsSms - `marketing` (list of SegmentDefinitionContactsSmsMarketingItems, optional) — The marketing subscription statuses that the segment includes on this channel. Each entry selects one or more statuses. The segment includes the contacts of all entries. - `transactional` (list of SegmentDefinitionContactsSmsTransactionalItems, optional) — Reserved. Do not use this property. If a request includes it, the API returns a 400 error. ### SegmentDefinitionContactsWhatsapp - `marketing` (list of SegmentDefinitionContactsWhatsappMarketingItems, optional) — The marketing subscription statuses that the segment includes on this channel. Each entry selects one or more statuses. The segment includes the contacts of all entries. - `transactional` (list of SegmentDefinitionContactsWhatsappTransactionalItems, optional) — Reserved. Do not use this property. If a request includes it, the API returns a 400 error. ### SegmentDefinitionContactsEmailMarketingItems - `sendable` (boolean, required) — Shows if the contacts can receive marketing on this channel now. Use it with `consent` and `reason` to select subscription statuses. - `consent` (enum, optional) — Selects a subset of the contacts that cannot receive marketing. `confirmed`, or no value, selects all of these contacts. `denied` selects only the contacts that unsubscribed. `unknown` selects only the contacts that never subscribed. On email, these are the contacts that can receive only transactional email. If `sendable` is true, the only permitted value is `confirmed`. Do not use `consent` with `reason`. If a request breaks one of these rules, the API returns a 400 error. On email, `denied` also selects the contacts that an account admin unsubscribed. - Allowed values: `unknown`, `confirmed`, `denied` - `reason` (enum, optional) — Selects the contacts that Mailchimp removed because of delivery problems (cleaned contacts). Use it only on email, and only when `sendable` is false. Do not use it with `consent`. If a request breaks one of these rules, the API returns a 400 error. - Allowed values: `deliverability` ### SegmentDefinitionContactsEmailTransactionalItems - `sendable` (boolean, required) — If true, the segment includes the contacts that can receive only transactional email. The API accepts false, but false selects no contacts. ### SegmentDefinitionContactsSmsMarketingItems - `sendable` (boolean, required) — Shows if the contacts can receive marketing on this channel now. Use it with `consent` and `reason` to select subscription statuses. - `consent` (enum, optional) — Selects a subset of the contacts that cannot receive marketing. `confirmed`, or no value, selects all of these contacts. `denied` selects only the contacts that unsubscribed. `unknown` selects only the contacts that never subscribed. On email, these are the contacts that can receive only transactional email. If `sendable` is true, the only permitted value is `confirmed`. Do not use `consent` with `reason`. If a request breaks one of these rules, the API returns a 400 error. On email, `denied` also selects the contacts that an account admin unsubscribed. - Allowed values: `unknown`, `confirmed`, `denied` - `reason` (enum, optional) — Selects the contacts that Mailchimp removed because of delivery problems (cleaned contacts). Use it only on email, and only when `sendable` is false. Do not use it with `consent`. If a request breaks one of these rules, the API returns a 400 error. - Allowed values: `deliverability` ### SegmentDefinitionContactsSmsTransactionalItems - `sendable` (boolean, required) — If true, the segment includes the contacts that can receive only transactional email. The API accepts false, but false selects no contacts. ### SegmentDefinitionContactsWhatsappMarketingItems - `sendable` (boolean, required) — Shows if the contacts can receive marketing on this channel now. Use it with `consent` and `reason` to select subscription statuses. - `consent` (enum, optional) — Selects a subset of the contacts that cannot receive marketing. `confirmed`, or no value, selects all of these contacts. `denied` selects only the contacts that unsubscribed. `unknown` selects only the contacts that never subscribed. On email, these are the contacts that can receive only transactional email. If `sendable` is true, the only permitted value is `confirmed`. Do not use `consent` with `reason`. If a request breaks one of these rules, the API returns a 400 error. On email, `denied` also selects the contacts that an account admin unsubscribed. - Allowed values: `unknown`, `confirmed`, `denied` - `reason` (enum, optional) — Selects the contacts that Mailchimp removed because of delivery problems (cleaned contacts). Use it only on email, and only when `sendable` is false. Do not use it with `consent`. If a request breaks one of these rules, the API returns a 400 error. - Allowed values: `deliverability` ### SegmentDefinitionContactsWhatsappTransactionalItems - `sendable` (boolean, required) — If true, the segment includes the contacts that can receive only transactional email. The API accepts false, but false selects no contacts. ## Examples **Request** ```json { "definition": { "conditions": [ { "field": "merge0", "op": "contains", "value": [ "yahoo.com" ] } ], "match": "all", "contacts": { "email": { "marketing": [ { "sendable": true } ] } }, "schema_version": 2 }, "list_id": "a1b2c3d4e5", "name": "Example Segment" } ``` **Response** ```json { "created_at": "2025-01-15T10:30:00+00:00", "definition": {}, "id": "0dbaba26-0003-8000-8000-000000000919", "list_id": "a1b2c3d4e5", "read_only": true, "name": "Example Segment" } ``` **SDK Code** ```python import requests url = "https://api.mailchimp.com/3.0/segments" payload = { "definition": { "conditions": [ { "field": "merge0", "op": "contains", "value": ["yahoo.com"] } ], "match": "all", "contacts": { "email": { "marketing": [{ "sendable": True }] } }, "schema_version": 2 }, "list_id": "a1b2c3d4e5", "name": "Example Segment" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.mailchimp.com/3.0/segments'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"definition":{"conditions":[{"field":"merge0","op":"contains","value":["yahoo.com"]}],"match":"all","contacts":{"email":{"marketing":[{"sendable":true}]}},"schema_version":2},"list_id":"a1b2c3d4e5","name":"Example Segment"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.mailchimp.com/3.0/segments" payload := strings.NewReader("{\n \"definition\": {\n \"conditions\": [\n {\n \"field\": \"merge0\",\n \"op\": \"contains\",\n \"value\": [\n \"yahoo.com\"\n ]\n }\n ],\n \"match\": \"all\",\n \"contacts\": {\n \"email\": {\n \"marketing\": [\n {\n \"sendable\": true\n }\n ]\n }\n },\n \"schema_version\": 2\n },\n \"list_id\": \"a1b2c3d4e5\",\n \"name\": \"Example Segment\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.mailchimp.com/3.0/segments") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"definition\": {\n \"conditions\": [\n {\n \"field\": \"merge0\",\n \"op\": \"contains\",\n \"value\": [\n \"yahoo.com\"\n ]\n }\n ],\n \"match\": \"all\",\n \"contacts\": {\n \"email\": {\n \"marketing\": [\n {\n \"sendable\": true\n }\n ]\n }\n },\n \"schema_version\": 2\n },\n \"list_id\": \"a1b2c3d4e5\",\n \"name\": \"Example Segment\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.mailchimp.com/3.0/segments") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"definition\": {\n \"conditions\": [\n {\n \"field\": \"merge0\",\n \"op\": \"contains\",\n \"value\": [\n \"yahoo.com\"\n ]\n }\n ],\n \"match\": \"all\",\n \"contacts\": {\n \"email\": {\n \"marketing\": [\n {\n \"sendable\": true\n }\n ]\n }\n },\n \"schema_version\": 2\n },\n \"list_id\": \"a1b2c3d4e5\",\n \"name\": \"Example Segment\"\n}") .asString(); ``` ```php request('POST', 'https://api.mailchimp.com/3.0/segments', [ 'body' => '{ "definition": { "conditions": [ { "field": "merge0", "op": "contains", "value": [ "yahoo.com" ] } ], "match": "all", "contacts": { "email": { "marketing": [ { "sendable": true } ] } }, "schema_version": 2 }, "list_id": "a1b2c3d4e5", "name": "Example Segment" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.mailchimp.com/3.0/segments"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"definition\": {\n \"conditions\": [\n {\n \"field\": \"merge0\",\n \"op\": \"contains\",\n \"value\": [\n \"yahoo.com\"\n ]\n }\n ],\n \"match\": \"all\",\n \"contacts\": {\n \"email\": {\n \"marketing\": [\n {\n \"sendable\": true\n }\n ]\n }\n },\n \"schema_version\": 2\n },\n \"list_id\": \"a1b2c3d4e5\",\n \"name\": \"Example Segment\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "definition": [ "conditions": [ [ "field": "merge0", "op": "contains", "value": ["yahoo.com"] ] ], "match": "all", "contacts": ["email": ["marketing": [["sendable": true]]]], "schema_version": 2 ], "list_id": "a1b2c3d4e5", "name": "Example Segment" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.mailchimp.com/3.0/segments")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```