canonical: https://jentic.com/apis/mailinabox.email/mailinabox

# Mailinabox Email Mail-in-a-Box

Mail-in-a-Box is an open-source self-hosted mail server that bundles SMTP, IMAP, webmail, DNS, and TLS into a single Ubuntu install. The admin API exposes 49 endpoints for managing mail users and aliases, DNS zones and custom records, SSL certificates, system status and updates, and backups. Authentication is HTTP Basic with optional MFA via the x-auth-token header.

## For AI agents

Administer a self-hosted Mail-in-a-Box server through 49 endpoints - manage mail users, DNS records, SSL certificates, system updates, and backups without SSHing into the box.

## Scope

Does not send transactional email, run marketing campaigns, or expose a public IMAP API - use for Mail-in-a-Box server administration only.

## Capabilities

- Add, remove, and set passwords for mail users on a Mail-in-a-Box server
- Grant or revoke admin privileges through the user-privileges endpoints
- Manage DNS custom A, MX, TXT, and other records on hosted zones
- Provision or install SSL certificates for hosted domains
- Trigger system package updates and reboot the box from the API
- Read system status, version, and backup configuration

## Use cases

### Self-Hosted Mail User Provisioning

Provision and deprovision mail users on a self-hosted Mail-in-a-Box server through the admin API rather than the web console. Endpoints under `/mail/users` cover add, remove, password reset, and privilege grant operations, which lets a small team or homelab manage its mail server from CI or a chat-ops bot. Each call uses HTTP Basic against the admin endpoint at /admin.

Example prompt: POST `/mail/users/add` with email=alice@example.com and password set to a generated value, then POST `/mail/users/privileges/add` to grant admin if needed.

### DNS and SSL Lifecycle

Manage DNS records and SSL certificates for the domains hosted on a Mail-in-a-Box without leaving the API. The `/dns/custom` endpoints support add, update, and remove for any record type while `/ssl/provision` triggers Let's Encrypt provisioning across the hosted domains. POST `/dns/update` applies pending DNS changes to the live nameserver.

Example prompt: POST `/ssl/provision` to provision certificates, then GET `/ssl/status` to confirm every hosted domain has a current certificate.

### System Maintenance Automation

Automate routine maintenance on a small fleet of Mail-in-a-Box instances by calling `/system/status` to gather health, `/system/updates` to identify pending package updates, and `/system/update-packages` to apply them. The `/system/reboot` endpoints schedule a controlled reboot when kernel updates require it.

Example prompt: Call POST `/system/status`, then if the response flags pending updates, POST `/system/update-packages` and confirm completion with GET `/system/version.`

### Agent-Driven Mail Server Operations

An AI agent can run end-to-end Mail-in-a-Box operations through Jentic: add a new user, provision an SSL cert, and update the backup config in one chained workflow. The basic-auth credentials live in your Jentic One instance and the agent works against the published admin endpoints without ever seeing the raw password.

Example prompt: Add a new mail user via POST `/mail/users/add`, set their password through POST `/mail/users/password`, and confirm the addition by checking GET `/mail/users.`

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/mail/users/add` | Add a mail user |
| POST | `/mail/users/password` | Set a mail user password |
| POST | `/dns/custom/{qname}/{rtype}` | Add a custom DNS record |
| POST | `/ssl/provision` | Provision SSL certificates via Let's Encrypt |
| POST | `/system/update-packages` | Update system packages |
| GET | `/system/status` | Get full system status |
| POST | `/login` | Exchange username and password for a session API key |

## Key resources

- **Mail Users** — Mail user lifecycle: add, remove, password set, privilege grant
- **DNS** — Zones, custom records, secondary nameservers, and zonefile dumps
- **SSL** — Status, CSR generation, install, and Let's Encrypt provisioning
- **System** — Status, version, updates, privacy, reboot, and backup configuration
- **Auth** — Login and logout endpoints that exchange password for a session API key

## Why Jentic

- **Setup:** Wiring Mail-in-a-Box by hand means encoding its HTTP basic credentials, pointing at your own {host}/admin server, and stitching together its mail, DNS, and SSL admin endpoints yourself. Through Jentic you install once, import Mail-in-a-Box from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** Mail-in-a-Box drives account and system changes through admin operations, so limit the agent to the operations it needs, such as reading system status, and leave changes like adding a mail user or updating packages out unless you add them. The operation set is your choice.
- **Credential handling:** Your Mail-in-a-Box credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'add a mail user' or 'check server status', and Jentic returns the matching Mail-in-a-Box operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Cloudflare API** — DNS, TLS, and edge protection that pairs naturally with a self-hosted mail server.
- **DigitalOcean API** — VPS provider commonly used to host Mail-in-a-Box instances.
- **MailerSend API** — Hosted transactional email provider for teams that prefer not to self-host.

## FAQ

### What authentication does the Mail-in-a-Box API use?

Mail-in-a-Box uses HTTP Basic authentication via the basicAuth scheme. If MFA is enabled, supply a one-time password in the x-auth-token header alongside Basic credentials. POST /login returns a session API key that can replace the password on subsequent calls. Through Jentic the credentials are stored encrypted in the vault.

### Can I add mail users through the API?

Yes. POST `/mail/users/add` creates a new mail user with email and password fields, and POST `/mail/users/privileges/add` grants admin rights. POST `/mail/users/password` resets the password for an existing user, and POST `/mail/users/remove` deletes the account.

### What are the rate limits for the Mail-in-a-Box API?

Mail-in-a-Box is self-hosted, so admin throughput is bounded by the resources of the box itself rather than a vendor-imposed rate limit. The OpenAPI spec does not declare a per-second cap. Long-running operations such as `/system/update-packages` should be polled rather than retried aggressively.

### How do I provision an SSL certificate through Jentic?

Search Jentic for "provision ssl mail in a box" to load POST `/ssl/provision`, then execute against your admin host. Follow up with GET `/ssl/status` to confirm a current certificate is in place for every hosted domain.

### Is Mail-in-a-Box free?

Yes. Mail-in-a-Box is open-source software released under CC0. There is no licence fee - you only pay for the VPS or hardware that runs the box and any domain or DNS costs.

### Can I trigger DNS updates from the API?

Yes. POST `/dns/update` applies pending DNS changes to the live nameserver, and the `/dns/custom` endpoints add, update, or remove individual records. Use GET `/dns/dump` to inspect the full zonefile state for debugging.

### Can I limit what my agent is allowed to do with the Mail-in-a-Box API?

Yes. Because Jentic One is self-hosted, your own rules decide which Mail-in-a-Box operations and credentials the agent may use. You can allow read-only calls like GET `/system/status` while leaving out account and system changes such as POST `/mail/users/add` or POST `/system/update-packages` unless you explicitly add them. The operation set the agent can call is entirely your choice.