--- title: "Search campaigns" method: GET path: "/3.0/search-campaigns" tags: ["search-campaigns"] --- # Search campaigns `GET /3.0/search-campaigns` ## Request - Base URL: `https://api.mailchimp.com` - URL: `https://api.mailchimp.com/3.0/search-campaigns` - Auth: one of: - HTTP bearer - OAuth 2 - Authorization code: `https://login.mailchimp.com/oauth2/authorize` - Token URL: `https://login.mailchimp.com/oauth2/token` - TypeScript: (a function with typed inputs; its response is checked against the schema) Search all campaigns for the specified query terms. ## Query parameters - `fields` string[] - `exclude_fields` string[] - `query` string, required ## Response `200` - object: Campaigns and Snippets found for given search term. - `_links` object[]: A list of link types and descriptions for the API schema documents. - `href` string: This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action. - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD': The HTTP method that should be used when accessing the URL defined in 'href'. - `rel` string: As with an HTML 'rel' attribute, this describes the type of link. - `schema` string: 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: For GETs, this is a URL representing the schema that the response should conform to. - `results` object[]: An array of matching campaigns and snippets. - `campaign` object: A summary of an individual campaign's settings and content. - `_links` object[]: A list of link types and descriptions for the API schema documents. - `href` string: This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action. - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD': The HTTP method that should be used when accessing the URL defined in 'href'. - `rel` string: As with an HTML 'rel' attribute, this describes the type of link. - `schema` string: 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: For GETs, this is a URL representing the schema that the response should conform to. - `ab_split_opts` object: [A/B Testing](https://mailchimp.com/help/about-ab-tests/) options for a campaign. - `from_name_a` string: For campaigns split on 'From Name', the name for Group A. - `from_name_b` string: For campaigns split on 'From Name', the name for Group B. - `pick_winner` 'opens' | 'clicks' | 'manual': How we should evaluate a winner. Based on 'opens', 'clicks', or 'manual'. - `reply_email_a` string: For campaigns split on 'From Name', the reply-to address for Group A. - `reply_email_b` string: For campaigns split on 'From Name', the reply-to address for Group B. - `send_time_a` string, date-time: The send time for Group A. - `send_time_b` string, date-time: The send time for Group B. - `send_time_winner` string: The send time for the winning version. - `split_size` integer: The size of the split groups. Campaigns split based on 'schedule' are forced to have a 50/50 split. Valid split integers are between 1-50. - `split_test` 'subject' | 'from_name' | 'schedule': The type of AB split to run. - `subject_a` string: For campaigns split on 'Subject Line', the subject line for Group A. - `subject_b` string: For campaigns split on 'Subject Line', the subject line for Group B. - `wait_time` integer: The amount of time to wait before picking a winner. This cannot be changed after a campaign is sent. - `wait_units` 'hours' | 'days': How unit of time for measuring the winner ('hours' or 'days'). This cannot be changed after a campaign is sent. - `archive_url` string: The link to the campaign's archive version in ISO 8601 format. - `content_type` 'template' | 'html' | 'url' | 'multichannel': How the campaign's content is put together. - `create_time` string, date-time: The date and time the campaign was created in ISO 8601 format. - `delivery_status` object: Updates on campaigns in the process of sending. - `can_cancel` boolean: Whether a campaign send can be canceled. - `emails_canceled` integer: The total number of emails canceled for this campaign. - `emails_sent` integer: The total number of emails confirmed sent for this campaign so far. - `enabled` boolean: Whether Campaign Delivery Status is enabled for this account and campaign. - `status` 'delivering' | 'delivered' | 'canceling' | 'canceled': The current state of a campaign delivery. - `emails_sent` integer: The total number of emails sent for this campaign. - `id` string: A string that uniquely identifies this campaign. - `long_archive_url` string: The original link to the campaign's archive version. - `needs_block_refresh` boolean: Determines if the campaign needs its blocks refreshed by opening the web-based campaign editor. Deprecated and will always return false. - `parent_campaign_id` string: If this campaign is the child of another campaign, this identifies the parent campaign. For Example, for RSS or Automation children. - `recipients` object: List settings for the campaign. - `list_id` string: The unique list id. - `list_is_active` boolean: The status of the list used, namely if it's deleted or disabled. - `list_name` string: The name of the list. - `recipient_count` integer: Count of the recipients on the associated list. Formatted as an integer. - `segment_opts` object: An object representing all segmentation options. This object should contain a `saved_segment_id` to use an existing segment, or you can create a new segment by including both `match` and `conditions` options. - `conditions` union[]: Segment match conditions. There are multiple possible types, see the [condition types documentation](https://mailchimp.com/developer/marketing/docs/alternative-schemas/#segment-condition-schemas). - union - … - `match` 'any' | 'all': Segment match type. - `prebuilt_segment_id` string: The prebuilt segment id, if a prebuilt segment has been designated for this campaign. - `saved_segment_id` union: The id for an existing saved segment. - integer - string - `segment_text` string: A description of the [segment](https://mailchimp.com/help/create-and-send-to-a-segment/) used for the campaign. Formatted as a string marked up with HTML. - `report_summary` object: For sent campaigns, a summary of opens, clicks, and e-commerce data. - `click_rate` number: The number of unique clicks divided by the total number of successful deliveries. - `clicks` integer: The total number of clicks for an campaign. - `ecommerce` object: E-Commerce stats for a campaign. - `total_orders` integer: The total orders for a campaign. - `total_revenue` number: The total revenue for a campaign. Calculated as the sum of all order totals minus shipping and tax totals. - `total_spent` number: The total spent for a campaign. Calculated as the sum of all order totals with no deductions. - `open_rate` number: The number of unique opens divided by the total number of successful deliveries. - `opens` integer: The total number of opens for a campaign. - `subscriber_clicks` integer: The number of unique clicks. - `unique_opens` integer: The number of unique opens. - `resend_shortcut_eligibility` object: Determines if the campaign qualifies for the Campaign Resend Shortcuts. Only included when query parameter `include_resend_shortcuts` is `true`. - `to_new_subscribers` object: Determines if the campaign qualifies to be resent to new subscribers. - `is_eligible` boolean: Determines if the campaign qualifies to be resent to this segment. - `reason` string: The reason the campaign is not eligible to be resent to this segment. - `to_non_clickers` object: Determines if the campaign qualifies to be resent to non-clickers. - `is_eligible` boolean: Determines if the campaign qualifies to be resent to this segment. - `reason` string: The reason the campaign is not eligible to be resent to this segment. - `to_non_openers` object: Determines if the campaign qualifies to be resent to non-openers. - `is_eligible` boolean: Determines if the campaign qualifies to be resent to this segment. - `reason` string: The reason the campaign is not eligible to be resent to this segment. - `to_non_purchasers` object: Determines if the campaign qualifies to be resent to non-purchasers. - `is_eligible` boolean: Determines if the campaign qualifies to be resent to this segment. - `reason` string: The reason the campaign is not eligible to be resent to this segment. - `resend_shortcut_usage` object: Information about campaigns related through shortcuts. - `original_campaign` object: The original campaign that was resent. - `id` string: ID for the resent campaign. - `shortcut_type` 'non_openers' | 'new_subscribers' | 'non_clickers' | 'non_purchasers': Which campaign resend shortcut was used. - `title` string: The title of the original campaign. - `web_id` integer: The ID for the resent campaign used in the Mailchimp web application. View this campaign in your Mailchimp account at `https://{dc}.admin.mailchimp.com/campaigns/show/?id={web_id}`. - `shortcut_campaigns` object[]: Campaigns that were created from Campaign Resend Shortcuts for this campaign - `id` string: Unique ID for the resent campaign. - `send_time` string, date-time: The date and time a resent campaign was sent. - `shortcut_type` 'non_openers' | 'new_subscribers' | 'non_clickers' | 'non_purchasers': Which campaign resend shortcut was used. - `status` 'save' | 'paused' | 'schedule' | 'sending' | 'sent' | 'canceled' | 'canceling' | 'archived': The current status of the campaign. - `web_id` integer: The ID for the resent campaign used in the Mailchimp web application. View this campaign in your Mailchimp account at `https://{dc}.admin.mailchimp.com/campaigns/show/?id={web_id}`. - `resendable` boolean: Determines if the campaign qualifies to be resent to non-openers. - `rss_opts` object: [RSS](https://mailchimp.com/help/share-your-blog-posts-with-mailchimp/) options for a campaign. - `constrain_rss_img` boolean: Whether to add CSS to images in the RSS feed to constrain their width in campaigns. - `feed_url` string, uri: The URL for the RSS feed. - `frequency` 'daily' | 'weekly' | 'monthly': The frequency of the RSS Campaign. - `last_sent` string, date-time: The date the campaign was last sent. - `schedule` object: The schedule for sending the RSS Campaign. - `daily_send` object: The days of the week to send a daily RSS Campaign. - `friday` boolean: Sends the daily RSS Campaign on Fridays. - `monday` boolean: Sends the daily RSS Campaign on Mondays. - `saturday` boolean: Sends the daily RSS Campaign on Saturdays. - `sunday` boolean: Sends the daily RSS Campaign on Sundays. - `thursday` boolean: Sends the daily RSS Campaign on Thursdays. - `tuesday` boolean: Sends the daily RSS Campaign on Tuesdays. - `wednesday` boolean: Sends the daily RSS Campaign on Wednesdays. - `hour` integer: The hour to send the campaign in local time. Acceptable hours are 0-23. For example, '4' would be 4am in [your account's default time zone](https://mailchimp.com/help/set-account-details/). - `monthly_send_date` number: The day of the month to send a monthly RSS Campaign. Acceptable days are 0-31, where '0' is always the last day of a month. Months with fewer than the selected number of days will not have an RSS campaign sent out that day. For example, RSS Campaigns set to send on the 30th will not go out in February. - `weekly_send_day` 'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday': The day of the week to send a weekly RSS Campaign. - `send_time` string, date-time: The date and time a campaign was sent. - `settings` object: The settings for your campaign, including subject, from name, reply-to address, and more. - `authenticate` boolean: Whether Mailchimp [authenticated](https://mailchimp.com/help/about-email-authentication/) the campaign. Defaults to `true`. - `auto_fb_post` string[]: An array of [Facebook](https://mailchimp.com/help/connect-or-disconnect-the-facebook-integration/) page ids to auto-post to. - `auto_footer` boolean: Automatically append Mailchimp's [default footer](https://mailchimp.com/help/about-campaign-footers/) to the campaign. - `auto_tweet` boolean: Automatically tweet a link to the [campaign archive](https://mailchimp.com/help/about-email-campaign-archives-and-pages/) page when the campaign is sent. - `drag_and_drop` boolean: Whether the campaign uses the drag-and-drop editor. - `fb_comments` boolean: Allows Facebook comments on the campaign (also force-enables the Campaign Archive toolbar). Defaults to `true`. - `folder_id` string: If the campaign is listed in a folder, the id for that folder. - `from_name` string: The 'from' name on the campaign (not an email address). - `inline_css` boolean: Automatically inline the CSS included with the campaign content. - `preview_text` string: The preview text for the campaign. - `reply_to` string: The reply-to email address for the campaign. - `subject_line` string: The subject line for the campaign. - `template_id` integer: The id for the template used in this campaign. - `timewarp` boolean: Send this campaign using [Timewarp](https://mailchimp.com/help/use-timewarp/). - `title` string: The title of the campaign. - `to_name` string: The campaign's custom 'To' name. Typically the first name [audience field](https://mailchimp.com/help/getting-started-with-merge-tags/). - `use_conversation` boolean: Use Mailchimp Conversation feature to manage out-of-office replies. - `social_card` object: The preview for the campaign, rendered by social networks like Facebook and Twitter. [Learn more](https://mailchimp.com/help/enable-and-customize-social-cards/). - `description` string: A short summary of the campaign to display. - `image_url` string: The url for the header image for the card. - `title` string: The title for the card. Typically the subject line of the campaign. - `status` 'save' | 'paused' | 'schedule' | 'sending' | 'sent' | 'canceled' | 'canceling' | 'archived': The current status of the campaign. - `tracking` object: The tracking options for a campaign. - `capsule` object: Deprecated - `notes` boolean: Update contact notes for a campaign based on subscriber email addresses. - `clicktale` string: The custom slug for [ClickTale](https://mailchimp.com/help/additional-tracking-options-for-campaigns/) tracking (max of 50 bytes). - `ecomm360` boolean: Whether to enable e-commerce tracking. - `goal_tracking` boolean: Deprecated - `google_analytics` string: The custom slug for [Google Analytics](https://mailchimp.com/help/integrate-google-analytics-with-mailchimp/) tracking (max of 50 bytes). - `html_clicks` boolean: Whether to [track clicks](https://mailchimp.com/help/enable-and-view-click-tracking/) in the HTML version of the campaign. Defaults to `true`. Cannot be set to false for variate campaigns. - `opens` boolean: Whether to [track opens](https://mailchimp.com/help/about-open-tracking/). Defaults to `true`. Cannot be set to false for variate campaigns. - `salesforce` object: Deprecated - `campaign` boolean: Create a campaign in a connected Salesforce account. - `notes` boolean: Update contact notes for a campaign based on subscriber email addresses. - `text_clicks` boolean: Whether to [track clicks](https://mailchimp.com/help/enable-and-view-click-tracking/) in the plain-text version of the campaign. Defaults to `true`. Cannot be set to false for variate campaigns. - `type` 'regular' | 'plaintext' | 'absplit' | 'rss' | 'variate': There are four types of [campaigns](https://mailchimp.com/help/getting-started-with-campaigns/) you can create in Mailchimp. A/B Split campaigns have been deprecated and variate campaigns should be used instead. - `variate_settings` object: The settings specific to A/B test campaigns. - `combinations` object[]: Combinations of possible variables used to build emails. - `content_description` integer: The index of `variate_settings.contents` used. - `from_name` integer: The index of `variate_settings.from_names` used. - `id` string: Unique ID for the combination. - `recipients` integer: The number of recipients for this combination. - `reply_to` integer: The index of `variate_settings.reply_to_addresses` used. - `send_time` integer: The index of `variate_settings.send_times` used. - `subject_line` integer: The index of `variate_settings.subject_lines` used. - `contents` string[]: Descriptions of possible email contents. To set campaign contents, make a PUT request to /campaigns/{campaign_id}/content with the field 'variate_contents'. - `from_names` string[]: The possible from names. The number of from_names provided must match the number of reply_to_addresses. If no from_names are provided, settings.from_name will be used. - `reply_to_addresses` string[]: The possible reply-to addresses. The number of reply_to_addresses provided must match the number of from_names. If no reply_to_addresses are provided, settings.reply_to will be used. - `send_times` string[]: The possible send times to test. The times provided should be in the format YYYY-MM-DD HH:MM:SS. If send_times are provided to test, the test_size will be set to 100% and winner_criteria will be ignored. - `subject_lines` string[]: The possible subject lines to test. If no subject lines are provided, settings.subject_line will be used. - `test_size` integer: The percentage of recipients to send the test combinations to, must be a value between 10 and 100. - `wait_time` integer: The number of minutes to wait before choosing the winning campaign. The value of wait_time must be greater than 0 and in whole hours, specified in minutes. - `winner_criteria` 'opens' | 'clicks' | 'manual' | 'total_revenue': The combination that performs the best. This may be determined automatically by click rate, open rate, or total revenue -- or you may choose manually based on the reporting data you find the most valuable. For Multivariate Campaigns testing send_time, winner_criteria is ignored. For Multivariate Campaigns with 'manual' as the winner_criteria, the winner must be chosen in the Mailchimp web application. - `winning_campaign_id` string: ID of the campaign that was sent to the remaining recipients based on the winning combination. - `winning_combination_id` string: ID for the winning combination. - `web_id` integer: The ID used in the Mailchimp web application. View this campaign in your Mailchimp account at `https://{dc}.admin.mailchimp.com/campaigns/show/?id={web_id}`. - `snippet` string - `total_items` integer: The total number of items matching the query regardless of pagination. ## Other responses - `default`: An error generated by the Mailchimp API. --- [API](https://skmtc.dev/mailchimp/apis/mailchimp-api.md) - [All operations](https://skmtc.dev/mailchimp/apis/mailchimp-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mailchimp/apis/mailchimp-api/revisions/53bf4b156855?raw)