Retrieve Mailchimp account details including name, contact info, total subscribers, and industry benchmarks.

Use this to verify API connectivity or inspect account-level metrics. Typically the first call in a workflow. Do not use this as a health check; use ping instead (faster, no payload). Use list_audiences to get per-audience stats.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Read-only, safe to retry.

Returns: JSON with fields: account_name (string), email (account owner), first_name, last_name, total_subscribers (int, all audiences combined), industry_stats (object with open/click rate benchmarks for the account's industry). Returns an error object if the API key is invalid or missing.

Example: get_account_info() -> {"account_name": "My Company", "total_subscribers": 5000, "industry_stats": {"open_rate": 0.21, ...}}

List audiences (lists) with subscriber counts and engagement rates.

First step in most workflows to discover list_id values. Use get_audience_details for full stats of a known audience. Use search_members to find a specific member.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry.

Args: count: Audiences to return (1-1000, default 10). Most accounts have fewer than 10. offset: Pagination offset. Use when total_items exceeds count.

Returns: JSON with total_items and audiences array. Each: id (use as list_id), name, member_count, unsubscribe_count, open_rate (0-1), click_rate (0-1), date_created.

Retrieve full stats, subscribe URL, and rating for a specific audience.

Use when you have a list_id and need detailed metrics or the public subscribe URL. Use list_audiences to browse all audiences and discover list_ids instead.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry. Returns 404 error if list_id is invalid.

Args: list_id: Audience/list ID (10-char alphanumeric, e.g. 'abc123def4'). Obtain from list_audiences.

Returns: JSON with id, name, stats (member_count, unsubscribe_count, open_rate, click_rate), date_created, list_rating (0-5), subscribe_url_short.

List campaigns with metadata, send stats, and filtering by status or date.

Use to browse campaigns and discover campaign IDs. Use get_campaign_details for full settings of a single campaign. Use get_campaign_report for post-send performance metrics. Use search_campaigns to find campaigns by keyword instead of browsing.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Read-only, safe to retry.

Args: count: Number of campaigns to return (1-1000, default 20). offset: Pagination offset. Use when total_items exceeds count. status: Filter by status. Valid values: 'save' (draft), 'paused', 'schedule', 'sending', 'sent'. Omit to return all statuses. since_send_time: Only return campaigns sent after this datetime. ISO 8601 format (e.g. '2025-01-01T00:00:00Z'). Only applies to sent campaigns.

Returns: JSON with total_items and campaigns array. Each campaign: id, type ('regular', 'plaintext', 'absplit', 'rss', 'variate'), status, title, subject_line, preview_text, send_time (ISO 8601 or null), emails_sent, list_id, list_name.

Example: list_campaigns(count=10, status="sent") -> {"total_items": 42, "campaigns": [{"id": "abc123", "status": "sent", ...}]}

Retrieve full configuration of a specific campaign including settings, recipients, and tracking options.

Use to inspect subject line, sender, audience targeting, or tracking settings. Use get_campaign_report instead for post-send performance (opens, clicks, bounces). Use list_campaigns or search_campaigns to find campaign IDs.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Read-only, safe to retry.

Args: campaign_id: The Mailchimp campaign ID (e.g. 'abc123def4'). Obtain from list_campaigns or search_campaigns.

Returns: JSON with fields: id, type, status, settings (subject_line, title, from_name, reply_to), recipients (list_id, segment_opts), send_time (ISO 8601 or null), emails_sent, tracking (opens, html_clicks, text_clicks booleans). Returns error if campaign_id is invalid.

Example: get_campaign_details(campaign_id="abc123def4") -> {"id": "abc123def4", "status": "sent", "settings": {"subject_line": "Spring Sale", ...}}

Retrieve aggregate performance metrics for a sent campaign: opens, clicks, bounces, benchmarks.

High-level overview. Use get_campaign_click_details for per-link data, get_open_details for per-recipient opens, get_campaign_recipients for delivery status. Only works for sent campaigns.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry.

Args: campaign_id: Campaign ID (e.g. 'abc123def4'). Must be sent. Obtain from list_campaigns(status="sent").

Returns: JSON with campaign_title, subject_line, emails_sent, abuse_reports, unsubscribed, send_time, opens (opens_total, unique_opens, open_rate 0-1), clicks (clicks_total, unique_clicks, click_rate), bounces, forwards, list_stats, industry_stats.

Retrieve per-link click data for a campaign showing which URLs were clicked and how many times.

Use to analyze which links drove engagement. Use get_campaign_report instead for aggregate totals (opens, clicks, bounces). Use get_email_activity for per-recipient click timelines. Only works for sent campaigns.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Read-only, safe to retry.

Args: campaign_id: The Mailchimp campaign ID (e.g. 'abc123def4'). Must be a sent campaign. count: Number of URL results to return (1-1000, default 20).

Returns: JSON with total_items and links array. Each link: url (string), total_clicks (int, includes repeat clicks), unique_clicks (int, one per subscriber), click_percentage (decimal 0-1).

Example: get_campaign_click_details(campaign_id="abc123") -> {"total_items": 5, "links": [{"url": "https://example.com", "total_clicks": 120, "unique_clicks": 95, "click_percentage": 0.019}]}

List members of a specific audience with subscription status, merge fields, and engagement stats.

Use to browse members of a known audience. Use search_members instead to find a specific person by email or name across all audiences. Use list_segment_members to list members of a specific segment/tag.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Read-only, safe to retry.

Args: list_id: The Mailchimp audience/list ID (e.g. 'abc123def4'). Obtain from list_audiences. count: Number of members to return (1-1000, default 20). offset: Pagination offset. Use when total_items exceeds count. status: Filter by subscription status. Valid values: 'subscribed', 'unsubscribed', 'cleaned', 'pending', 'transactional'. Omit to return all statuses.

Returns: JSON with total_items and members array. Each member: id (MD5 hash of email), email_address, status, full_name, merge_fields (object with FNAME, LNAME, etc.), open_rate (decimal 0-1), click_rate (decimal 0-1), timestamp_opt (ISO 8601 opt-in time).

Example: list_audience_members(list_id="abc123", count=50, status="subscribed") -> {"total_items": 5000, "members": [{"email_address": "jane@co.com", "status": "subscribed", ...}]}

Search for members across all audiences by email address or name, returning both exact and fuzzy matches.

Use when looking for a specific person and you may not know which audience they belong to. Use list_audience_members instead to browse all members of a known audience. Use get_member_activity or get_member_tags after finding a member for engagement data.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Read-only, safe to retry.

Args: query: Search query. Full email address for exact match, or name/partial email for fuzzy search. Minimum 3 characters. list_id: Optional audience/list ID to restrict search to a single audience. Obtain from list_audiences.

Returns: JSON with results array combining exact and fuzzy matches. Each result: email, status ('subscribed', 'unsubscribed', etc.), full_name, list_id (audience the member belongs to). Exact matches appear first.

Example: search_members(query="john@example.com") -> {"results": [{"email": "john@example.com", "status": "subscribed", "list_id": "abc123", ...}]}

Retrieve monthly growth history for an audience (subscribes, unsubscribes, cleaned).

Each record is one calendar month, ordered newest first. Use get_audience_details for current totals instead of historical trends.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry.

Args: list_id: Audience/list ID (10-char alphanumeric, e.g. 'abc123def4'). Obtain from list_audiences. count: Months to return (1-1000, default 12).

Returns: JSON with list_id and history array. Each: month (YYYY-MM), subscribed, unsubscribed, reconfirm, cleaned, pending, transactional (all cumulative ints).

List automation workflows in the account with status and send counts.

Returns all automations regardless of status (sending, paused, draft), ordered by creation date descending. Includes both Classic Automations and Customer Journeys. Use get_automation_emails for individual emails within a workflow.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry.

Args: count: Automations to return (1-1000, default 20). offset: Pagination offset. Use when total_items exceeds count.

Returns: JSON with total_items and automations array. Each: id, status ('sending'/'paused'/'draft'), title, emails_sent, start_time, create_time, list_id.

List email templates in the account (user-created and Mailchimp gallery templates).

Use to browse templates and find template IDs. Use get_template_default_content to extract HTML from a template. Use create_template to add new templates. Do not use to find campaigns; use list_campaigns instead.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry.

Args: count: Templates to return (1-1000, default 20). offset: Pagination offset. Use when total_items exceeds count.

Returns: JSON with total_items and templates array. Each: id (int), name, type ('user'/'gallery'/ 'base'), date_created, active (boolean).

Retrieve the default HTML content of a template for use in campaign content.

Use to extract a template's HTML before customizing it with set_campaign_content. Only works for user-created templates; gallery templates may return limited content. Use list_templates to find template IDs.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry. Returns 404 error if template_id is invalid.

Args: template_id: Template ID (numeric string, e.g. '12345'). Obtain from list_templates.

Returns: JSON with html (string, full HTML content), sections (object with editable content blocks).

Retrieve metadata for a template (name, type, dates, folder, thumbnail) without its HTML content.

Use to inspect a template's settings or verify it exists before referencing it elsewhere. Use get_template_default_content to fetch the actual HTML body. Use list_templates to browse and discover template IDs.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry. Returns 404 error if template_id is invalid.

Args: template_id: Template ID (numeric string, e.g. '12345'). Obtain from list_templates.

Returns: JSON with id, name, type ('user' | 'base' | 'gallery'), drag_and_drop (bool), date_created, date_edited, created_by, edited_by, active (bool), folder_id, thumbnail, share_url, category.

Create a new reusable email template from HTML content.

Use to save HTML email designs for reuse across campaigns. Retrieve template HTML later via get_template_default_content for use with set_campaign_content. Use list_templates to browse existing templates. Do not use for one-off emails; use set_campaign_content directly instead.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes.

Args: name: Display name for the template (e.g. 'Monthly Newsletter v2'). html: Complete HTML content. Must be valid HTML with inline CSS for email client compatibility. Mailchimp merge tags (e.g. |FNAME|, |UNSUB|) are supported. folder_id: Optional template folder ID to organize the template. Obtain from the Mailchimp web UI.

Returns: JSON with id (int, new template ID), name, type ('user'), active (boolean), date_created.

Update an existing template's name or HTML content.

Only provided fields are updated. Only works for user-created templates; gallery and base templates cannot be modified. Use create_template to create a new template instead of modifying a gallery template.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes. Returns 404 error if template_id is invalid.

Args: template_id: Template ID to update (numeric string, e.g. '12345'). Obtain from list_templates. name: New display name for the template. html: New HTML content. Replaces all existing content.

Returns: JSON with id, name, type, active, date_edited.

Delete a user-created template permanently.

Irreversible. Only works for user-created templates; gallery and base templates cannot be deleted. Does not affect campaigns already using this template's content. Use list_templates to find template IDs.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes. Returns 404 error if template_id is invalid or is not a user template.

Args: template_id: Template ID to delete (numeric string, e.g. '12345'). Must be type 'user'.

Returns: JSON with status ("deleted"), template_id.

List segments and tags for an audience with member counts and types.

Use to discover segment IDs for campaign targeting or membership management. Returns both static (tags, manual) and dynamic (saved, auto-updated) segments. Use get_segment for full details including filter conditions.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry.

Args: list_id: Audience/list ID (10-char alphanumeric, e.g. 'abc123def4'). Obtain from list_audiences. count: Segments to return (1-1000, default 20). offset: Pagination offset. Use when total_items exceeds count.

Returns: JSON with total_items and segments array. Each: id (use as segment_id), name, member_count, type ('static'/'saved'), created_at, updated_at.

Add a new member to an audience with optional name and tags.

Creates a new contact. Returns "Member Exists" error if already present. Choose the right member tool: add_member for new contacts, update_member to change profile/status of existing contacts, tag_member to manage tags on existing contacts, batch_subscribe for bulk add/update (up to 500), unsubscribe_member to opt out, delete_member for permanent GDPR removal. Side effect: status='pending' triggers a double opt-in confirmation email.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes.

Args: list_id: Audience/list ID (10-char alphanumeric, e.g. 'abc123def4'). Obtain from list_audiences. email_address: Email of the new member. Must not already exist in the audience. status: 'subscribed' (default), 'pending' (triggers opt-in email), 'unsubscribed', 'cleaned'. first_name: First name (FNAME merge field). last_name: Last name (LNAME merge field). tags: Comma-separated tag names (e.g. 'VIP,Newsletter'). Created automatically if new.

Returns: JSON with id (MD5 hash of email), email_address, status, full_name.

Update a member's profile fields or subscription status. Does not manage tags.

Only provided fields are updated; omitted fields remain unchanged. Idempotent: re-applying the same values is safe. Side effect: changing status to 'pending' triggers a re-confirmation email. Choose the right member tool: update_member for profile/status changes, tag_member for tag management, unsubscribe_member as shortcut for opt-out, add_member if the contact does not exist yet, batch_subscribe for bulk operations.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes. Returns 404 error if member does not exist. Returns 400 if status transition is invalid (e.g. cleaned to subscribed).

Args: list_id: Audience/list ID (10-char alphanumeric, e.g. 'abc123def4'). Obtain from list_audiences. email_address: Email of the member to update. Must exist in the audience. status: New status: 'subscribed', 'unsubscribed', 'cleaned', 'pending'. first_name: New first name (FNAME merge field). last_name: New last name (LNAME merge field).

Returns: JSON with id, email_address, status, full_name.

Unsubscribe a member from an audience, preserving profile and history for reporting.

Reversible via update_member(status='subscribed'). Use delete_member for permanent removal (GDPR). Returns 404 error if member does not exist.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes.

Args: list_id: Audience/list ID (10-char alphanumeric, e.g. 'abc123def4'). Obtain from list_audiences. email_address: Email of the member. Must be a valid email address and exist in the audience.

Returns: JSON with email_address, status ("unsubscribed").

Permanently delete a member and all their data from an audience.

Use only for complete data removal (e.g. GDPR right-to-erasure requests). All activity history, merge field data, and tag associations are permanently lost. Use unsubscribe_member instead to stop sending while preserving data for reporting. There is no undo.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). This operation is irreversible. Respects read-only and dry-run modes.

Args: list_id: The Mailchimp audience/list ID (e.g. 'abc123def4'). Obtain from list_audiences. email_address: Email address of the member to permanently delete. Must exist in the audience.

Returns: JSON with fields: status ("permanently_deleted"), email_address. Returns error if the member does not exist.

Example: delete_member(list_id="abc123", email_address="jane@co.com") -> {"status": "permanently_deleted", "email_address": "jane@co.com"}

Add or remove tags from a single member. Does not modify profile data or subscription status.

Tags are case-insensitive free-form labels. Added tags are created automatically if new; removed tags are silently ignored if not present. Idempotent. Choose the right member tool: tag_member for per-member tag changes, add_members_to_segment for bulk-adding members to a tag/segment, add_member with tags param for tagging at signup, update_member for profile/status changes, get_member_tags to check current tags.

Authenticated via API key (read scope required). Max 10 concurrent requests. Respects read-only and dry-run modes. Returns 404 error if the member does not exist.

Args: list_id: Audience/list ID (10-char alphanumeric, e.g. 'abc123def4'). Obtain from list_audiences. email_address: Email of the member. Must exist in the audience. tags_to_add: Comma-separated tag names to add (e.g. 'VIP,Returning Customer'). tags_to_remove: Comma-separated tag names to remove (e.g. 'Trial').

Returns: JSON with status ("updated"), email_address, tags array with name and status 'active'/'inactive'.

Add or update up to 500 members in a single synchronous request.

Use for bulk operations. Choose the right member tool: batch_subscribe for 2-500 members, add_member or update_member for a single member, create_batch for imports larger than 500. Side effect: members with status='pending' each receive a double opt-in confirmation email.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes.

Args: list_id: Audience/list ID (10-char alphanumeric, e.g. 'abc123def4'). Obtain from list_audiences. members_json: JSON array of members (max 500). Each requires email_address and status ('subscribed'/'unsubscribed'/'cleaned'/'pending'). Optional: merge_fields, tags. update_existing: If true (default), existing members are updated. If false, skipped as errors.

Returns: JSON with new_members, updated_members, errors array, total_created, total_updated, error_count.

Update audience-level settings: name, default sender, subject, and permission reminder.

Changes apply to newly created campaigns only; does not retroactively affect existing ones. Only provided fields are updated. Use get_audience_details to check current settings.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes.

Args: list_id: Audience/list ID (10-char alphanumeric, e.g. 'abc123def4'). Obtain from list_audiences. name: New audience display name (shown in Mailchimp UI and audience picker). from_name: Default sender name for new campaigns (e.g. 'Marketing Team'). Max 100 chars. from_email: Default sender email. Must be a verified sending domain in Mailchimp. subject: Default subject line for new campaigns (e.g. 'Monthly Update'). Max 150 chars. permission_reminder: Why subscribers receive emails (required by CAN-SPAM).

Returns: JSON with id, name, permission_reminder, campaign_defaults (from_name, from_email, subject, language).

Create a new audience (list) with required contact info, campaign defaults, and permission reminder.

Side effect: creates a billable audience under the Mailchimp plan. Mailchimp requires all contact fields (company, address, city, state, zip, country) and CAN-SPAM-compliant permission reminder text. Use update_audience to modify later, delete_audience for cleanup, or list_audiences to verify creation.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes. Returns 400 error if any required field is missing or the plan audience limit is reached.

Args: name: Audience display name shown in dashboard and audience picker (max 100 chars). from_name: Default sender name on campaigns (e.g. 'Marketing Team'). Max 100 chars. from_email: Default sender email. Must be on a verified sending domain. subject: Default subject line for new campaigns. Max 150 chars. language: Default language code (e.g. 'en', 'fr', 'es'). ISO 639-1 two-letter code. company: Legal company name displayed in email footer (required by CAN-SPAM). address1: Primary postal address line shown in email footer. city: City of the postal address. state: State or region of the postal address. zip: Postal/ZIP code. country: Two-letter ISO country code (e.g. 'US', 'FR', 'GB'). permission_reminder: Sentence shown at the bottom of every email explaining why subscribers receive it (required by CAN-SPAM). email_type_option: If true, lets subscribers choose plaintext vs. HTML emails. Default false. address2: Optional secondary postal address line. phone: Optional contact phone number shown in the footer.

Returns: JSON with id (new list_id, save for subsequent calls), name, member_count (0 at creation), date_created, subscribe_url_short.

Permanently delete an audience and all its members, segments, campaigns, and stats. Irreversible.

Side effect: removes every member of the audience and all historical data tied to it. Cannot be undone via the API. Use update_audience to rename or archive-like changes instead. Use list_audience_members to back up members first if needed.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes. Returns 404 error if list_id does not exist.

Args: list_id: Audience/list ID to delete (10-char alphanumeric, e.g. 'abc123def4'). Obtain from list_audiences. Double-check before calling — deletion is permanent.

Returns: JSON with status ('deleted') and list_id on success, or error object on failure.

Create a new email campaign in draft status, with optional segment targeting or A/B variate testing.

Typical workflow: create_campaign -> set_campaign_content (add HTML body) -> send_test_email (preview) -> send_campaign or schedule_campaign (deliver). The campaign is created in 'save' (draft) status and cannot be sent until content is set. Use replicate_campaign instead to clone an existing campaign.

For A/B testing, set campaign_type='variate' and pass variate_settings_json describing the test. Mailchimp will send variants to a sample of recipients, then auto-pick a winner based on winner_criteria and send it to the remaining audience after wait_time.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Respects read-only and dry-run modes.

Args: list_id: The audience/list ID to send to (e.g. 'abc123def4'). Obtain from list_audiences. subject_line: Subject line recipients see in their inbox. Keep under 150 chars. For variate campaigns testing subject lines, this is the default/fallback. title: Internal title for organizing in Mailchimp dashboard. Defaults to subject_line if omitted. preview_text: Preheader text shown after the subject line in inbox. Keep under 200 chars. from_name: Sender name on the email. Falls back to audience default if omitted. reply_to: Reply-to email address. Must be a verified domain. Falls back to audience default. segment_id: Saved segment ID to restrict recipients. Only members matching this segment receive the email. Obtain from list_segments. Omit to send to the full audience. campaign_type: 'regular' (default) for a standard campaign, or 'variate' for an A/B test. 'plaintext', 'rss', and 'absplit' (legacy A/B) are also accepted but rarely used. variate_settings_json: Required when campaign_type='variate'. JSON string with keys: winner_criteria ('opens' | 'clicks' | 'manual' | 'total_revenue'), test_size (10-100, percent of audience sampled), wait_time (minutes before picking winner), and one of subject_lines (list of 2-8 strings), from_names (list of 2-8), reply_to_addresses (list of 2-8), send_times (list of 2-8 ISO datetimes), or contents (list of 2-8 HTML strings). Example: '{"winner_criteria": "opens", "test_size": 20, "wait_time": 1440, "subject_lines": ["Spring Sale 20% off", "Last chance: 20% off Spring"]}'

Returns: JSON with fields: id (string, the new campaign ID for use with set_campaign_content, send_campaign, etc.), status ('save'), title, subject_line, web_id (int, for Mailchimp web UI link), type. Returns error if list_id is invalid, variate_settings_json is malformed, or variate settings violate Mailchimp constraints.

Example: create_campaign(list_id="abc123", subject_line="Spring Sale", preview_text="20% off") -> {"id": "def456", "status": "save", "type": "regular", ...}

Update settings or segment targeting of an existing campaign draft.

Use to modify subject line, sender, or segment targeting before sending. Only works on campaigns in 'save' (draft) status; returns error for sent/scheduled campaigns. Only provided fields are updated; omitted fields remain unchanged. Use set_campaign_content to change the HTML body instead.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Respects read-only and dry-run modes.

Args: campaign_id: The campaign ID to update (e.g. 'abc123def4'). Obtain from list_campaigns or create_campaign. subject_line: New subject line for the email. title: New internal title for organizing in Mailchimp. preview_text: New preview/preheader text. from_name: New sender name. reply_to: New reply-to email address. Must be a verified domain. list_id: Audience/list ID. Required when changing segment_id. Obtain from list_audiences. segment_id: Saved segment ID to target. Requires list_id to also be set. Obtain from list_segments.

Returns: JSON with fields: id, status, settings (full settings object), recipients (list_id, segment_opts).

Example: update_campaign(campaign_id="abc123", subject_line="Updated Subject") -> {"id": "abc123", "status": "save", "settings": {"subject_line": "Updated Subject", ...}}

Set the full HTML body of a campaign draft, replacing any existing content entirely.

Use after create_campaign to add the email body before sending. The campaign must be in 'save' (draft) status. Overwrites all previous content. Typical workflow: create_campaign -> set_campaign_content -> send_test_email -> send_campaign. Use update_campaign to change settings (subject, sender) instead of content.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Respects read-only and dry-run modes.

Args: campaign_id: The campaign ID (e.g. 'abc123def4'). Obtain from create_campaign or list_campaigns(status='save'). html: Complete HTML content for the email body. Must be valid HTML. Use inline CSS for email client compatibility. Mailchimp merge tags (e.g. |FNAME|, |UNSUB|) are supported. Large HTML payloads may time out; keep under 200KB.

Returns: JSON with fields: status ("content_set"), campaign_id. Returns error if campaign is not in draft status.

Example: set_campaign_content(campaign_id="abc123", html="Hello |FNAME|!") -> {"status": "content_set", "campaign_id": "abc123"}

Schedule a campaign draft for sending at a specific future time.

Use to schedule delivery of a draft campaign. The campaign must have content set via set_campaign_content and be in 'save' status. Use unschedule_campaign to cancel a scheduled send. Use send_campaign instead for immediate delivery. Use send_test_email first to preview.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Respects read-only and dry-run modes.

Args: campaign_id: The campaign ID (e.g. 'abc123def4'). Must be in 'save' status with content set. schedule_time: When to send. ISO 8601 datetime in UTC (e.g. '2025-06-15T14:00:00Z'). Must be at least 15 minutes in the future. Mailchimp rounds to the nearest quarter hour.

Returns: JSON with fields: status ("scheduled"), campaign_id, schedule_time. Returns error if campaign has no content or is not in draft status.

Example: schedule_campaign(campaign_id="abc123", schedule_time="2025-06-15T14:00:00Z") -> {"status": "scheduled", "campaign_id": "abc123", "schedule_time": "2025-06-15T14:00:00Z"}

Cancel a scheduled campaign send, returning it to draft ('save') status for editing.

Use to cancel a scheduled send before it goes out. Only works on campaigns in 'schedule' status; returns error for drafts or sent campaigns. After unscheduling, the campaign can be edited via update_campaign/set_campaign_content and rescheduled.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Respects read-only and dry-run modes.

Args: campaign_id: The campaign ID to unschedule (e.g. 'abc123def4'). Must be in 'schedule' status. Obtain from list_campaigns(status='schedule').

Returns: JSON with fields: status ("unscheduled"), campaign_id. Returns error if the campaign is not currently scheduled.

Example: unschedule_campaign(campaign_id="abc123") -> {"status": "unscheduled", "campaign_id": "abc123"}

Clone an existing campaign into a new draft with identical settings, recipients, and content.

Use to reuse a successful campaign as a starting point. Works on campaigns of any status (draft, scheduled, sent). The new campaign is created in 'save' (draft) status. Use update_campaign and set_campaign_content to modify the copy before sending. Use create_campaign instead to build from scratch.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Respects read-only and dry-run modes.

Args: campaign_id: The campaign ID to replicate (e.g. 'abc123def4'). Obtain from list_campaigns.

Returns: JSON with fields: id (string, the NEW campaign's ID, different from original), status ('save'), title (original title with " (copy)" appended), web_id (int, for Mailchimp web UI).

Example: replicate_campaign(campaign_id="abc123") -> {"id": "def456", "status": "save", "title": "Spring Sale (copy)", "web_id": 789012}

Permanently delete a campaign from the account.

Use to remove unwanted draft or scheduled campaigns. Only works on campaigns that have not been sent (status 'save' or 'schedule'). Sent campaigns cannot be deleted and will return an error. Use replicate_campaign to clone before deleting if you want to preserve settings.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). This operation is irreversible. Respects read-only and dry-run modes.

Args: campaign_id: The campaign ID to delete (e.g. 'abc123def4'). Must not be a sent campaign.

Returns: JSON with fields: status ("deleted"), campaign_id. Returns error if the campaign has already been sent.

Example: delete_campaign(campaign_id="abc123") -> {"status": "deleted", "campaign_id": "abc123"}

Send a campaign immediately to all targeted recipients. Emails begin delivering within minutes.

Use for immediate delivery. The campaign must have content set via set_campaign_content and be in 'save' (draft) status. Use schedule_campaign instead to send at a future time. Use send_test_email first to preview the email before sending to real recipients. Once sent, emails cannot be recalled.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). This operation is irreversible. Respects read-only and dry-run modes.

Args: campaign_id: The campaign ID to send (e.g. 'abc123def4'). Must be in 'save' status with content set. Obtain from create_campaign or list_campaigns(status='save').

Returns: JSON with fields: status ("sent"), campaign_id. Returns error if the campaign has no content, is already sent, or is in schedule status (use unschedule_campaign first).

Example: send_campaign(campaign_id="abc123") -> {"status": "sent", "campaign_id": "abc123"}

Send a test/preview email to specific addresses without affecting the real audience.

Side effect: sends a real email. Tests do not count against send limits and are not tracked in reports. Campaign must have content set via set_campaign_content. Recommended before send_campaign or schedule_campaign.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes.

Args: campaign_id: Campaign ID (e.g. 'abc123def4'). Must have content set. test_emails: Comma-separated emails (e.g. 'me@co.com,team@co.com'). Max 10 per request. send_type: Format: 'html' (default) or 'plaintext'.

Returns: JSON with status ("test_sent"), campaign_id, test_emails array. Error if no content set.

Cancel a campaign mid-send, stopping delivery to remaining recipients.

Only works on campaigns with status 'sending'. Already-delivered emails cannot be recalled. Irreversible. Use unschedule_campaign for scheduled (not yet sending) campaigns instead.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes.

Args: campaign_id: Campaign ID (e.g. 'abc123def4'). Must be in 'sending' status.

Returns: JSON with status ("cancelled"), campaign_id. Error if not currently sending.

Create a new segment or tag in an audience for grouping members.

Static segments (default) have manual membership via add_members_to_segment. Dynamic segments auto-update based on filter conditions. No destructive side effects. Use tag_member to apply tags to individual members instead.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes.

Args: list_id: Audience/list ID (10-char alphanumeric, e.g. 'abc123def4'). Obtain from list_audiences. name: Display name for the segment or tag. static: True (default) for manual membership; false for dynamic (requires match + conditions_json). match: Condition logic for dynamic segments: 'all' (AND) or 'any' (OR). Required when static=false. conditions_json: JSON conditions array for dynamic segments. Required when static=false.

Returns: JSON with id (new segment ID), name, member_count, type ('static'/'saved'), options.

Delete a segment or tag from an audience. Members remain in the audience.

Irreversible. Use update_segment to rename or modify conditions instead of deleting. Use list_segments to find segment IDs.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes. Returns 404 error if segment does not exist.

Args: list_id: Audience/list ID (10-char alphanumeric, e.g. 'abc123def4'). Obtain from list_audiences. segment_id: Segment/tag ID to delete (numeric string, e.g. '12345'). Obtain from list_segments.

Returns: JSON with status ("deleted"), segment_id.

Add members to a static segment or tag by email address.

Only works on static segments (tags), not dynamic segments. Members must already exist in the audience. Use tag_member for single-member tag management instead.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes.

Args: list_id: Audience/list ID (10-char alphanumeric, e.g. 'abc123def4'). Obtain from list_audiences. segment_id: Static segment/tag ID (numeric string, e.g. '12345'). Obtain from list_segments. emails: Comma-separated emails to add (e.g. 'a@co.com,b@co.com'). Must exist in audience.

Returns: JSON with total_added, total_removed (always 0), errors array.

Remove members from a static segment or tag. Members remain in the audience.

Only works on static segments (tags), not dynamic segments. Non-existent members in the email list are silently skipped. Use tag_member with tags_to_remove for single-member removal.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes. Returns 404 error if segment_id or list_id is invalid.

Args: list_id: Audience/list ID (10-char alphanumeric, e.g. 'abc123def4'). Obtain from list_audiences. segment_id: Static segment/tag ID (numeric string, e.g. '12345'). Obtain from list_segments. emails: Comma-separated email addresses to remove (e.g. 'a@co.com,b@co.com').

Returns: JSON with total_added (always 0), total_removed, errors array.

Update a segment's name or dynamic filter conditions.

Only provided fields are updated. Idempotent: re-applying the same name is safe. Cannot change a segment from static to dynamic or vice versa. Use add_members_to_segment or remove_members_from_segment to manage static segment membership instead.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes. Returns 404 error if segment_id is invalid. Providing match without conditions_json is ignored.

Args: list_id: Audience/list ID (10-char alphanumeric, e.g. 'abc123def4'). Obtain from list_audiences. segment_id: Segment ID to update (numeric string, e.g. '12345'). Obtain from list_segments. name: New display name for the segment. match: Condition match type for dynamic segments: 'all' (AND) or 'any' (OR). Must be provided together with conditions_json. conditions_json: JSON string of conditions array. Must be provided with match.

Returns: JSON with id, name, member_count, type ('static'/'saved'), options.

Retrieve full details of a specific segment including member count and filter conditions.

Use to inspect a segment's conditions or verify its type and member count. Use list_segments to browse all segments. Use list_segment_members to see individual members in the segment.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Read-only, safe to retry.

Args: list_id: The Mailchimp audience/list ID (e.g. 'abc123def4'). Obtain from list_audiences. segment_id: The segment ID (numeric string, e.g. '12345'). Obtain from list_segments.

Returns: JSON with fields: id, name, member_count (int), type ('static' for tags, 'saved' for dynamic segments), created_at (ISO 8601), updated_at (ISO 8601), options (object with match and conditions for dynamic segments, null for static segments).

Example: get_segment(list_id="abc123", segment_id="12345") -> {"id": 12345, "name": "VIP", "member_count": 150, "type": "static", ...}

List individual members belonging to a specific segment or tag.

Use to see who is in a segment. Use list_audience_members to browse all members of the full audience instead. Use get_segment to check segment metadata and member count first.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Read-only, safe to retry.

Args: list_id: The Mailchimp audience/list ID (e.g. 'abc123def4'). Obtain from list_audiences. segment_id: The segment ID (numeric string, e.g. '12345'). Obtain from list_segments. count: Number of members to return (1-1000, default 20). offset: Pagination offset. Use when total_items exceeds count.

Returns: JSON with total_items and members array. Each member: id, email_address, status, full_name, merge_fields (object with FNAME, LNAME, etc.).

Example: list_segment_members(list_id="abc123", segment_id="12345", count=50) -> {"total_items": 150, "members": [{"email_address": "jane@co.com", ...}]}

List merge fields (custom data fields) defined for an audience, including tags, types, and defaults.

Use to discover available merge fields and their tag names before adding or updating members. Default fields (FNAME, LNAME, ADDRESS, PHONE) are always present. Use create_merge_field to add custom fields. Merge field tags are used in add_member/update_member merge_fields objects and in email content as |TAG| merge tags.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Read-only, safe to retry.

Args: list_id: The Mailchimp audience/list ID (e.g. 'abc123def4'). Obtain from list_audiences. count: Number of merge fields to return (1-1000, default 50). offset: Pagination offset. Use when total_items exceeds count.

Returns: JSON with total_items and merge_fields array. Each field: merge_id (int, use with update_merge_field/delete_merge_field), tag (string, e.g. 'FNAME'), name (display name), type ('text', 'number', 'date', etc.), required (boolean), default_value, options (choices for dropdown/radio types).

Example: list_merge_fields(list_id="abc123") -> {"total_items": 6, "merge_fields": [{"merge_id": 1, "tag": "FNAME", "name": "First Name", "type": "text", ...}]}

Create a new custom merge field in an audience for storing additional member data.

Use to add custom data fields beyond the defaults (FNAME, LNAME, ADDRESS, PHONE). Once created, populate per-member via add_member/update_member using the tag name. The type cannot be changed after creation. Use list_merge_fields to check existing fields first.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Respects read-only and dry-run modes.

Args: list_id: The Mailchimp audience/list ID (e.g. 'abc123def4'). Obtain from list_audiences. name: Display name for the field (e.g. 'Company Name'). type: Field data type. Valid values: 'text', 'number', 'address', 'date', 'birthday', 'phone', 'url', 'imageurl', 'zip', 'dropdown', 'radio'. Cannot be changed after creation. tag: Short uppercase tag name (e.g. 'COMPANY'). Max 10 characters, letters and numbers only. Auto-generated from name if omitted. Used as |TAG| in email content. required: Whether the field is required when subscribing (default false). default_value: Default value for new subscribers. choices: Comma-separated choices for 'dropdown' or 'radio' types (e.g. 'Small,Medium,Large'). Required when type is 'dropdown' or 'radio'. Ignored for other types.

Returns: JSON with fields: merge_id (int, for update/delete), tag (string), name, type, required.

Example: create_merge_field(list_id="abc123", name="Company", type="text", tag="COMPANY") -> {"merge_id": 5, "tag": "COMPANY", "name": "Company", "type": "text", ...}

Update a merge field's name, default value, required flag, or dropdown/radio choices.

Only provided fields are updated; omitted fields remain unchanged. Choices are replaced entirely (old choices are lost). Do not use to change field type or tag (immutable after creation); use delete_merge_field then create_merge_field instead.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes. Returns 404 error if merge_id is invalid or does not exist.

Args: list_id: Audience/list ID (10-char alphanumeric, e.g. 'abc123def4'). Obtain from list_audiences. merge_id: Merge field ID (numeric string, e.g. '5'). Obtain from list_merge_fields. name: New display name for the field. required: Whether the field is required when subscribing. default_value: New default value for new subscribers. choices: Comma-separated choices for dropdown/radio types (e.g. 'Small,Medium,Large'). Replaces all existing choices. Ignored for other field types.

Returns: JSON with merge_id, tag, name, type, required.

Delete a custom merge field and all its stored data from an audience.

Use only when you no longer need the field. All data stored in this field for every member is permanently lost. Default fields (FNAME, LNAME, ADDRESS, PHONE) cannot be deleted and will return an error. Use list_merge_fields to find merge_id values.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). This operation is irreversible. Respects read-only and dry-run modes.

Args: list_id: The Mailchimp audience/list ID (e.g. 'abc123def4'). Obtain from list_audiences. merge_id: The merge field ID to delete (numeric string). Obtain from list_merge_fields. Cannot be a default field.

Returns: JSON with fields: status ("deleted"), merge_id. Returns error if the field is a default field or does not exist.

Example: delete_merge_field(list_id="abc123", merge_id="5") -> {"status": "deleted", "merge_id": "5"}

List interest categories (group containers) for an audience, showing titles and form types.

Use to discover category IDs, then list_interests for options within each. Use create_interest_category to add new categories.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry.

Args: list_id: Audience/list ID (10-char alphanumeric, e.g. 'abc123def4'). Obtain from list_audiences. count: Categories to return (1-1000, default 50). offset: Pagination offset. Use when total_items exceeds count.

Returns: JSON with total_items and categories array. Each: id, title, type ('checkboxes'/'dropdown'/ 'radio'/'hidden'), list_id.

Create a new interest category (group container) in an audience for organizing subscriber preferences.

Use to create a container for interest options. Typical workflow: create_interest_category -> create_interest (add options within the category). The type controls how subscribers interact with it on signup forms. Use list_interest_categories to check existing categories first.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Respects read-only and dry-run modes.

Args: list_id: The Mailchimp audience/list ID (e.g. 'abc123def4'). Obtain from list_audiences. title: Display title for the category (e.g. 'Preferred Topics'). Must be unique within the audience. type: How the category appears on signup forms. Valid values: 'checkboxes' (subscribers can select multiple), 'dropdown' (single select), 'radio' (single select), 'hidden' (not shown on forms, managed via API only).

Returns: JSON with fields: id (string, use with create_interest, list_interests, delete_interest_category), title, type, list_id.

Example: create_interest_category(list_id="abc123", title="Newsletter Preferences", type="checkboxes") -> {"id": "cat456", "title": "Newsletter Preferences", "type": "checkboxes", ...}

List interest options within a category, with subscriber counts per option.

Use after list_interest_categories to see individual options (e.g. "Tech", "Sports"). Interest IDs are needed when setting member preferences via add_member/update_member. Do not use to manage member preferences directly; set interests per-member via the API instead.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry. Returns 404 error if category_id is invalid.

Args: list_id: Audience/list ID (10-char alphanumeric, e.g. 'abc123def4'). Obtain from list_audiences. category_id: Interest category ID. Obtain from list_interest_categories. count: Number of interests to return (1-1000, default 50). offset: Pagination offset. Use when total_items exceeds count.

Returns: JSON with total_items and interests array. Each interest: id, name, subscriber_count, display_order.

Create a new interest option within an interest category (e.g. add "Tech" to a "Topics" category).

Use after create_interest_category to add selectable options. Each option becomes available on signup forms (unless category type is 'hidden'). Use list_interests to check existing options. Use delete_interest to remove an option.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Respects read-only and dry-run modes.

Args: list_id: The Mailchimp audience/list ID (e.g. 'abc123def4'). Obtain from list_audiences. category_id: The interest category ID. Obtain from list_interest_categories or create_interest_category. name: Display name for the interest option (e.g. 'Tech', 'Sports'). Must be unique within the category.

Returns: JSON with fields: id (string, use with delete_interest), name, subscriber_count (int, starts at 0).

Example: create_interest(list_id="abc123", category_id="cat456", name="Technology") -> {"id": "int789", "name": "Technology", "subscriber_count": 0}

Delete an interest category and all its interest options at once.

Removes the entire category with all its options. All subscriber associations with interests in this category are removed. Subscribers themselves are not affected. Use delete_interest instead to remove a single option while keeping the category. Use list_interest_categories to find category IDs.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). This operation is irreversible. Respects read-only and dry-run modes.

Args: list_id: The Mailchimp audience/list ID (e.g. 'abc123def4'). Obtain from list_audiences. category_id: The interest category ID to delete. Obtain from list_interest_categories.

Returns: JSON with fields: status ("deleted"), category_id. Returns error if category does not exist.

Example: delete_interest_category(list_id="abc123", category_id="cat456") -> {"status": "deleted", "category_id": "cat456"}

Delete a single interest option from a category, keeping the category and other options intact.

Use to remove one specific option. The interest and its subscriber associations are removed. Use delete_interest_category instead to remove the entire category with all options at once.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). This operation is irreversible. Respects read-only and dry-run modes.

Args: list_id: The Mailchimp audience/list ID (e.g. 'abc123def4'). Obtain from list_audiences. category_id: The interest category ID. Obtain from list_interest_categories. interest_id: The interest option ID to delete. Obtain from list_interests.

Returns: JSON with fields: status ("deleted"), interest_id. Returns error if interest does not exist.

Example: delete_interest(list_id="abc123", category_id="cat456", interest_id="int789") -> {"status": "deleted", "interest_id": "int789"}

List webhooks configured for an audience, showing callback URLs, events, and source filters.

Use to audit integrations or find webhook IDs before deleting via delete_webhook. Do not use to check webhook delivery history; Mailchimp does not expose delivery logs via the API.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry.

Args: list_id: Audience/list ID (10-char alphanumeric, e.g. 'abc123def4'). Obtain from list_audiences.

Returns: JSON with total_items and webhooks array. Each webhook: id, url, events (boolean flags: subscribe, unsubscribe, profile, cleaned, upemail, campaign), sources (boolean flags: user, admin, api), list_id.

Create a webhook that sends HTTP POST notifications to an external URL on audience events.

Side effect: Mailchimp sends a validation GET request during creation; the URL must be publicly accessible and return HTTP 200. All events and sources enabled by default if omitted. Do not use for polling or batch data retrieval; use list_audience_members or campaign reports instead.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes.

Args: list_id: Audience/list ID (10-char alphanumeric, e.g. 'abc123def4'). Obtain from list_audiences. url: Public HTTPS URL to receive POST requests. Must return HTTP 200 on GET validation. events: Comma-separated events: 'subscribe', 'unsubscribe', 'profile', 'cleaned', 'upemail', 'campaign'. All enabled if omitted. sources: Comma-separated sources: 'user', 'admin', 'api'. All enabled if omitted.

Returns: JSON with id, url, events (boolean flags), sources (boolean flags). Error if URL validation fails.

Delete a webhook, immediately stopping event notifications to its URL.

Irreversible. Do not use when you want to temporarily pause notifications; webhooks have no pause mechanism. Use create_webhook to set up a replacement afterward.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes. Returns 404 error if webhook_id or list_id is invalid.

Args: list_id: Audience/list ID (10-char alphanumeric, e.g. 'abc123def4'). Obtain from list_audiences. webhook_id: The webhook ID to delete. Obtain from list_webhooks.

Returns: JSON with status ("deleted"), webhook_id.

Retrieve per-recipient activity timeline for a sent campaign (opens, clicks, bounces).

Use get_open_details for open data only. Use get_campaign_report for aggregate totals. Use get_campaign_recipients for delivery status only.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry.

Args: campaign_id: Campaign ID (e.g. 'abc123def4'). Must be a sent campaign. count: Recipient records to return (1-1000, default 20). offset: Pagination offset. Use when total_items exceeds count.

Returns: JSON with total_items and emails array. Each: email_address, activity array with action ('open'/'click'/'bounce'), timestamp, url (clicks only).

Retrieve per-recipient open data for a sent campaign (who opened, when, how many times).

Use get_campaign_report for aggregate open rates. Use get_email_activity for all activity types combined.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry.

Args: campaign_id: Campaign ID (e.g. 'abc123def4'). Must be a sent campaign. count: Records to return (1-1000, default 20). offset: Pagination offset. Use when total_items exceeds count.

Returns: JSON with total_items and members array. Each: email_address, opens_count, opens array with timestamps.

Retrieve the delivery roster for a sent campaign showing each recipient's delivery status and open count.

Use to verify who received a campaign and whether they opened it. Use get_email_activity for detailed per-recipient timelines (clicks, bounces with timestamps). Use get_campaign_report for aggregate metrics. Only works for sent campaigns; returns error for drafts or scheduled.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Read-only, safe to retry.

Args: campaign_id: The Mailchimp campaign ID (e.g. 'abc123def4'). Must be a sent campaign. count: Number of recipients to return (1-1000, default 20). offset: Pagination offset. Use when total_items exceeds count.

Returns: JSON with total_items (int) and recipients array. Each recipient: email_address, status ('sent', 'hard', 'soft'), open_count (int), last_open (ISO 8601 or null).

Example: get_campaign_recipients(campaign_id="abc123", count=100) -> {"total_items": 5000, "recipients": [{"email_address": "jane@co.com", "status": "sent", "open_count": 3, ...}]}

Retrieve members who unsubscribed from a specific sent campaign, with reasons.

Use get_campaign_report for aggregate unsubscribe count instead.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry. Returns 404 error if campaign_id is invalid. Returns empty array for unsent campaigns.

Args: campaign_id: Campaign ID (e.g. 'abc123def4'). Must be a sent campaign. count: Records to return (1-1000, default 20). offset: Pagination offset. Use when total_items exceeds count.

Returns: JSON with total_items and unsubscribes array. Each: email_address, reason (string or null), timestamp.

Retrieve campaign performance broken down by recipient email domain (gmail.com, outlook.com, etc.).

Use to identify deliverability issues with specific providers or compare engagement across domains. Use get_campaign_report for overall aggregate metrics. Only works for sent campaigns.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Read-only, safe to retry.

Args: campaign_id: The Mailchimp campaign ID (e.g. 'abc123def4'). Must be a sent campaign.

Returns: JSON with total_items and domains array. Each domain: domain (string, e.g. 'gmail.com'), emails_sent (int), bounces (int), opens (int), clicks (int), unsubs (int).

Example: get_domain_performance(campaign_id="abc123") -> {"total_items": 15, "domains": [{"domain": "gmail.com", "emails_sent": 2000, "opens": 500, "clicks": 80, ...}]}

Retrieve Mailchimp's automated post-send feedback on a campaign (subject line, content, engagement tips).

Use to surface algorithmic suggestions Mailchimp makes after looking at how a campaign performed (e.g. 'your open rate is below industry average, try shorter subject lines'). Use get_campaign_report for raw metrics. Only works for sent campaigns.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry. Returns 404 error if campaign_id is invalid. Returns an empty advice array if Mailchimp has no suggestions for the campaign.

Args: campaign_id: The Mailchimp campaign ID (e.g. 'abc123def4'). Must be a sent campaign.

Returns: JSON with total_items and advice array. Each entry: type ('positive' | 'negative' | 'neutral'), message (string, the advice text).

Retrieve geographic open data for a sent campaign, broken down by country and region.

Use to map where opens happened — useful for region-targeted follow-ups, timezone-aware sending, or audit reports. Aggregated from IP geolocation at open time. Use get_domain_performance for per-provider stats instead. Only works for sent campaigns.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry.

Args: campaign_id: The Mailchimp campaign ID (e.g. 'abc123def4'). Must be a sent campaign. count: Number of locations to return (1-1000, default 20). offset: Pagination offset. Use when total_items exceeds count.

Returns: JSON with total_items and locations array. Each entry: country_code (ISO 2-letter, e.g. 'US'), region (string, state/province name or code), region_name (full name), opens (int, opens from that region).

Retrieve social sharing stats for a campaign's eepurl (Mailchimp's short-URL share link).

Use to measure how much the campaign was shared on Twitter/Facebook/etc. via the 'Share this' link Mailchimp generates. Use get_campaign_click_details for in-email link clicks instead. Only works for sent campaigns where eepurl tracking is enabled.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry.

Args: campaign_id: The Mailchimp campaign ID (e.g. 'abc123def4'). Must be a sent campaign.

Returns: JSON with eepurl (the short URL), twitter (object with statuses, first_status, last_status, replies, impressions, retweets), facebook (object with likes, recipient_likes, unique_likes), referrers array (list of {referrer, clicks, first_click, last_click}).

Retrieve e-commerce product activity for a campaign showing revenue per product.

Requires an active e-commerce integration; returns total_items: 0 if none is connected. Use list_ecommerce_stores to verify status. Only works for sent campaigns.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry. Returns 404 error if campaign_id is invalid.

Args: campaign_id: Campaign ID (e.g. 'abc123def4'). Must be a sent campaign. count: Products to return (1-1000, default 20). offset: Pagination offset. Use when total_items exceeds count.

Returns: JSON with total_items and products array. Each: title, sku, image_url, total_revenue (float, store currency), total_purchased.

Retrieve child report data for A/B test, variate, or RSS campaign sub-items.

Read-only, no side effects. Returns empty data for regular campaigns; use get_campaign_report instead. Check campaign type with get_campaign_details first ('absplit', 'variate', 'rss').

Authenticated via API key. Max 10 concurrent requests. Safe to retry.

Args: campaign_id: Campaign ID (e.g. 'abc123def4'). Should be type 'absplit', 'variate', or 'rss'. Obtain from list_campaigns.

Returns: JSON with sub-reports. Format varies: A/B tests include per-variant opens, clicks, winner; RSS includes per-item send stats with dates.

Retrieve a member's email interaction history (opens, clicks, bounces across all campaigns).

Shows email actions only. Use get_member_events for custom API-triggered events. Use get_member_tags for tag data. Use search_members first to find which audience a member belongs to.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry. Returns 404 error if the member does not exist in the audience.

Args: list_id: Audience/list ID (10-char alphanumeric, e.g. 'abc123def4'). Obtain from list_audiences. email_address: Email of the member. Must exist in the audience. count: Number of activity records to return (1-1000, default 20).

Returns: JSON with email_address and activity array. Each: action ('open'/'click'/'bounce'), timestamp, campaign_id, title.

Retrieve all tags currently assigned to a specific member.

Use to see which tags a member has before modifying them. Use tag_member to add or remove tags. Use list_segments to see all available tags/segments in the audience.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Read-only, safe to retry.

Args: list_id: The Mailchimp audience/list ID (e.g. 'abc123def4'). Obtain from list_audiences. email_address: Email address of the member. Must exist in the audience. count: Number of tags to return (1-1000, default 50).

Returns: JSON with email_address, total_items (int), and tags array. Each tag: id (int), name (string), date_added (ISO 8601).

Example: get_member_tags(list_id="abc123", email_address="jane@co.com") -> {"email_address": "jane@co.com", "total_items": 3, "tags": [{"name": "VIP", "date_added": "2025-01-15T10:00:00Z", ...}]}

Retrieve custom API-triggered events for a specific member (e.g. "purchased", "signed_up").

Use to view events sent to Mailchimp via the Events API. These are custom application events, not email interactions (opens, clicks); use get_member_activity for email engagement data. Returns empty if no custom events have been recorded for the member.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Read-only, safe to retry.

Args: list_id: The Mailchimp audience/list ID (e.g. 'abc123def4'). Obtain from list_audiences. email_address: Email address of the member. Must exist in the audience. count: Number of events to return (1-1000, default 20).

Returns: JSON with email_address, total_items (int), and events array. Each event: name (string, event name), occurred_at (ISO 8601), properties (object, custom key-value data or null).

Example: get_member_events(list_id="abc123", email_address="jane@co.com") -> {"email_address": "jane@co.com", "total_items": 5, "events": [{"name": "purchased", "occurred_at": "2025-06-01T10:00:00Z", "properties": {"product": "T-Shirt"}}]}

List CRM-style notes attached to a member by team members (not visible to the contact).

Notes are internal annotations like "Called about pricing" or "VIP customer". They are not sent to the contact and do not affect deliverability. Use add_member_note to create one, update_member_note to edit, delete_member_note to remove.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry. Returns 404 error if the member does not exist.

Args: list_id: Audience/list ID (10-char alphanumeric, e.g. 'abc123def4'). Obtain from list_audiences. email_address: Email of the member whose notes to list. Must exist in the audience. count: Number of notes to return (1-1000, default 20). offset: Pagination offset. Use when total_items exceeds count.

Returns: JSON with email_address, total_items, and notes array. Each note: id (use as note_id), note (string, the text), created_at, created_by, updated_at.

Add a CRM-style internal note to a member. Not sent to the contact.

Useful for sales/support context, e.g. "Asked for discount on annual plan", "Out of office until June 1st". Use update_member_note to edit an existing note instead of adding another.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes. Returns 404 if the member does not exist; returns 400 if note text exceeds 1000 chars.

Args: list_id: Audience/list ID. Obtain from list_audiences. email_address: Email of the member to attach the note to. Must exist in the audience. note: Note text (max 1000 chars). Plain text; markdown is not rendered in the Mailchimp UI.

Returns: JSON with id (use as note_id), email_address, note, created_at, created_by.

Update the text of an existing member note. Replaces the entire note body.

Use list_member_notes to find note_ids. Use add_member_note instead to create a new note rather than overwriting; use delete_member_note to remove a note.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes. Returns 404 if the note or member does not exist.

Args: list_id: Audience/list ID. Obtain from list_audiences. email_address: Email of the member who owns the note. note_id: Note ID to update. Obtain from list_member_notes. note: New note text (max 1000 chars). Replaces the previous text entirely.

Returns: JSON with id, email_address, note (new value), updated_at.

Permanently delete a note attached to a member. Cannot be undone.

Use list_member_notes to find note_ids before calling. Does not affect the member itself, only the note.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes. Returns 404 if the note or member does not exist.

Args: list_id: Audience/list ID. Obtain from list_audiences. email_address: Email of the member who owns the note. note_id: Note ID to delete. Obtain from list_member_notes.

Returns: JSON with status ('deleted'), email_address, note_id on success.

List individual emails within an automation workflow with sequence, delays, and send counts.

Returns all emails regardless of status. Do not confuse with get_email_activity (campaign engagement). Use get_automation_email_queue to see queued subscribers for a specific email.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry.

Args: automation_id: Automation workflow ID (e.g. 'auto123'). Obtain from list_automations.

Returns: JSON with total_items and emails array. Each email: id, position (sequence starting at 1), status ('sending'/'paused'/'draft'), subject_line, title, emails_sent, send_time, delay.

Retrieve the queue of subscribers about to receive a specific automation email, with scheduled send times.

Use to see who is waiting to receive a particular email in a workflow. Use get_automation_emails first to find email_id values within the workflow.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Read-only, safe to retry.

Args: automation_id: The automation workflow ID (e.g. 'auto123'). Obtain from list_automations. email_id: The specific email ID within the automation. Obtain from get_automation_emails.

Returns: JSON with total_items (int) and queue array. Each entry: email_address (string), next_send (ISO 8601 timestamp of scheduled send).

Example: get_automation_email_queue(automation_id="auto123", email_id="email456") -> {"total_items": 12, "queue": [{"email_address": "jane@co.com", "next_send": "2025-06-02T10:00:00Z"}]}

Pause an automation workflow, stopping delivery while preserving the queue.

Queued subscribers resume when restarted via start_automation. New subscribers still enter the queue but do not receive emails while paused. Reversible.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes.

Args: automation_id: Automation workflow ID (e.g. 'auto123'). Obtain from list_automations.

Returns: JSON with status ("paused"), automation_id. Error if already paused or in draft status.

Start or resume all emails in an automation workflow, activating delivery to queued subscribers.

Use to activate a new automation or resume a paused one. Queued subscribers begin receiving emails. Use pause_automation to temporarily stop. Use list_automations to check current status.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Respects read-only and dry-run modes.

Args: automation_id: The automation workflow ID (e.g. 'auto123'). Obtain from list_automations.

Returns: JSON with fields: status ("started"), automation_id. Returns error if automation is already sending or is in draft status.

Example: start_automation(automation_id="auto123") -> {"status": "started", "automation_id": "auto123"}

List landing pages with publication status, URLs, and associated audiences.

Landing pages are standalone web pages, not emails. Use get_landing_page for full details. Do not use to find email campaigns; use list_campaigns instead.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry.

Args: count: Landing pages to return (1-1000, default 20). offset: Pagination offset. Use when total_items exceeds count.

Returns: JSON with total_items and landing_pages array. Each: id, name, title, status ('published'/'unpublished'/'draft'), url (null if not published), published_at, created_at, list_id.

Retrieve full details of a landing page including description and tracking settings.

Use list_landing_pages to browse all pages and discover page IDs.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry. Returns 404 error if page_id is invalid.

Args: page_id: Landing page ID (alphanumeric string). Obtain from list_landing_pages.

Returns: JSON with id, name, title, description, status ('published'/'unpublished'/'draft'), url, published_at, created_at, updated_at, list_id, tracking.

Create a new landing page in draft status from a template, optionally linked to a store.

The page is created unpublished. Use update_landing_page to edit settings or publish_landing_page to make it live at its public URL. Use list_landing_pages or get_landing_page to inspect existing pages.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes. Returns 400 error if template_id is invalid or list_id does not exist.

Args: name: Internal name for the page (shown in the Mailchimp dashboard, not to visitors). title: Browser tab title (shown in the page's HTML ). list_id: Audience ID this page collects signups for (e.g. 'abc123def4'). Obtain from list_audiences. template_id: Template ID to base the page on. Obtain from list_templates. store_id: Optional e-commerce store ID to link the page to. Obtain from list_ecommerce_stores. description: Optional internal description. tracking_opens: Track view-opens analytics. Default true. tracking_clicks: Track link clicks analytics. Default true.

Returns: JSON with id (use as page_id for subsequent calls), name, title, status ('unpublished'), url (null until published), created_at, list_id.

Update settings of an existing landing page. Only provided fields are changed.

Cannot change list_id or template after creation; create a new page instead. Use publish_landing_page / unpublish_landing_page to change live status. Use get_landing_page to inspect current settings before updating.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes. Returns 404 error if page_id is invalid.

Args: page_id: Landing page ID. Obtain from list_landing_pages. name: New internal name. title: New browser tab title. description: New internal description. tracking_opens: Toggle open tracking on/off. tracking_clicks: Toggle click tracking on/off.

Returns: JSON with id, name, title, status, url, updated_at, list_id.

Permanently delete a landing page. Cannot be undone.

Side effect: the page becomes inaccessible at its public URL immediately. Past visit analytics remain in Mailchimp's reports area but the page itself is gone. Use unpublish_landing_page if you only want to take it offline temporarily.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes. Returns 404 error if page_id is invalid.

Args: page_id: Landing page ID to delete. Obtain from list_landing_pages.

Returns: JSON with status ('deleted') and page_id on success.

Publish a landing page, making it live at its public URL.

Idempotent on already-published pages. Use unpublish_landing_page to take a page offline. Use get_landing_page to confirm the live URL after publishing.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes. Returns 400 if the page is missing required content; returns 404 if page_id is invalid.

Args: page_id: Landing page ID to publish. Obtain from list_landing_pages.

Returns: JSON with status ('published') and page_id on success.

Take a published landing page offline. The public URL stops serving the page.

Reversible — re-publish with publish_landing_page. Use delete_landing_page for permanent removal instead.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes. Returns 404 error if page_id is invalid.

Args: page_id: Landing page ID to unpublish. Obtain from list_landing_pages.

Returns: JSON with status ('unpublished') and page_id on success.

List connected e-commerce stores (Shopify, WooCommerce, etc.) with platform and currency info.

Use to discover store IDs for list_store_orders, list_store_products, list_store_customers. Also verifies integration status before get_ecommerce_product_activity. Returns total_items: 0 if no integration is configured.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry.

Returns: JSON with total_items and stores array. Each: id (use as store_id), list_id, name, platform, domain, currency_code (ISO 4217), money_format, created_at.

List orders from a connected e-commerce store with totals and fulfillment status.

Requires an active integration. Use list_store_customers for customer-level aggregates instead.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry.

Args: store_id: E-commerce store ID (alphanumeric string). Obtain from list_ecommerce_stores. count: Orders to return (1-1000, default 20). offset: Pagination offset. Use when total_items exceeds count.

Returns: JSON with total_items and orders array. Each: id, customer (email), order_total (float), currency_code (ISO 4217), financial_status, fulfillment_status, processed_at_foreign, lines_count.

List products from a connected e-commerce store with titles, URLs, and variant counts.

Use to browse the product catalog synced to Mailchimp. Useful for verifying sync status or finding product data for campaign content. Use list_ecommerce_stores to find store IDs. Use get_ecommerce_product_activity for campaign-level product revenue data.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Read-only, safe to retry.

Args: store_id: The e-commerce store ID. Obtain from list_ecommerce_stores. count: Number of products to return (1-1000, default 20). offset: Pagination offset. Use when total_items exceeds count.

Returns: JSON with total_items and products array. Each product: id (string), title, url (product page link), vendor (string), image_url (string or null), variants_count (int). Returns total_items: 0 if no integration is configured.

Example: list_store_products(store_id="store123", count=50) -> {"total_items": 200, "products": [{"id": "prod_123", "title": "Blue T-Shirt", "variants_count": 3, ...}]}

List customers from a connected e-commerce store with order counts, total spend, and opt-in status.

Use to analyze customer purchasing behavior or identify high-value customers. Requires an active e-commerce integration. Use list_ecommerce_stores to find store IDs. Use list_store_orders for per-order detail instead of customer-level aggregates.

Authenticated via API key. Subject to Mailchimp API rate limits (max 10 concurrent requests). Read-only, safe to retry.

Args: store_id: The e-commerce store ID. Obtain from list_ecommerce_stores. count: Number of customers to return (1-1000, default 20). offset: Pagination offset. Use when total_items exceeds count.

Returns: JSON with total_items and customers array. Each customer: id (string), email_address, first_name, last_name, orders_count (int), total_spent (float, in store currency), opt_in_status (boolean), created_at (ISO 8601).

Example: list_store_customers(store_id="store123", count=50) -> {"total_items": 500, "customers": [{"email_address": "jane@co.com", "orders_count": 5, "total_spent": 299.95, ...}]}

List carts for a store, including abandoned ones, with customer and total info.

Carts in Mailchimp typically represent in-progress purchases synced from a connected storefront. Use for abandoned-cart workflows: filter by recent created_at, segment by cart total, then trigger a recovery automation. Use get_store_cart for a single cart with line items. Use list_store_orders for completed purchases.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry. Returns 404 if store_id is invalid.

Args: store_id: E-commerce store ID. Obtain from list_ecommerce_stores. count: Number of carts to return (1-1000, default 20). offset: Pagination offset.

Returns: JSON with store_id, total_items, and carts array. Each cart: id, customer (object with id, email_address, opt_in_status), currency_code, order_total, tax_total, checkout_url, created_at, updated_at.

Retrieve a single cart with its full line items, customer, and total breakdown.

Use to inspect what's in an abandoned cart before triggering a recovery email. Use list_store_carts to browse and discover cart_ids.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry. Returns 404 if store_id or cart_id is invalid.

Args: store_id: E-commerce store ID. Obtain from list_ecommerce_stores. cart_id: Cart ID. Obtain from list_store_carts.

Returns: JSON with id, customer, currency_code, order_total, tax_total, checkout_url, lines (array of {id, product_id, product_variant_id, quantity, price}), created_at, updated_at.

Create a cart in a store with line items and a customer reference. Used to push abandoned-cart data from an external system into Mailchimp for recovery workflows.

cart_id is client-supplied (Mailchimp does not auto-generate it). The customer must already exist in the store; create them via Mailchimp's customer endpoints first if not. Use update_store_cart to modify after creation.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes.

Args: store_id: E-commerce store ID. cart_id: Client-supplied unique ID for the new cart (e.g. 'cart_42'). customer_id: ID of an existing customer in the store. currency_code: ISO 4217 currency code (e.g. 'USD', 'EUR'). order_total: Total order amount (line items + tax + shipping if any). lines_json: JSON string with the cart line items array. Example: '[{"id": "line_1", "product_id": "p_1", "product_variant_id": "p_1_red", "quantity": 2, "price": 19.99}]' checkout_url: Optional URL to resume the cart (used in recovery emails). tax_total: Optional tax portion of order_total.

Returns: JSON with id, customer, currency_code, order_total, checkout_url, created_at.

Update an existing cart's totals, currency, checkout URL, or line items.

Only provided fields are changed. To replace line items, pass a full lines_json array (partial line updates are not supported by this tool — use the Mailchimp UI or REST API directly for line-level edits).

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes. Returns 404 if store_id or cart_id is invalid.

Args: store_id: E-commerce store ID. cart_id: Existing cart ID. order_total: New order total. tax_total: New tax portion. checkout_url: New checkout URL. currency_code: New ISO 4217 currency code. lines_json: JSON string with a replacement line items array.

Returns: JSON with id, order_total, tax_total, checkout_url, currency_code, updated_at.

Permanently delete a cart from a store. Cannot be undone.

Use when an external system reports the cart has been completed (converted to order) or expired. Does not affect related orders or customer records.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes. Returns 404 if store_id or cart_id is invalid.

Args: store_id: E-commerce store ID. cart_id: Cart ID to delete.

Returns: JSON with status ('deleted'), store_id, cart_id on success.

List discount/promo rules configured for a store (fixed amount, percentage, free shipping).

A promo rule defines the discount mechanic (e.g. '20% off entire order'). Codes that customers redeem are attached to rules via list_promo_codes / create_promo_code.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry.

Args: store_id: E-commerce store ID. Obtain from list_ecommerce_stores. count: Number of rules to return (1-1000, default 20). offset: Pagination offset.

Returns: JSON with store_id, total_items, and promo_rules array. Each rule: id, title, description, amount, type ('fixed' | 'percentage'), target ('per_item' | 'total' | 'shipping'), enabled (bool), starts_at, ends_at, created_at, updated_at.

Retrieve a single promo rule by ID with its full configuration.

Use to inspect a rule's current settings before updating, or to confirm a rule exists before attaching new codes. Use list_promo_rules to browse and discover IDs.

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry. Returns 404 if store_id or promo_rule_id is invalid.

Args: store_id: E-commerce store ID. promo_rule_id: Rule ID to inspect.

Returns: JSON with id, title, description, amount, type, target, enabled, starts_at, ends_at, created_at, updated_at.

Create a promo rule (discount mechanic) in a store. Attach codes to it afterwards via create_promo_code.

promo_rule_id is client-supplied. Common patterns: amount=20 + type='percentage' + target='total' for '20% off entire order'; amount=5 + type='fixed' + target='shipping' for '$5 off shipping'.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes.

Args: store_id: E-commerce store ID. promo_rule_id: Client-supplied unique ID for the rule. description: Internal description shown in Mailchimp UI. amount: Discount value. For type='percentage', a value between 0 and 100. type: 'fixed' for absolute amount or 'percentage' for percent off. target: 'per_item' (each item), 'total' (whole order), or 'shipping' (shipping cost only). enabled: Whether the rule is active. Default true. title: Optional public title. starts_at: Optional ISO 8601 start datetime (rule inactive before this). ends_at: Optional ISO 8601 end datetime (rule inactive after this).

Returns: JSON with id, title, description, amount, type, target, enabled, created_at.

Update an existing promo rule. Only provided fields are changed.

Useful to toggle a rule on/off (enabled), extend an end date, or adjust the discount amount mid-campaign. Use list_promo_rules to discover promo_rule_ids.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes. Returns 404 if store_id or promo_rule_id is invalid.

Args: store_id: E-commerce store ID. promo_rule_id: Existing rule ID. description: New internal description. amount: New discount amount. type: New type ('fixed' or 'percentage'). target: New target ('per_item', 'total', or 'shipping'). enabled: Toggle the rule on/off. title: New public title. starts_at: New start datetime (ISO 8601). ends_at: New end datetime (ISO 8601).

Returns: JSON with id, title, description, amount, type, target, enabled, updated_at.

Permanently delete a promo rule and all its associated promo codes. Irreversible.

Side effect: every promo code attached to this rule is also deleted and stops working at checkout. Use update_promo_rule with enabled=false to disable a rule without deleting its codes.

Authenticated via API key. Max 10 concurrent requests. Respects read-only and dry-run modes. Returns 404 if store_id or promo_rule_id is invalid.

Args: store_id: E-commerce store ID. promo_rule_id: Rule ID to delete.

Returns: JSON with status ('deleted'), store_id, promo_rule_id on success.

List the redeemable codes attached to a promo rule (e.g. 'SUMMER20', 'VIPONLY').

Codes are what customers type at checkout. They redeem the discount defined by the rule. A single rule can have many codes (e.g. one per customer segment).

Authenticated via API key. Max 10 concurrent requests. Read-only, safe to retry.

Args: store_id: E-commerce store ID. promo_rule_id: Rule ID. Obtain from list_promo_rules. count: Number of codes to return (1-1000, default 20). offset: Pagination offset.

Returns: JSON with store_id, promo_rule_id, total_items, and promo_codes array. Each code: id, code (the string customers type), redemption_url, usage_count, enabled, created_at, updated_at.