Mailbux API for Developers

What the Mailbux API does

The Mailbux API lets your software run business email on your own domain. You can create and manage domains, mailboxes, aliases, forwarders, DKIM keys and API keys, and you can send and read mail from real, authenticated mailboxes. Mailbux uses open standards, so there is nothing Mailbux-specific to install: any HTTP client works for the REST API, and any SMTP, IMAP or JMAP library works for mail.

There are three parts, and most projects need only one or two of them:

• Mailbux Management API. A REST API at https://dash.mailbux.com/api/v1 for running your own email: domains, mailboxes, aliases, app passwords, distribution lists, mail filters, the vacation responder, DKIM, forwarders and more. You sign each request with an API key from your dashboard. Every endpoint needs its own scope, and a key without that scope gets a 403, never a partial answer.
• Mailbux Reseller API. For agencies, MSPs and hosting companies that sell email under their own brand. It manages your white-label brands, the mail pools they draw on and your sub-tenants, and it issues API credentials for each sub-tenant. It uses OAuth bearer tokens with reseller scopes.
• Mail protocols: SMTP, IMAP, POP3 and JMAP. To send and read the mail itself, connect to my.mailbux.com as the mailbox. SMTP and JMAP work on every plan. IMAP and POP3 need a paid plan. For scripts, CI jobs and AI agents, use an app password so you can revoke it without changing the mailbox password.

API keys are available on paid and lifetime (LTD) plans. The Free plan has no API keys, and moving a service to Free revokes its keys. Each key belongs to one service and can never reach another customer or service. Requests are limited to 60 a minute per key and source IP, and sending is limited to 300 messages an hour per mailbox on every plan.

An API key acts like your organization’s administrator: it manages mailboxes but cannot open the mail inside them. To read or send a mailbox’s mail, sign in as that mailbox with JMAP or SMTP and an app password.

You can also read the plan catalog as JSON without a key, at https://dash.mailbux.com/api/v1/public/plans.

Which Mailbux API do I need?

Get an API key

1. Use a paid plan. API keys are not available on Free.
2. Sign in to your dashboard, open the service, then go to Manage, then API access, and create a key.
3. Copy it right away. It is shown once and cannot be recovered. If you lose it, create a new one.

Reseller API calls use an OAuth bearer token with the reseller scope instead, described on the Reseller API page.

Quickstart with curl

These steps use the Management API. Replace YOUR_API_KEY with your key.

1. Use a paid plan. API keys are not available on Free.
2. Create a key. In your dashboard, open the service, then Manage, then API access, and create a key. Copy it now: it is shown once and can’t be recovered.
3. Check the key. The answer lists the accounts your key can act on. Note the account id.

   curl "https://dash.mailbux.com/api/v1/mail/session" \
     -H "Authorization: Bearer YOUR_API_KEY"

4. List your mailboxes. Call POST https://dash.mailbux.com/api/v1/mail with the method x:Account/query and your account id (the full example is on the Management API page).

   curl -X POST "https://dash.mailbux.com/api/v1/mail" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "using": ["urn:ietf:params:jmap:core"],
       "methodCalls": [["x:Account/query", {"accountId": "YOUR_ACCOUNT_ID"}, "0"]]
     }'

5. List your forwarders.

   curl "https://dash.mailbux.com/api/v1/forwarders" \
     -H "Authorization: Bearer YOUR_API_KEY"

6. Send or read a mailbox’s mail. Create an app password for that mailbox (in its dashboard: Manage, then App Passwords). Then use SMTP at my.mailbux.com:587 (STARTTLS) to send, or JMAP at https://my.mailbux.com/.well-known/jmap with the mailbox address and the app password.
7. Handle errors. Every error comes back as {"error": {"code": "...", "message": "..."}}. A 429 rate_limited means more than 60 requests in 60 seconds: wait and retry.

The public plan catalog needs no key: curl "https://dash.mailbux.com/api/v1/public/plans".

Authentication and scopes

Send the key as Authorization: Bearer YOUR_API_KEY. A key is bound to one service, its owner and its tenant, so it can never reach another customer.

Each endpoint, and each JMAP method, needs its own scope. A key without the scope gets 403, never a partial answer. Examples: forwarders:read and forwarders:write for forwarders, mail:native for the mail passthrough. A key can also be limited to a list of IP ranges. Reseller tokens carry reseller, with reseller.read, reseller.write and others added as needed. App passwords are a different credential for mail apps and are never accepted by the API.

Rate limits

When you get a 429, wait and retry.

Errors

Management API errors share one JSON shape:

{
  "error": {
    "code": "unauthorized",
    "message": "..."
  }
}

Guides

• Mailbux Reseller API integration guide
• What is JMAP? A guide to the email API
• Email hosting for AI agents
• Developer guides

Reference pages

• Management API: domains, mailboxes, aliases, forwarders, DKIM and API keys
• SMTP and Send API: connection settings for sending and receiving
• Reseller API: brands, sub-tenants and credentials
• llms.txt: a site guide for AI agents