> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://mailchimp.com/developer/marketing/api/audiences/create-audience-contact/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://mailchimp.com/_mcp/server. # Add Contact POST https://api.mailchimp.com/3.0/audiences/{audience_id}/contacts Content-Type: application/json Create a new omni-channel contact for an audience. Reference: https://mailchimp.com/developer/marketing/api/audiences/create-audience-contact ## 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 ### Path parameters - `audience_id` (string, required) — The unique ID for the audience. ### Query parameters - `merge_field_validation_mode` (enum, optional) — Defines how merge field validation is handled. When set to `ignore_required_checks`, the API does not raise an error if required merge fields are missing from the request. When set to `strict`, the API enforces validation and returns an error if any required merge field is not provided. If this setting is omitted, `strict` is applied by default. - Allowed values: `ignore_required_checks`, `strict` - `data_mode` (enum, optional) — Indicates the data processing mode. In `historical` mode, contact data changes do not trigger automations or webhooks. In `live mode`, such changes do trigger them. - Allowed values: `historical`, `live` ### Body (application/json) This endpoint expects an object. - `email_channel` (30AudiencesAudienceIdContactsPostRequestBodyContentApplicationJsonSchemaEmailChannel, optional) - `language` (string, optional) — The contact's detected language. - `merge_fields` (map from string to 30AudiencesAudienceIdContactsPostRequestBodyContentApplicationJsonSchemaMergeFields, 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_channel` (30AudiencesAudienceIdContactsPostRequestBodyContentApplicationJsonSchemaSmsChannel, optional) - `tags` (list of 30AudiencesAudienceIdContactsPostRequestBodyContentApplicationJsonSchemaTagsItems, optional) — An array of tags to add to the contact. Accepts tag name strings or objects with name and status. This operation is append-only; existing tags will be preserved, and only new tags from this array will be added. - `update_existing` (boolean, optional) — If a contact already exists, update them instead of returning a conflict error. When `true` and a matching contact is found (by email or phone), the existing contact is updated with the provided channel data. Defaults to `false`. ## Response ### 200 - `audience_id` (string, optional) — The unique ID for the audience. - `created_at` (datetime, optional) — The date that the contact was created. - `email_channel` (AudiencesContactEmailChannel, optional) - `id` (string, optional) — The unique ID for the contact. - `language` (enum, optional) — The contact's detected language. Empty string when no language has been detected or set. - Allowed values: ``, `en`, `ar`, `af`, `be`, `bg`, `ca`, `zh`, `zh_CN`, `hr`, `cs`, `da`, `nl`, `et`, `fa`, `fi`, `fr`, `fr_CA`, `de`, `el`, `he`, `hi`, `hu`, `is`, `id`, `ga`, `it`, `ja`, `km`, `ko`, `lv`, `lt`, `mt`, `ms`, `mk`, `no`, `pl`, `pt`, `pt_PT`, `ro`, `ru`, `sr`, `sk`, `sl`, `es`, `es_ES`, `sw`, `sv`, `ta`, `th`, `tr`, `uk`, `vi` - `last_updated_at` (datetime, optional) — The date that the contact was last updated. - `merge_fields` (map from string to AudiencesContactMergeFields, 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_channel` (AudiencesContactSmsChannel, optional) - `source` (AudiencesContactSource, optional) — The source from which the parent's entity was created. - `status` (enum, optional) — The status of a contact. - Allowed values: `active`, `archived` - `tags` (list of string, optional) — The tags assigned to this contact. ## Types ### 30AudiencesAudienceIdContactsPostRequestBodyContentApplicationJsonSchemaEmailChannel - `email` (string, optional) — Email address - `marketing_consent` (30AudiencesAudienceIdContactsPostRequestBodyContentApplicationJsonSchemaEmailChannelMarketingConsent, optional) — A contact's current consent status for email marketing communications. See the [Audiences (BETA) documentation](https://mailchimp.com/developer/marketing/docs/audiences-introduction) to learn about supported values. ### 30AudiencesAudienceIdContactsPostRequestBodyContentApplicationJsonSchemaMergeFields This object's keys are merge tags (like FNAME). It's values are the values to be added to the merge field. ### 30AudiencesAudienceIdContactsPostRequestBodyContentApplicationJsonSchemaSmsChannel - `marketing_consent` (30AudiencesAudienceIdContactsPostRequestBodyContentApplicationJsonSchemaSmsChannelMarketingConsent, optional) — A contact's current consent status for SMS marketing communications. See the [Audiences (BETA) documentation](https://mailchimp.com/developer/marketing/docs/audiences-introduction) to learn about supported values. - `sms_phone` (string, optional) — SMS Phone Number ### 30AudiencesAudienceIdContactsPostRequestBodyContentApplicationJsonSchemaTagsItems ### AudiencesContactEmailChannel - `effective_subscription_status` (AudiencesContactEmailChannelEffectiveSubscriptionStatus, optional) — A computation performed by the Mailchimp platform, triggered whenever any of its inputs change. Some inputs are controlled by API users, while others are tracked internally by the platform. Computation is based on: audience opt-in configuration (single vs. double opt-in), marketing consent status, and deliverability status (an internal state for a contact, maintained by Mailchimp for a specific marketing channel instance). This new API field is distinct from how contacts are displayed in the UI. See the [Audiences (BETA) documentation](https://mailchimp.com/developer/marketing/docs/audiences-introduction) to learn about supported values. - `email` (string, optional) — Email address - `hashed_email` (string, optional) — MD5 hash of the email address - `marketing_consent` (AudiencesContactEmailChannelMarketingConsent, optional) — A contact's current consent status for email marketing communications. See the [Audiences (BETA) documentation](https://mailchimp.com/developer/marketing/docs/audiences-introduction) to learn about supported values. - `source` (AudiencesContactEmailChannelSource, optional) — The source from which the parent's entity was created. ### AudiencesContactMergeFields This object's keys are merge tags (like FNAME). It's values are the values to be added to the merge field. ### AudiencesContactSmsChannel - `effective_subscription_status` (AudiencesContactSmsChannelEffectiveSubscriptionStatus, optional) — A computation performed by the Mailchimp platform, triggered whenever any of its inputs change. Some inputs are controlled by API users, while others are tracked internally by the platform. Computation is based on: audience opt-in configuration (single vs. double opt-in), marketing consent status, and deliverability status (an internal state for a contact, maintained by Mailchimp for a specific marketing channel instance). This new API field is distinct from how contacts are displayed in the UI. See the [Audiences (BETA) documentation](https://mailchimp.com/developer/marketing/docs/audiences-introduction) to learn about supported values. - `marketing_consent` (AudiencesContactSmsChannelMarketingConsent, optional) — A contact's current consent status for SMS marketing communications. See the [Audiences (BETA) documentation](https://mailchimp.com/developer/marketing/docs/audiences-introduction) to learn about supported values. - `sms_phone` (string, optional) — SMS Phone Number - `source` (AudiencesContactSmsChannelSource, optional) — The source from which the parent's entity was created. - `hashed_sms_phone` (string, optional) — SHA256 hash of the SMS phone number ### AudiencesContactSource The source from which the parent's entity was created. - `name` (string, optional) — The name of the entity's source ### 30AudiencesAudienceIdContactsPostRequestBodyContentApplicationJsonSchemaEmailChannelMarketingConsent A contact's current consent status for email marketing communications. See the [Audiences (BETA) documentation](https://mailchimp.com/developer/marketing/docs/audiences-introduction) to learn about supported values. - `status` (enum, optional) — Status of a contacts Marketing Consent - Allowed values: `confirmed`, `consented`, `denied`, `unknown` ### 30AudiencesAudienceIdContactsPostRequestBodyContentApplicationJsonSchemaMergeFields0 - `addr1` (string, required) - `city` (string, required) - `state` (string, required) - `zip` (string, required) - `addr2` (string, optional) - `country` (string, optional) ### 30AudiencesAudienceIdContactsPostRequestBodyContentApplicationJsonSchemaSmsChannelMarketingConsent A contact's current consent status for SMS marketing communications. See the [Audiences (BETA) documentation](https://mailchimp.com/developer/marketing/docs/audiences-introduction) to learn about supported values. - `source` (30AudiencesAudienceIdContactsPostRequestBodyContentApplicationJsonSchemaSmsChannelMarketingConsentSource, optional) — The source from which the parent's entity was created. - `status` (enum, optional) — The contact's SMS marketing consent status. Use `confirmed` for double opt-in audiences, `consented` for single opt-in audiences. - Allowed values: `consented`, `confirmed`, `unknown` - `captured_at` (datetime, optional) — The timestamp when SMS marketing consent was captured (ISO 8601). Only accepted and returned when status is `confirmed`. The timestamp of the consent state change being recorded. Defaults to the current time if not provided. If the contact already has a consent timestamp on record that is equal to or newer than the supplied value, the supplied value is ignored (staleness guard); to update the consent timestamp supply a value strictly newer than the stored one. ### Tag Object - `name` (string, required) - `status` (enum, required) - Allowed values: `active`, `inactive` ### AudiencesContactEmailChannelEffectiveSubscriptionStatus A computation performed by the Mailchimp platform, triggered whenever any of its inputs change. Some inputs are controlled by API users, while others are tracked internally by the platform. Computation is based on: audience opt-in configuration (single vs. double opt-in), marketing consent status, and deliverability status (an internal state for a contact, maintained by Mailchimp for a specific marketing channel instance). This new API field is distinct from how contacts are displayed in the UI. See the [Audiences (BETA) documentation](https://mailchimp.com/developer/marketing/docs/audiences-introduction) to learn about supported values. - `value` (enum, optional) - Allowed values: `subscribed`, `unsubscribed`, `nonsubscribed`, `pending` ### AudiencesContactEmailChannelMarketingConsent A contact's current consent status for email marketing communications. See the [Audiences (BETA) documentation](https://mailchimp.com/developer/marketing/docs/audiences-introduction) to learn about supported values. - `source` (AudiencesContactEmailChannelMarketingConsentSource, optional) — The source from which the parent's entity was created. - `status` (enum, optional) - Allowed values: `consented`, `denied`, `confirmed`, `unknown` - `captured_at` (datetime, optional) — The ISO 8601 timestamp when the email marketing consent state was recorded; accepted and returned only when status is `confirmed` or `consented`; defaults to the current time if omitted; ignored if older than an existing stored timestamp (staleness guard). ### AudiencesContactEmailChannelSource The source from which the parent's entity was created. - `name` (string, optional) — The name of the entity's source ### AudiencesContactMergeFields0 - `addr1` (string, required) - `city` (string, required) - `state` (string, required) - `zip` (string, required) - `addr2` (string, optional) - `country` (string, optional) ### AudiencesContactSmsChannelEffectiveSubscriptionStatus A computation performed by the Mailchimp platform, triggered whenever any of its inputs change. Some inputs are controlled by API users, while others are tracked internally by the platform. Computation is based on: audience opt-in configuration (single vs. double opt-in), marketing consent status, and deliverability status (an internal state for a contact, maintained by Mailchimp for a specific marketing channel instance). This new API field is distinct from how contacts are displayed in the UI. See the [Audiences (BETA) documentation](https://mailchimp.com/developer/marketing/docs/audiences-introduction) to learn about supported values. - `value` (enum, optional) - Allowed values: `subscribed`, `unsubscribed`, `nonsubscribed`, `pending` ### AudiencesContactSmsChannelMarketingConsent A contact's current consent status for SMS marketing communications. See the [Audiences (BETA) documentation](https://mailchimp.com/developer/marketing/docs/audiences-introduction) to learn about supported values. - `source` (AudiencesContactSmsChannelMarketingConsentSource, optional) — The source from which the parent's entity was created. - `status` (enum, optional) — The contact's SMS marketing consent status. Use `confirmed` for double opt-in audiences, `consented` for single opt-in audiences. `denied` is accepted on PATCH/PUT only (not POST) and drives an API-initiated unsubscribe; it cannot be used when creating a new contact. - Allowed values: `consented`, `confirmed`, `denied`, `unknown` - `captured_at` (datetime, optional) — The timestamp when SMS marketing consent was captured (ISO 8601). Only accepted and returned when status is `confirmed`. The timestamp of the consent state change being recorded. Defaults to the current time if not provided. If the contact already has a consent timestamp on record that is equal to or newer than the supplied value, the supplied value is ignored (staleness guard); to update the consent timestamp supply a value strictly newer than the stored one. ### AudiencesContactSmsChannelSource The source from which the parent's entity was created. - `name` (string, optional) — The name of the entity's source ### 30AudiencesAudienceIdContactsPostRequestBodyContentApplicationJsonSchemaSmsChannelMarketingConsentSource The source from which the parent's entity was created. - `name` (string, optional) — The name of the entity's source ### AudiencesContactEmailChannelMarketingConsentSource The source from which the parent's entity was created. - `name` (string, optional) — The name of the entity's source ### AudiencesContactSmsChannelMarketingConsentSource The source from which the parent's entity was created. - `name` (string, optional) — The name of the entity's source ## Examples **Request** ```json {} ``` **Response** ```json { "audience_id": "773280e405", "created_at": "2024-01-15T09:30:00Z", "email_channel": { "effective_subscription_status": { "value": "subscribed" }, "email": "example@freddiemail.com", "hashed_email": "9115d71ba28088047d342e3bcedacd0f", "marketing_consent": { "source": { "name": "string" }, "status": "consented", "captured_at": "2024-01-15T10:30:00Z" }, "source": { "name": "string" } }, "id": "7CCF816ADF6CE1B11AE09BB024A02B9B", "language": "en", "last_updated_at": "2024-01-15T09:30:00Z", "merge_fields": {}, "sms_channel": { "effective_subscription_status": { "value": "subscribed" }, "marketing_consent": { "source": { "name": "string" }, "status": "consented", "captured_at": "2024-01-15T10:30:00Z" }, "sms_phone": "+14045550102", "source": { "name": "string" }, "hashed_sms_phone": "0572084e1f8288816f02cdb7bd930c62400bc8aef510adfaa9eec2b995fa7609" }, "source": { "name": "string" }, "status": "active", "tags": [ "string" ] } ``` **SDK Code** ```python import requests url = "https://api.mailchimp.com/3.0/audiences/audience_id/contacts" payload = {} 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/audiences/audience_id/contacts'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{}' }; 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/audiences/audience_id/contacts" payload := strings.NewReader("{}") 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/audiences/audience_id/contacts") 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 = "{}" 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/audiences/audience_id/contacts") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{}") .asString(); ``` ```php request('POST', 'https://api.mailchimp.com/3.0/audiences/audience_id/contacts', [ 'body' => '{}', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.mailchimp.com/3.0/audiences/audience_id/contacts"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.mailchimp.com/3.0/audiences/audience_id/contacts")! 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() ``` > Find all the Mailchimp API documentation and tools developers need to send marketing and transactional emails.