> 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. # Search members GET https://api.mailchimp.com/3.0/search-members Search for list members. This search can be restricted to a specific list, or can be used to search across all lists in an account. Reference: https://mailchimp.com/developer/marketing/api/search-members/list ## 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 ### Query parameters - `fields` (list of string, optional) — A comma-separated list of fields to return. Reference parameters of sub-objects with dot notation. - `exclude_fields` (list of string, optional) — A comma-separated list of fields to exclude. Reference parameters of sub-objects with dot notation. - `query` (string, required) — The search query used to filter results. Query should be a valid email, or a string representing a contact's first or last name. - `list_id` (string, optional) — The unique id for the list. ## Response ### 200 - `_links` (list of 30SearchMembersGetResponsesContentApplicationJsonSchemaLinksItems, optional) — A list of link types and descriptions for the API schema documents. - `exact_matches` (30SearchMembersGetResponsesContentApplicationJsonSchemaExactMatches, optional) — Exact matches of the provided search query. - `full_search` (30SearchMembersGetResponsesContentApplicationJsonSchemaFullSearch, optional) — Partial matches of the provided search query. ## Types ### 30SearchMembersGetResponsesContentApplicationJsonSchemaLinksItems This object represents a link from the resource where it is found to another resource or action that may be performed. - `href` (string, optional) — This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action. - `method` (enum, optional) — The HTTP method that should be used when accessing the URL defined in 'href'. - Allowed values: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS`, `HEAD` - `rel` (string, optional) — As with an HTML 'rel' attribute, this describes the type of link. - `schema` (string, optional) — For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to. - `targetSchema` (string, optional) — For GETs, this is a URL representing the schema that the response should conform to. ### 30SearchMembersGetResponsesContentApplicationJsonSchemaExactMatches Exact matches of the provided search query. - `members` (list of ListMembers, optional) — An array of objects, each representing a specific list member. - `total_items` (integer, optional) — The total number of items matching the query regardless of pagination. ### 30SearchMembersGetResponsesContentApplicationJsonSchemaFullSearch Partial matches of the provided search query. - `members` (list of ListMembers, optional) — An array of objects, each representing a specific list member. - `total_items` (integer, optional) — The total number of items matching the query regardless of pagination. ### ListMembers Individuals who are currently or have been previously subscribed to this list, including members who have bounced or unsubscribed. - `_links` (list of ListMembersLinksItems, optional) — A list of link types and descriptions for the API schema documents. - `consents_to_one_to_one_messaging` (boolean, optional) — Indicates whether a contact consents to 1:1 messaging. - `contact_id` (string, optional) — As Mailchimp evolves beyond email, you may eventually have contacts without email addresses. While the `id` is the MD5 hash of their email address, this `contact_id` is agnostic of contact’s inclusion of an email address. - `email_address` (string, optional) — Email address for a subscriber. - `email_client` (string, optional) — The list member's email client. - `email_type` (any, optional) — Type of email this member asked to get ('html' or 'text'). - `id` (string, optional) — The MD5 hash of the lowercase version of the list member's email address. - `interests` (map from string to boolean, optional) — The key of this object's properties is the ID of the interest in question. - `ip_opt` (string, optional) — The IP address the subscriber used to confirm their opt-in status. - `ip_signup` (string, optional) — IP address the subscriber signed up from. - `language` (string, optional) — If set/detected, the [subscriber's language](https://mailchimp.com/help/view-and-edit-contact-languages/). - `last_changed` (datetime, optional) — The date and time the member's info was last changed in ISO 8601 format. - `last_note` (ListMembersLastNote, optional) — The most recent Note added about this member. - `list_id` (string, optional) — The list id. - `location` (ListMembersLocation, optional) — Subscriber location information. - `marketing_permissions` (list of ListMembersMarketingPermissionsItems, optional) — The marketing permissions for the subscriber. - `member_rating` (integer, optional) — Star rating for this member, between 1 and 5. - `merge_fields` (map from string to ListMembersMergeFields, optional, nullable) — A dictionary of merge fields where the keys are the merge tags. See the [Merge Fields documentation](https://mailchimp.com/developer/marketing/docs/merge-fields/#structure) for more about the structure. - `sms_phone_number` (string, optional) — A US phone number for SMS contact. - `sms_subscription_last_updated` (string, optional) — The datetime when the SMS subscription was last updated - `sms_subscription_status` (enum, optional) — The status of an SMS subscription. - Allowed values: `subscribed`, `unsubscribed`, `nonsubscribed`, `pending` - `source` (string, optional) — The source from which the subscriber was added to this list. - `stats` (ListMembersStats, optional) — Open and click rates for this subscriber. - `status` (enum, optional) — Subscriber's current status. - Allowed values: `subscribed`, `unsubscribed`, `cleaned`, `pending`, `transactional`, `archived` - `tags` (list of ListMembersTagsItems, optional) — Returns up to 50 tags applied to this member. To retrieve all tags see [Member Tags](https://mailchimp.com/developer/marketing/api/list-member-tags/). - `tags_count` (integer, optional) — The number of tags applied to this member. - `timestamp_opt` (datetime, optional) — The date and time the subscriber confirmed their opt-in status in ISO 8601 format. - `timestamp_signup` (datetime, optional) — The date and time the subscriber signed up for the list in ISO 8601 format. - `unique_email_id` (string, optional) — An identifier for the address across all of Mailchimp. - `unsubscribe_reason` (string, optional) — A subscriber's reason for unsubscribing. - `vip` (boolean, optional) — [VIP status](https://mailchimp.com/help/designate-and-send-to-vip-contacts/) for subscriber. - `web_id` (integer, optional) — The ID used in the Mailchimp web application. View this member in your Mailchimp account at `https://{dc}.admin.mailchimp.com/lists/members/view?id={web_id}`. ### ListMembersLinksItems This object represents a link from the resource where it is found to another resource or action that may be performed. - `href` (string, optional) — This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action. - `method` (enum, optional) — The HTTP method that should be used when accessing the URL defined in 'href'. - Allowed values: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS`, `HEAD` - `rel` (string, optional) — As with an HTML 'rel' attribute, this describes the type of link. - `schema` (string, optional) — For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to. - `targetSchema` (string, optional) — For GETs, this is a URL representing the schema that the response should conform to. ### ListMembersLastNote The most recent Note added about this member. - `created_at` (datetime, optional) — The date and time the note was created in ISO 8601 format. - `created_by` (string, optional) — The author of the note. - `note` (string, optional) — The content of the note. - `note_id` (integer, optional) — The note id. ### ListMembersLocation Subscriber location information. - `country_code` (string, optional) — The unique code for the location country. - `dstoff` (integer, optional) — The offset for timezones where daylight saving time is observed. - `gmtoff` (integer, optional) — The time difference in hours from GMT. - `latitude` (double, optional) — The location latitude. - `longitude` (double, optional) — The location longitude. - `region` (string, optional) — The region for the location. - `timezone` (string, optional) — The timezone for the location. ### ListMembersMarketingPermissionsItems A single marketing permission a subscriber has either opted-in to or opted-out of. - `enabled` (boolean, optional) — If the subscriber has opted-in to the marketing permission. - `marketing_permission_id` (string, optional) — The id for the marketing permission on the list - `text` (string, optional) — The text of the marketing permission. ### ListMembersMergeFields This object's keys are merge tags (like FNAME). It's values are the values to be added to the merge field. ### ListMembersStats Open and click rates for this subscriber. - `avg_click_rate` (double, optional) — A subscriber's average clickthrough rate. - `avg_open_rate` (double, optional) — A subscriber's average open rate. - `ecommerce_data` (ListMembersStatsEcommerceData, optional) — Ecommerce stats for the list member if the list is attached to a store. ### ListMembersTagsItems - `id` (integer, optional) — The tag id. - `name` (string, optional) — The name of the tag ### ListMembersMergeFields0 - `addr1` (string, required) - `city` (string, required) - `state` (string, required) - `zip` (string, required) - `addr2` (string, optional) - `country` (string, optional) ### ListMembersStatsEcommerceData Ecommerce stats for the list member if the list is attached to a store. - `currency_code` (string, optional) — The three-letter ISO 4217 code for the currency that the store accepts. - `number_of_orders` (double, optional) — The total number of orders placed by the list member. - `total_revenue` (double, optional) — The total revenue the list member has brought in. ## Examples **Response** ```json { "_links": [ { "href": "string", "method": "GET", "rel": "string", "schema": "string", "targetSchema": "string" } ], "exact_matches": { "members": [ { "_links": [ { "href": "string", "method": "GET", "rel": "string", "schema": "string", "targetSchema": "string" } ], "consents_to_one_to_one_messaging": true, "contact_id": "string", "email_address": "string", "email_client": "string", "email_type": null, "id": "string", "interests": {}, "ip_opt": "string", "ip_signup": "string", "language": "string", "last_changed": "2024-01-15T09:30:00Z", "last_note": { "created_at": "2024-01-15T09:30:00Z", "created_by": "string", "note": "string", "note_id": 1 }, "list_id": "string", "location": { "country_code": "string", "dstoff": 1, "gmtoff": 1, "latitude": 1.1, "longitude": 1.1, "region": "string", "timezone": "string" }, "marketing_permissions": [ { "enabled": true, "marketing_permission_id": "string", "text": "string" } ], "member_rating": 1, "merge_fields": {}, "sms_phone_number": "string", "sms_subscription_last_updated": "string", "sms_subscription_status": "subscribed", "source": "string", "stats": { "avg_click_rate": 1.1, "avg_open_rate": 1.1, "ecommerce_data": { "currency_code": "USD", "number_of_orders": 1.1, "total_revenue": 1.1 } }, "status": "subscribed", "tags": [ { "id": 1, "name": "string" } ], "tags_count": 1, "timestamp_opt": "2024-01-15T09:30:00Z", "timestamp_signup": "2024-01-15T09:30:00Z", "unique_email_id": "string", "unsubscribe_reason": "string", "vip": true, "web_id": 1 } ], "total_items": 1 }, "full_search": { "members": [ { "_links": [ { "href": "string", "method": "GET", "rel": "string", "schema": "string", "targetSchema": "string" } ], "consents_to_one_to_one_messaging": true, "contact_id": "string", "email_address": "string", "email_client": "string", "email_type": null, "id": "string", "interests": {}, "ip_opt": "string", "ip_signup": "string", "language": "string", "last_changed": "2024-01-15T09:30:00Z", "last_note": { "created_at": "2024-01-15T09:30:00Z", "created_by": "string", "note": "string", "note_id": 1 }, "list_id": "string", "location": { "country_code": "string", "dstoff": 1, "gmtoff": 1, "latitude": 1.1, "longitude": 1.1, "region": "string", "timezone": "string" }, "marketing_permissions": [ { "enabled": true, "marketing_permission_id": "string", "text": "string" } ], "member_rating": 1, "merge_fields": {}, "sms_phone_number": "string", "sms_subscription_last_updated": "string", "sms_subscription_status": "subscribed", "source": "string", "stats": { "avg_click_rate": 1.1, "avg_open_rate": 1.1, "ecommerce_data": { "currency_code": "USD", "number_of_orders": 1.1, "total_revenue": 1.1 } }, "status": "subscribed", "tags": [ { "id": 1, "name": "string" } ], "tags_count": 1, "timestamp_opt": "2024-01-15T09:30:00Z", "timestamp_signup": "2024-01-15T09:30:00Z", "unique_email_id": "string", "unsubscribe_reason": "string", "vip": true, "web_id": 1 } ], "total_items": 1 } } ``` **SDK Code** ```python import requests url = "https://api.mailchimp.com/3.0/search-members" querystring = {"query":"query"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.mailchimp.com/3.0/search-members?query=query'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; 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" "net/http" "io" ) func main() { url := "https://api.mailchimp.com/3.0/search-members?query=query" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") 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/search-members?query=query") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.mailchimp.com/3.0/search-members?query=query") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.mailchimp.com/3.0/search-members?query=query', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.mailchimp.com/3.0/search-members?query=query"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.mailchimp.com/3.0/search-members?query=query")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers 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() ```