> Mailbux API docs: manage domains, mailboxes, aliases, forwarders and DKIM by REST with a scoped key, then send and read mail with SMTP, IMAP or JMAP.

Source: https://mailbux.com/developers

# Mailbux API for Developers

Create and manage domains, mailboxes, aliases, forwarders and DKIM by REST with a scoped API key, then send and read mail with SMTP, IMAP or JMAP.

## 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?

| API | What it does | How you sign in | Plans |
| --- | --- | --- | --- |
| Management API | Domains, mailboxes, aliases, forwarders, DKIM, API keys | Bearer API key with scopes | Paid plans |
| Reseller API | White-label brands, mail pools, sub-tenants, tenant credentials | OAuth token with reseller scopes | Reseller add-on |
| SMTP, IMAP, POP3 and JMAP | Send and read a mailbox’s mail | Mailbox address and app password | SMTP and JMAP on every plan; IMAP and POP3 on paid plans |

## Get an API key

1. Use a paid plan. API keys are not available on Free.
2. Sign in to your [dashboard](https://dash.mailbux.com), 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](https://mailbux.com/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](https://mailbux.com/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

| Interface | Limit |
| --- | --- |
| Management API | 60 requests per 60 seconds for each key and source IP. Mail uploads have a narrower limit. Going over returns `429 rate_limited`. |
| Reseller API | 60 requests per minute. |
| Sending mail | Up to 300 messages per hour for each mailbox. |

When you get a 429, wait and retry.

## Errors

Management API errors share one JSON shape:

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

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `https_required` | The request was not made over HTTPS. |
| 401 | `unauthorized` | The bearer token is missing or does not match a key. |
| 401 | `token_suspended` | The key is suspended until it is enabled again in the dashboard. |
| 401 | `token_inactive` | The key was revoked or has expired. |
| 403 | `forbidden` | Missing scope, an IP outside the key’s allow-list, or the wrong brand host. |
| 403 | `api_unavailable` | The service is inactive, on a Free plan, or its mail connection is not ready. |
| 429 | `rate_limited` | More than 60 requests in 60 seconds. |
| 503 | `api_unavailable` | Temporarily unavailable during a deploy window. Retry shortly. |

## Guides

- [Mailbux Reseller API integration guide](https://mailbux.com/blog/reseller/mailbux-reseller-api-integration-guide)
- [What is JMAP? A guide to the email API](https://mailbux.com/blog/email-guides/what-is-jmap-email-api-guide-mailbux)
- [Email hosting for AI agents](https://mailbux.com/ai-email-hosting)
- [Developer guides](https://mailbux.com/blog/developer-guides)

## Reference pages

- [Management API](https://mailbux.com/management-api): domains, mailboxes, aliases, forwarders, DKIM and API keys
- [SMTP and Send API](https://mailbux.com/smtp-api): connection settings for sending and receiving
- [Reseller API](https://mailbux.com/reseller-api): brands, sub-tenants and credentials
- [llms.txt](https://mailbux.com/llms.txt): a site guide for AI agents

## Ready to Host Your Business Email for Free?

Set up professional email on your own domain in minutes. Free business email hosting, powered by Mailbux.

---

More for agents: [llms.txt](https://mailbux.com/llms.txt) · [Sitemap](https://mailbux.com/sitemap.xml)