canonical: https://jentic.com/apis/mailu.io/mailu # Mailu API 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. ## For AI 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. ## Scope 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. ## Capabilities - 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 ### 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. Example prompt: 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. Example prompt: 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. Example prompt: 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. Example prompt: 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 | 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 | ## Key resources - **Domains** — Create, list, update, and delete managed domains on the Mailu server. - **Users** — Create, fetch, update, and delete mailbox users under a managed domain. - **Aliases** — Create, fetch, update, and delete forwarding aliases pointing at one or more destinations. - **Relays** — Configure relay domains for outbound mail forwarding. - **Fetchers** — Manage fetcher accounts that pull mail from external IMAP or POP3 mailboxes. ## Why Jentic - **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 handling:** 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. - **Discovery method:** 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 - **Mailtrap API** — Mailtrap is a hosted transactional email service rather than a self-hosted server. - **Mailsac API** — Mailsac provides disposable inboxes useful for end-to-end testing of mail flowing through a Mailu server. - **Cloudflare API** — Cloudflare manages the DNS records (MX, SPF, DKIM) that a Mailu domain depends on. ## FAQ ### 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.