# Mail-in-a-Box MCP

> Mail-in-a-Box MCP Server automates private email server administration. Your AI agent connects directly to your Mail-in-a-Box instance, giving it tools to handle user creation, password resets, and alias management via natural language commands. This lets you manage mailboxes and monitor system health without ever touching a dashboard or API client.

## Overview
- **Category:** communication-messaging
- **Price:** Free
- **Tags:** email-server, user-administration, dns-management, system-health, private-email, mailbox-management

## Description

You run a private email server, and you don't wanna live in the dashboard or mess around with API endpoints just to manage users. This MCP Server gives your AI agent direct command access to Mail-in-a-Box. It handles everything—from adding new mailboxes to fixing forwarding rules—all through natural language prompts. You just talk to your agent, and it executes the necessary commands against your live server instance.

**Managing User Accounts:** The core capability here lets you control every user on your system. To get started, the `create_mail_user` tool handles adding a new mailbox; you provide the full email address and set the initial password, and that account is live. If someone changes their mind or needs to change their login credentials, you'll use `update_user_password` to reset it without touching the actual user profile. When an account is done for good, `delete_mail_user` permanently removes the mailbox and associated data from the server. To keep track of who’s actually on board, you can always run `list_mail_users`, which gathers a full roster of every active mail user currently set up on your instance.

**Handling Email Aliases:** Forwarding addresses are crucial for any serious email setup. The agent manages these rules using `create_or_update_alias`; this tool lets you either establish a brand-new forwarding address or modify an existing one, ensuring incoming messages get sent to the right place or multiple places. If an alias gets messed up or is no longer needed, you just run `delete_mail_alias` and it removes that specific forwarding rule from your server configuration. You can see exactly what's set up by using `list_mail_aliases`, which pulls together a complete list of every current alias and shows where each one directs mail.

**Listing Domains and Diagnosing Status:** Before you change anything, you need to know what’s running. The `list_mail_domains` tool returns a comprehensive inventory of every domain name configured on the server instance. This is your quick check to make sure all your intended domains are recognized by Mail-in-a-Box. To see how healthy the whole setup is, run `get_system_status`. That checks the overall operational status of the entire email server stack, giving you real-time diagnostic information on performance and service health.

This set of tools means your AI client doesn't just read data; it *acts*. It executes direct administrative changes. You get to manage user accounts, control every alias forwarding rule, and check system diagnostics—all without ever opening a dashboard or writing an API call. It’s pure automation for hardcore email admin work.

## Tools

### create_mail_user
Adds a new user mailbox by providing a full email address and setting a password.

### list_mail_aliases
Retrieves a complete list of all current mail aliases and where they forward to.

### list_mail_domains
Returns a comprehensive list of every domain name hosted on the server instance.

### delete_mail_alias
Removes a specific forwarding address (alias) from the server configuration.

### delete_mail_user
Permanently removes an existing user account and its associated mailbox.

### update_user_password
Changes the password for an existing user mailbox without deleting the account.

### get_system_status
Checks the overall operational status of the entire Mail-in-a-Box server system.

### create_or_update_alias
Changes or sets up an email alias so incoming messages forward to one or more specified emails.

### list_mail_users
Gathers and displays a full roster of all active mail users currently set up on the server.

## Prompt Examples

**Prompt:** 
```
List all mail users on my server.
```

**Response:** 
```
I've retrieved the users. You have 12 mailboxes across 2 domains, including 'admin@example.com', 'user1@example.com', and 'team@otherdomain.io'.
```

**Prompt:** 
```
Create a new mail user 'support@example.com' with password 'MySecret123!'.
```

**Response:** 
```
Successfully created the mailbox for support@example.com. The user can now log in via IMAP/SMTP or webmail.
```

**Prompt:** 
```
How is the health status of my Mail-in-a-Box server?
```

**Response:** 
```
I've checked the system status. All core services (DNS, IMAP, SMTP) are running correctly. 2 minor updates are available for your OS.
```

## Capabilities

### Manage User Accounts
The agent can create, read, update, and delete entire mail user accounts.

### Handle Email Aliases
You can add new forwarding aliases, remove old ones, or list all existing addresses that redirect mail.

### Diagnose Server Status
The agent retrieves the real-time health status and diagnostic information for the entire email server stack.

### List Hosted Domains
You can get a list of all domains that are currently configured to run on the instance.

## Use Cases

### New Employee Onboarding
The ops engineer needs to onboard a new manager. They ask the agent, 'Create user 'manager@corp.com' and set their password.' The agent runs `create_mail_user` and confirms success. Next, they ask, 'Make sure that alias also forwards to the sales team,' running `create_or_update_alias`. Done in three steps.

### Security Audit of Accounts
The security auditor needs a full roster and status check. They prompt, 'List all users and then tell me the system health.' The agent runs `list_mail_users` to get the list, and immediately follows up with `get_system_status` to ensure no service is down.

### Fixing a Broken Forwarder
A marketing team member reports that 'old-info@corp.com' isn't forwarding mail correctly. They ask the agent, 'Check and fix the alias for old-info.' The agent runs `list_mail_aliases` to verify the current setup, then uses `delete_mail_alias` followed by `create_or_update_alias` to correct it.

### Server Health Check
The DevOps team notices suspicious activity. They ask the agent for a full report. The agent runs `get_system_status`, which verifies if DNS, IMAP, and SMTP services are running correctly before alerting the team.

## Benefits

- Automate user management. Instead of running a console command to create a mailbox, you just ask your agent to 'create a new account for support@company.com,' using `create_mail_user`.
- Handle complex forwarding rules instantly. Use `create_or_update_alias` to set up an alias that sends mail to three different team members simultaneously—no manual list editing required.
- Get instant system diagnostics. Need to know if the server is healthy? Just run `get_system_status`. It pulls all core service metrics without you needing to log into a dashboard.
- Maintain domain visibility. With `list_mail_domains`, you instantly see every single domain hosted on your instance, making audits much faster than digging through configuration files.
- Streamline account lifecycle. If an employee leaves, instead of manually deleting them from multiple places, use `delete_mail_user` and `delete_mail_alias` in two prompts.

## How It Works

The bottom line is: You talk to your AI client like you're talking to a system admin, and it runs the necessary commands on your private email server.

1. Subscribe to this server and provide your Mail-in-a-Box Host credentials (Admin Email/API Key).
2. Your AI agent sends a natural language request, which triggers the appropriate tool (e.g., `create_mail_user`).
3. The tool executes against your live server and returns structured data or confirmation to the agent for you to review.

## Frequently Asked Questions

**How do I list every user mailbox using the list_mail_users tool?**
Just ask your agent to run `list_mail_users`. It retrieves a full roster of all active mail users configured on the server. This is faster than logging into the web UI.

**I need to change an alias; should I use delete_mail_alias or create_or_update_alias?**
It's best practice to run `list_mail_aliases` first so you know exactly what you’re working with. Then, if the rule is wrong, use `create_or_update_alias`—it handles both setting up new rules and updating existing ones.

**What should I do to reset a user's password? Is there a specific tool?**
Use the `update_user_password` tool. You just give the agent the username and the new temporary password, and it handles the change securely.

**If I delete a user mailbox with delete_mail_user, is that permanent?**
Yes, using `delete_mail_user` removes the account entirely. Always verify your list of users first by running `list_mail_users` to make sure you're targeting the right account.

**If I run `get_system_status`, what kind of diagnostics does it report on my Mail-in-a-Box system?**
It provides a real-time health check. You'll see if all core services, like IMAP and SMTP, are running correctly. The tool also flags available OS updates or minor configuration issues.

**When using `create_mail_user`, what inputs does the tool require to successfully create a new mailbox?**
You must provide two things: a full, unique email address and a secure password. The tool then handles creating the user account, allowing them immediate access via IMAP/SMTP or webmail.

**How do I use `list_mail_domains` to see all hosted domains on my server?**
The function returns a comprehensive list of every mail domain and subdomain configured on your instance. This helps you quickly verify the scope of email addresses managed by this server.

**If I use `list_mail_aliases`, what exactly does that tool display about my forwarding setup?**
It returns a list of every defined alias and specifies which emails it forwards to. This is useful for auditing your entire system's email redirection rules at a glance.

**What format is required for the instance host?**
Provide the full hostname without the 'https://' prefix, for example: `box.yourdomain.com`.

**Can I add multiple forwarding targets to an alias?**
Yes, when using the `create_or_update_alias` tool, provide a comma-separated list of emails in the `forwards_to` field.

**Does this work with 2FA enabled accounts?**
The current API implementation uses Basic Auth. If 2FA is enabled on your admin account, you may need to use an API key or a dedicated admin user without 2FA for the integration.