# Listmonk MCP > Listmonk MCP Server lets your AI client manage every step of your email marketing workflow via chat. It controls subscribers, campaigns, lists, templates, and media assets using direct API calls. Instead of jumping between a dashboard and a spreadsheet, you tell the agent what to do—like finding all users in California who haven't opened an email in 60 days—and it runs the necessary tools for you. ## Overview - **Category:** marketing-automation - **Price:** Free - **Tags:** newsletter-management, mailing-lists, subscriber-management, email-campaigns, self-hosted, data-filtering ## Description You'll use your AI client to manage every part of your email marketing operation right from the chat window. You don't need to bounce between a dashboard and a spreadsheet; you just tell your agent what you want, and it runs the necessary commands against your Listmonk data. ### Managing Your Subscribers When you need user info, you can run deep queries using `list_subscribers`, which lets you filter and retrieve specific groups of people with complex SQL-like expressions. If you just need details on one person, use `get_subscriber` to pull all known data for that profile. You've got updates? Use `update_subscriber` to adjust specific fields on an existing record, or if you only need a small change—say, changing their status—you can hit them with `patch_subscriber`. If someone leaves the list entirely, you'll use `delete_subscriber`; for cleaning up data messes, the agent handles deleting multiple old bounce logs via `delete_bounces`. ### Building and Segmenting Lists To organize your users into groups, you can build a brand new segment using `create_list`, which names and sets up the list. Need to make it public so people can sign up on your site? You'll call `create_public_subscription`. To see what lists you already have, run `list_lists`; if you need the names or status of public-facing signup forms, use `list_public_lists`. If a list is totally useless and needs to go, you can permanently remove it with `delete_list`; likewise, you modify existing segments using `update_list`. ### Running Campaigns Launching an email series is straightforward. You'll create the initial draft campaign by calling `create_campaign`. To move that draft into a live send state, use `update_campaign_status`. When you want to see all the campaigns that exist, run `list_campaigns`, and if you only need the full details for one specific series, use `get_campaign`. If something goes wrong with a campaign or it's no longer needed, you can delete the draft or published series entirely using `delete_campaign`. ### Sending Critical Messages & Templates Sometimes you can't wait for the next newsletter. You need to send high-priority messages instantly to specific users; that’s what `send_transactional_message` does, and it uses templates and targets selected subscribers immediately. For content structure, you manage your templates—you generate a blank one with `create_template`, check existing options using `list_templates`, or change the content of an old template via `update_template`. If a template is garbage and needs to be purged, call `delete_template`. ### Managing Assets and Maintenance When it comes to your media library—those images and PDFs—you can list everything uploaded using `list_media`, or delete specific files with `delete_media`. You'll also need to keep track of large data dumps; running `get_import_status` checks the progress of any big import job, and if it's going too slow, you can halt it right away using `stop_import`. For ultimate data hygiene, besides clearing bounce logs, you can check how far along a massive data upload is by calling `get_import_status`; you also have tools to delete campaign drafts or lists entirely, giving you full control over the entire lifecycle of your marketing content. ## Tools ### create_campaign Creates a draft campaign for your newsletter series. ### create_list Builds and names a brand new mailing list segment. ### create_public_subscription Sets up a publicly visible sign-up form for your site. ### create_subscriber Adds one new user profile to the system. ### create_template Generates a blank email template structure. ### delete_bounces Cleans up multiple records of failed bounce emails from your database. ### delete_campaign Removes a campaign draft or published series entirely. ### delete_list Permanently removes an entire mailing list segment. ### delete_media Deletes a specific image or asset file from your media library. ### delete_subscriber Removes one individual user profile completely from the system. ### delete_template Deletes a structured email template, making it unavailable for use. ### get_campaign Retrieves all current details about one specific campaign by ID. ### get_import_status Checks the progress and status of a large data import job. ### get_subscriber Retrieves all known details for one specific subscriber profile. ### list_bounces Gets a full list of recent bounce records to check deliverability issues. ### list_campaigns Retrieves a paginated list containing all existing campaigns. ### list_lists Lists every mailing list segment you have created. ### list_media Gets a list of all media files (images, PDFs) uploaded to your account. ### list_public_lists Retrieves the names and statuses of any public-facing lists. ### list_subscribers Queries and retrieves subscribers using advanced filtering, including SQL expressions. ### list_templates Retrieves a full list of all available email templates you've built. ### patch_subscriber Makes small, targeted updates to specific fields on an existing subscriber record (e.g., status change). ### send_transactional_message Sends high-priority messages instantly to selected subscribers using a defined template. ### stop_import Halts an ongoing, large data import process immediately. ### update_campaign_status Changes the status of a campaign (e.g., from Draft to Published). ### update_list Modifies the settings or name of an existing mailing list. ### update_subscriber Updates specific details for a known subscriber profile. ### update_template Changes content or structure within an existing email template. ## Prompt Examples **Prompt:** ``` List all subscribers who are currently enabled in list 2. ``` **Response:** ``` I've queried your subscribers. In list 2, I found 15 enabled subscribers. Would you like to see the full list or filter them further by name? ``` **Prompt:** ``` Create a new campaign named 'Monthly Newsletter' with the subject 'Our latest updates'. ``` **Response:** ``` Campaign 'Monthly Newsletter' has been created successfully as a draft. You can now assign lists to it or update its content. ``` **Prompt:** ``` Show me all available email templates. ``` **Response:** ``` I've retrieved your templates. You have 3 available: 'Default', 'Newsletter-V2', and 'Transactional-Simple'. Which one would you like to use? ``` ## Capabilities ### Segmenting Users with Filters You query the database to find specific groups of subscribers using tools like `list_subscribers`, applying complex filters and SQL logic. ### Drafting and Activating Campaigns The agent creates new campaigns with `create_campaign` and moves them into a live state using `update_campaign_status`. ### Sending High-Priority Emails You send immediate, critical messages to subscribers using the `send_transactional_message` tool, bypassing standard newsletter scheduling. ### Managing Content Assets The system lets you list and manipulate templates (`list_templates`) or media files (`list_media`) without ever logging into the web UI. ### Cleaning Up Data Records You delete specific records, like old bounce logs via `delete_bounces`, to maintain data hygiene and keep your systems fast. ## Use Cases ### Cleaning up dead leads after a campaign. A growth manager runs a major promotion and notices high bounce rates. They ask the agent to run `list_bounces` first, identify the patterns, then use `delete_bounces` to clean the records. This prevents future sends from being flagged by spam filters due to outdated error data. ### Sending a critical account update. A developer needs to send an urgent 'API key updated' alert. They don't use a campaign; they ask the agent to `send_transactional_message` immediately, ensuring all active users get the high-priority notice using the correct template. ### Preparing for Q3 product launches. A marketer needs three new email assets. They first run `list_templates` to see what exists. Then, they ask the agent to create two new ones using `create_template` and finally use `update_template` on a third one to incorporate updated branding guidelines. ### Segmenting users who haven't engaged in 90 days. A content creator wants to re-engage inactive users. They instruct the agent to run `list_subscribers` with a complex filter (e.g., 'last opened < 90 days ago'). The agent returns the list of IDs, which can then be used for a targeted outreach campaign. ## Benefits - You can segment audiences on the fly. Instead of manually building a complex filter in the dashboard, you simply ask your agent to `list_subscribers` with specific SQL criteria (e.g., 'all users who signed up last month'). - Sending high-priority emails is instant. Use `send_transactional_message` when you need immediate communication—like a password reset or alert—without going through the full campaign creation process. - Data hygiene becomes automatic. You can check and delete old bounce records using `list_bounces` followed by `delete_bounces`, keeping your mailing list clean and reliable for high-volume sends. - Campaign status changes are simple commands. Don't navigate through multiple tabs; just ask the agent to run `update_campaign_status` when a draft is ready to go live. - Template management is centralized. You don't need to open the web editor to check assets; running `list_templates` or `list_media` gives you an immediate inventory of what content exists. ## How It Works The bottom line is: you manage complex marketing tasks through plain text prompts, not clicking through dashboards. 1. First, subscribe the server using your unique Listmonk URL and API Token. 2. Next, connect this endpoint to your preferred AI client (Claude, Cursor, etc.). 3. Finally, ask your agent a natural language question—for example, 'Send an alert email to all users who haven't logged in last month.' — and the agent executes the necessary sequence of tools. ## Frequently Asked Questions **How do I check if my data import was successful using get_import_status?** You use `get_import_status` to retrieve the current progress. It tells you exactly where the job is—whether it's still running, finished successfully, or if there were errors that need fixing. **Can I segment subscribers using list_subscribers with complex filters?** Yes. `list_subscribers` supports advanced filtering and SQL expressions. You can query for segments like 'all users in List A who haven't engaged since last month,' making segmentation powerful. **I need to change a user’s status without creating a new record. Which tool should I use?** You should use `patch_subscriber` or `update_subscriber`. These tools allow you to modify only specific fields—like changing a status from 'active' to 'unsubscribed'—without rewriting the entire profile. **What if I need to send an email but don't have a template yet? Can I still send it?** While `send_transactional_message` requires a template, you can first use `create_template` or `update_template` to build one in the chat environment before sending. The agent manages that sequence for you. **If I need to permanently remove a user from my system using `delete_subscriber`, what information do I need?** You must provide the unique subscriber ID. This tool executes an irreversible deletion, so double-check your target records before running it. **How can I verify that the connection to Listmonk is active and working before building a complex query with `list_subscribers`?** Run `list_lists`. This immediately confirms connectivity by retrieving all current mailing lists. If this succeeds, your agent has access to the basic server endpoints. **I have finished drafting an email and need to change its status from 'Draft' to 'Scheduled'. Which tool handles this state change? ** Use `update_campaign_status`. You supply the Campaign ID along with the target status (e.g., 'scheduled'). This changes the workflow state without altering content. **How do I clean up old images or attachments that are stored as assets, using the media tools?** First, run `list_media` to see all available files and their IDs. Then use `delete_media`, making sure you pass the correct file ID for deletion. **Can I search for subscribers using specific SQL-like attributes?** Yes! Use the `list_subscribers` tool with the `query` parameter. You can use SQL expressions to filter by attributes, names, or email patterns directly through the agent. **How do I send a one-off transactional email to a user?** Use the `send_transactional` action. You just need to provide the subscriber's email or ID and the template ID you wish to use for the message. **Can I stop an ongoing subscriber import if I notice an error?** Absolutely. Use the `stop_import` tool to immediately halt any active subscriber import process in your Listmonk instance.