# MailWizz MCP > MailWizz MCP Server connects your AI agent directly to your email marketing platform's API. It lets you manage subscriber lists, track campaign statuses, and update user records—all from natural language prompts in your IDE or client. You don't need to open the web dashboard; just tell your agent what needs doing. ## Overview - **Category:** developer-tools - **Price:** Free - **Tags:** email-campaigns, subscriber-management, self-hosted, audience-segmentation, campaign-management, list-management ## Description Listen up. This MCP Server connects your AI agent right into MailWizz's API. It lets you manage your entire email marketing operation—your lists, your campaigns, your subscribers—all through natural language prompts in your IDE or client. You don't gotta open the web dashboard; you just tell your agent what needs doing. **Managing Campaigns:** You can see every campaign running by invoking `list_email_campaigns`, which returns an array of all campaigns managed in your account. If you wanna dig deep on a single send, use `get_campaign_details`. It pulls detailed metadata and the current status for one specific email marketing campaign. When a campaign's delivery needs to stop immediately, you can programmatically pause it using `pause_email_campaign`, which suspends its automated sending process. **Handling Subscriber Lists:** To see what collections of people you got, run `list_subscriber_collections`. That gives you the names and IDs for every subscriber list in your account. If you need to know the structural details—like what fields it expects or its unique ID—use `get_list_details` on a specific collection. To get a full roster of who's actually signed up, run `list_list_subscribers`, specifying which list you want to check. This action returns every single subscriber currently inside that chosen list. **Modifying Users and Contacts:** You can manage the actual people in your lists from the command line. If a user signs up, use `add_subscriber_to_list`; you gotta pass it both the list's UID and all of the subscriber's required data fields for that addition to stick. When someone leaves or messes up their info, you can clean things up with `delete_list_subscriber`, which removes an existing user using their unique identifiers. If a contact updates their phone number or email but stays on the list, use `update_list_subscriber` to modify that person's details within any defined list. This whole setup gives your agent full control over the lifecycle of your mailing lists and sends. You tell it to add users, delete them, update them, pull campaign status checks, or get a complete dump of who's signed up in every collection. It's all about making sure your AI client handles the complexity behind the scenes so you don't gotta touch another dashboard. ## Tools ### add_subscriber_to_list Adds a new user to a specific list, requiring the list's UID and the subscriber's data fields. ### list_email_campaigns Returns an array of all email marketing campaigns managed in your MailWizz account. ### delete_list_subscriber Removes an existing subscriber from a specified list using their unique identifiers. ### get_campaign_details Retrieves detailed metadata and status information for one specific email marketing campaign. ### get_list_details Gets comprehensive details about a particular subscriber list, including its structure and unique ID. ### list_list_subscribers Lists every subscriber currently contained within a specified list collection. ### list_subscriber_collections Retrieves the names and IDs for all subscriber lists (collections) in your account. ### pause_email_campaign Stops a running email campaign immediately, suspending its automated delivery process. ### update_list_subscriber Modifies the contact details of an existing subscriber within any defined list. ## Prompt Examples **Prompt:** ``` List all active email campaigns in MailWizz. ``` **Response:** ``` I've retrieved your campaigns. You have 5 campaigns, including 'Product Launch Q4 (UID: sb123abc)', 'Monthly Update', and 'Re-engagement Flow'. Which one would you like to see metadata for? ``` **Prompt:** ``` Add 'user@example.com' to my 'Main Leads' list (UID: 'lz987xyz'). ``` **Response:** ``` Successfully added user@example.com to the list Main Leads. The subscriber UID is 'sub-abc-123' and they are now ready to receive your mailings. ``` **Prompt:** ``` Pause the email campaign with UID 'cp456def'. ``` **Response:** ``` I've triggered the pause command for campaign cp456def. MailWizz has updated the status and sending is now suspended. ``` ## Capabilities ### Manage Campaigns List all email marketing campaigns, or retrieve detailed metadata for a single campaign using `get_campaign_details`. ### Control Sending Status Pause or unpause an active mail campaign programmatically via the `pause_email_campaign` tool. ### List Collections and Subscribers Get a full list of all subscriber collections (`list_subscriber_collections`) or retrieve every member currently in a specific list using `list_list_subscribers`. ### Modify User Records Add new subscribers to lists with `add_subscriber_to_list`, remove existing users with `delete_list_subscriber`, or modify contact data using `update_list_subscriber`. ### Audit List Data Retrieve detailed information about a specific subscriber list, including its unique identifier and structure, via `get_list_details`. ## Use Cases ### Need to reactivate users from old lists. The marketing team found a list of high-value, dormant contacts. They ask their agent to 'Get all users in the 'VIP Leads' list and update their status.' The agent runs `list_list_subscribers` first for validation, then executes `update_list_subscriber` for each user, ensuring they are marked as active before sending a re-engagement flow. ### A new sign-up needs to be added and tracked. An external system generates a list of new leads. Instead of exporting them, the developer prompts the agent: 'Add these 5 users to the 'Main Leads' list.' The agent uses `add_subscriber_to_list` five times sequentially, confirming successful ingestion for every user. ### The current campaign is failing and needs a manual stop. During peak hours, an email campaign starts sending bad content. The manager prompts: 'Pause the Q2 product update campaign.' The agent immediately executes `pause_email_campaign` using the campaign's UID, stopping all further sends within seconds. ### Comparing two different audience segments. The CRM team wants to compare who is on the 'Beta Testers' list versus the 'Early Adopters' list. They prompt the agent to run `list_list_subscribers` for both UIDs. The agent returns two distinct, structured lists of IDs, allowing for side-by-side comparison. ## Benefits - Control sends instantly. Need to hit pause on a campaign? Use `pause_email_campaign` rather than logging into the web panel and clicking through menus. It’s fast, direct action. - Full subscriber visibility. You can list every collection with `list_subscriber_collections`, then drill down using `get_list_details` to understand the segment structure for targeted outreach. - Keep your data current. Instead of manual CSV uploads, use `add_subscriber_to_list` or `update_list_subscriber` to write clean API calls that sync contact records with zero risk of format errors. - Audit list health on demand. Running `list_list_subscribers` gives you a real-time dump of who's in the list, letting your agent quickly check for stale or incomplete records. - See campaign status at a glance. Use `list_email_campaigns` to get an immediate overview of all active and archived campaigns without opening the platform’s dashboard. ## How It Works The bottom line is that your AI client sends commands to this server, which translates those commands into specific API calls for MailWizz, returning clean data every time. 1. First, subscribe to the server and provide your MailWizz API URL along with your Public Key. 2. Your AI client establishes a secure connection to the endpoint. This allows it to execute specific operations (e.g., listing campaigns or adding subscribers) on your behalf. 3. You simply prompt your agent: 'List all active email campaigns.' The agent uses `list_email_campaigns`, gets the JSON result, and presents it back to you. ## Frequently Asked Questions **How do I find all my subscriber lists using MailWizz MCP Server?** You run the `list_subscriber_collections` tool. This returns a complete list of every collection you have, along with their unique IDs (UIDs), which you'll need for further actions. **Can I update multiple users at once using MailWizz MCP Server?** The server handles individual updates. You first use `list_list_subscribers` to get all target IDs, and then your agent can loop through those IDs, running the `update_list_subscriber` tool for each one. **What if I want to know the details of a specific campaign?** Use `get_campaign_details`. You just need to provide the campaign's UID. It returns all metadata, including status, send date range, and more. **Does MailWizz MCP Server support bulk deletion of subscribers?** Yes. The process is: run `list_list_subscribers` to get IDs; then use the array of IDs with the `delete_list_subscriber` tool. **How do I set up the connection credentials for `MailWizz` MCP Server?** You connect by providing your MailWizz API URL and a Public Key. These details authenticate your AI agent against your self-hosted instance, ensuring secure access to your marketing data. **What happens if I use `update_list_subscriber` with an invalid subscriber UID?** The operation will fail and return a specific error code. Your AI client catches this failure, telling you exactly which record needs correction before retrying the update. **Are there rate limits when I frequently call `list_email_campaigns`?** Yes, like all API integrations, MailWizz enforces standard rate limits. Always check your account dashboard to know the specific throughput restrictions for reliable operation. **Can I use `MailWizz` MCP Server to delete campaign data entirely?** No; this server focuses on audience and campaign management, not deletion of historical records. You must access MailWizz's core platform tools for permanent data removal. **How do I find my List UID or Campaign UID?** You can retrieve all UIDs by using the `list_subscriber_collections` or `list_email_campaigns` tools. They are also visible in the URL when viewing these resources in your MailWizz dashboard. **Can I add custom fields when subscribing a user?** Yes, include your custom field values (like FNAME, LNAME) within the `subscriber_json` object when using the `add_subscriber_to_list` tool. **What is the API URL?** This is the full base URL where your MailWizz API is reachable, for example: `https://mail.yourdomain.com/api`. Your token is encrypted at rest and injected securely at runtime.