Mailu API
Agent-ready OpenAPI document · curated by JenticCommunicationsEmail DeliveryapiKey25 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For Agents
Provision and manage a self-hosted Mailu mail server: create users, aliases, and domains, configure relays, and set up fetchers. Used by agents that automate hosting setup for self-managed email.
Use for: I need to create a new user mailbox on a Mailu server, Add a forwarding alias from sales@example.com to the team, List every domain managed by the Mailu server, Update the password and quota for an existing Mailu user
Not supported: Does not send transactional or marketing email, host an external SaaS mailbox, or manage end-user webmail sessions - use for self-hosted Mailu admin operations only.
Jentic publishes the only available OpenAPI specification for Mailu API, keeping it validated and agent-ready. Mailu is a self-hosted Docker mail server and its admin REST API exposes 25 endpoints for managing the entities a postmaster cares about: domains, users, aliases, relays, and fetcher accounts. The API runs on the operator's own host and is protected by an API token configured in the Mailu admin interface, making it ideal for automated provisioning of small-to-medium self-hosted mail deployments.
Install Jentic One Beta
Connect the Mailu API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Mailu API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fmailu.io%2Fmailu" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fmailu.io%2Fmailu" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Mailu API.
Create a new mailbox user under a managed domain with quota and password
Add or remove a forwarding alias that points to one or more destinations
Register a new managed domain on the Mailu server with MX and TLS settings
Configure a relay domain so the server forwards mail to an upstream host
Set up a fetcher account that pulls mail from an external IMAP or POP3 mailbox
Audit every user and alias on the server for retention or compliance reviews
Use Cases
Patterns agents use Mailu API for, with concrete tasks.
★ Automated User Provisioning
Self-hosted Mailu deployments often back small companies and homelabs that add and remove users frequently. The user endpoints create, update, and delete mailboxes under a managed domain with quota, password, and forward settings, so an HR or onboarding script can provision a new starter's mailbox in seconds. The same flow handles offboarding by deleting or disabling the user.
POST /users with email new.starter@company.com, password, and quota - then verify with GET /users/{email}.
Alias and Forwarding Management
Group addresses, role mailboxes, and personal forwarding rules are managed as Mailu aliases. The alias endpoints create, update, and delete forwarding rules that point a single address at one or more destinations. Operators can rotate role mailbox owners or disable a leaked address without touching the underlying user.
POST /aliases creating sales@example.com pointing at [alice@example.com, bob@example.com] with copy-on-keep enabled.
Domain and Relay Configuration
Adding a new domain to a self-hosted Mailu instance is a multi-step task: create the domain in admin, configure MX in DNS, optionally set up relay rules. The Mailu domain endpoints handle the admin side and the relay endpoints register upstream forwarders for outbound traffic. Together they let an automation script bring a new domain online without console access.
POST /domains with name 'newcompany.io', then POST /relays for upstream-relay.example.com to handle outbound.
AI Agent Postmaster Assistant
Operators of self-hosted mail servers benefit from agents that triage common admin requests: 'add a forwarder', 'reset a password', 'delete a stale alias'. Through Jentic the agent searches by intent, loads the schema, and executes the right Mailu admin call. The API token stays in the vault rather than in the agent's context.
Use Jentic to search 'add forwarding alias on mailu', execute POST /aliases with the requested forward, and confirm by listing the alias back.
Key Endpoints
25 endpoints — jentic publishes the only available openapi specification for mailu api, keeping it validated and agent-ready.
METHOD
PATH
DESCRIPTION
POST
/users
Create a user
GET
/users/{email}
Get user details
POST
/aliases
Create an alias
POST
/domains
Create a domain
POST
/relays
Create a relay domain
POST
/fetch
Create a fetcher
POST
/users
Create a user
GET
/users/{email}
Get user details
POST
/aliases
Create an alias
POST
/domains
Create a domain
POST
/relays
Create a relay domain
POST
/fetch
Create a fetcher
Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring the Mailu API by hand means sending your token in the Authorization header, pointing at your own {server_url}/api/v1 host, and driving its user, alias, domain, and relay endpoints yourself. Through Jentic you install once, import Mailu from the API Directory, store the token once, and your agent calls it.
Permission scoping
Mailu puts the user address in the URL path (/users/{email}), so a rule can pin your agent to reading one user. You choose the operations it may call, so creating a user, alias, or domain is not included unless you add it.
Credential isolation
Your Mailu API token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
Intent-based discovery
Agents search Jentic by intent such as 'create a mailbox user' or 'add an alias', and Jentic returns the matching Mailu operation with its input schema so the agent calls the right endpoint without browsing the reference docs.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Mailu API through Jentic.
Why is there no official OpenAPI spec for Mailu API?
Mailu does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Mailu API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.
What authentication does the Mailu API use?
Mailu uses an API token passed in the Authorization header, configured in the admin interface of the self-hosted instance. Through Jentic the token is encrypted in the vault and injected at execute time, so it never enters the agent context.
Can I create a new mailbox user through the API?
Yes. POST /users with email, password, and quota creates the mailbox. GET /users/{email} returns the configured user, and PATCH or DELETE update or remove it.
How do I forward mail from one address to another on Mailu?
Create an alias with POST /aliases where the source is the public address and destination is the list of recipients. Update the alias with PATCH /aliases/{email} or remove it with DELETE.
What are the rate limits for the Mailu API?
Mailu is self-hosted, so rate limits depend on the operator's deployment rather than a managed quota. The OpenAPI spec does not declare limits - keep request rates reasonable to avoid pressure on the admin process.
How do I provision a Mailu user through Jentic?
Run pip install jentic, search 'create mailu user', load the schema for POST /users, and execute with email, password, and quota. Jentic injects the API token from the vault at request time.
Can I limit what my agent is allowed to do with the Mailu API?
Yes. Because you run Jentic One yourself, your own rules decide which Mailu operations and credentials the agent may use. Since Mailu puts the user address in the URL path, such as GET /users/{email}, you can pin the agent to reading a single user, and you choose the operations it may call so that creating a user, alias, domain, or relay is excluded unless you add it. Your Mailu API token stays with your self-hosted instance and is injected only at execution time, never entering the agent's context.
GET STARTED