Mailbux API v1

Overview

The API manages one Mailbux service. Your key is bound to that service, its owner, its tenant namespace and the brand host it was created on, so it can never reach another customer, another service, or any provisioning credential.

Scoped to

One service

Auth

Bearer key

Rate limit

60 req/min

To read or send a mailbox’s own mail, see: Read a mailbox’s mail

Authentication

Send your key as a bearer token. It is shown once when you create it and is never recoverable; create a new one if it is lost.

curl -H "Authorization: Bearer <your-mail-api-key>" \
     https://dash.mailbux.com/api/v1/service

• Each endpoint requires its own scope. A token without that scope receives 403 — it is never silently downgraded to a partial response.
• Every response is limited to the one service the token was issued for. There is no account-wide or cross-service endpoint.
• Your mail key writes mail-server state — mailboxes, domains, DKIM, aliases — inside your tenant only. Everything else is read-only: no endpoint mutates billing or DNS state, and forwarders:write can only change this service's own forwarders.
• App passwords do not work here. They authenticate mail apps, and let you log in as a mailbox directly to read or send its mail: Read a mailbox’s mail

Base URL

Every path on this page is relative to one base URL. There is no second hostname to configure: mail-server calls are relayed to your mail server, and forwarders, storage and plan figures are answered here.

curl -H "Authorization: Bearer <your-mail-api-key>" \
     -H "Content-Type: application/json" \
     --data '{"using":["urn:ietf:params:jmap:core"],
              "methodCalls":[["x:Account/query",{},"a"]]}' \
     https://dash.mailbux.com/api/v1/mail

Mailbox and domain writes — create, delete, password changes — use the same /mail endpoint with the x:Account and x:Domain JMAP method families. There are no separate REST paths for these on purpose: your key already carries the management permissions for your tenant.

# 1) create the mailbox (domainId comes from GET /domains)
curl -H "Authorization: Bearer <your-mail-api-key>" \
     -H "Content-Type: application/json" \
     --data '{"using":["urn:ietf:params:jmap:core"],
              "methodCalls":[["x:Account/set",{"create":{"new":{
                "@type":"User","name":"sales","domainId":"<domainId>",
                "description":"Sales inbox"}}},"a"]]}' \
     https://dash.mailbux.com/api/v1/mail

# 2) set its password (id returned by step 1; the server
#    rejects credentials inside the create call itself)
curl -H "Authorization: Bearer <your-mail-api-key>" \
     -H "Content-Type: application/json" \
     --data '{"using":["urn:ietf:params:jmap:core"],
              "methodCalls":[["x:Account/set",{"update":{"<accountId>":
                {"credentials/0/secret":"S!rongPassw0rd"}}},"a"]]}' \
     https://dash.mailbux.com/api/v1/mail

# delete: ["x:Account/set",{"destroy":["<accountId>"]},"a"]

Tokens also carry a second bearer beginning mbx_. It is accepted at the same address with the same scopes and reaches the same endpoints, so either secret works — new integrations only need the mail key.

Read a mailbox’s mail

Your API key is your organization’s admin. It manages mailboxes, domains, aliases, DKIM, API keys and forwarders — the same as an admin in the mail portal. Like that admin, it cannot open the mail inside a mailbox: its own session holds only its own, empty mailbox.

To read or send a mailbox’s mail from your app, log in as that mailbox with JMAP:

Session URL

https://my.mailbux.com/.well-known/jmap

Sign in as

HTTP Basic — username is the mailbox address, password is an app password created for that mailbox

Then call the session’s apiUrl for the account listed under: primaryAccounts["urn:ietf:params:jmap:mail"]

curl -L -u "mailbox@example.com:APP_PASSWORD" \
     https://my.mailbux.com/.well-known/jmap

# then POST your method calls to the "apiUrl" the session document
# returns (inMailbox = the id of the mailbox with role "inbox"):
curl -u "mailbox@example.com:APP_PASSWORD" \
     -H "Content-Type: application/json" \
     --data '{"using":["urn:ietf:params:jmap:core","urn:ietf:params:jmap:mail"],
              "methodCalls":[
                ["Mailbox/get",{"accountId":"<accountId>"},"a"],
                ["Email/query",{"accountId":"<accountId>",
                  "filter":{"inMailbox":"<inboxId>"},
                  "sort":[{"property":"receivedAt","isAscending":false}],
                  "limit":20},"b"]
              ]}' \
     <apiUrl-from-the-session-above>

App passwords are not accepted at https://dash.mailbux.com/api/v1 — that base takes API keys only.

Mail-server endpoints

Mailboxes, domains, aliases, DNS readiness and DKIM. JMAP method calls are relayed straight to your mail server as your key’s own admin identity, confined to your tenant — not as any one mailbox.

These calls run as your API key’s own admin identity, whose mailbox is empty. To read or send a real mailbox’s mail, log in as that mailbox instead: Read a mailbox’s mail

Mail server (native)

• GET
  /mail/session

  The JMAP session for your tenant, with every advertised URL pointing back at this API so one hostname serves the whole integration.

  mail:native
• POST
  /mail

  Send JMAP method calls straight to your mail server: mailboxes, domains, DKIM keys, aliases, app passwords and API keys. Your mail key authenticates at the mail server, which confines it to your tenant.

  mail:native
• GET
  /mail/download/{accountId}/{blobId}/{name}

  Download a JMAP blob through your API hostname. The tenant mail key is checked before the request is relayed.

  mail:native
• POST
  /mail/upload/{accountId}

  Upload a JMAP blob through your API hostname, subject to the smaller of the upload limits.

  mail:native
• GET
  /mail/events

  Open a bounded JMAP event stream through your API hostname.

  mail:native

Forwarders

Forwarders are system rules a mail key is deliberately never allowed to write, so they are created and changed here instead, scoped to this service alone.

Mail routing

• GET
  /forwarders

  List the mail forwarders configured for this service: source address, destination addresses, copy or redirect mode, and enabled state.

  forwarders:read
• GET
  /forwarders/{forwarder}

  Read one mail forwarder of this service by its id. A forwarder id from another service always returns 404.

  forwarders:read
• POST
  /forwarders

  Create a mail forwarder for this service only. The source address must belong to a domain this service already owns.

  forwarders:write
• PUT
  /forwarders/{forwarder}

  Change an existing forwarder belonging to this service. A forwarder id from another service always returns 404.

  forwarders:write
• DELETE
  /forwarders/{forwarder}

  Delete a forwarder belonging to this service. A forwarder id from another service always returns 404.

  forwarders:write

Errors and rate limits

Requests are limited to 60 per minute per token and source IP. Optional IP allow-lists are enforced on every endpoint.

Not in v1. Delivery and DMARC/TLS report reads are deliberately absent: they can only be served through the elevated provisioning credential, which needs its own security review first. Reseller and brand operations, and access to other services, are out of scope for this API entirely.

Deprecated endpoints

These read endpoints duplicate the mail API and stop working on October 17, 2026. Existing keys keep them until then.

• GET

  /service

  Your dashboard (billing details are not part of the mail API).

• GET

  /usage

  POST /mail with x:Account/get (quota and usage per mailbox).

• GET

  /storage

  Your dashboard (plan and add-on storage).

• GET

  /mailboxes

  POST /mail with x:Account/query and x:Account/get.

  Try the replacement Copy

  curl -H "Authorization: Bearer <your-mail-api-key>" \
       -H "Content-Type: application/json" \
       --data '{"using":["urn:ietf:params:jmap:core"],
                "methodCalls":[["x:Account/query",{},"a"]]}' \
       https://dash.mailbux.com/api/v1/mail

• GET

  /domains

  POST /mail with x:Domain/query and x:Domain/get.

  Try the replacement Copy

  curl -H "Authorization: Bearer <your-mail-api-key>" \
       -H "Content-Type: application/json" \
       --data '{"using":["urn:ietf:params:jmap:core"],
                "methodCalls":[["x:Domain/query",{},"a"]]}' \
       https://dash.mailbux.com/api/v1/mail

• GET

  /aliases

  POST /mail with x:Account/get (the aliases property).

• GET

  /dns

  Your dashboard (DNS records and live checks).

• GET

  /dkim

  POST /mail with x:DkimSignature/query and x:DkimSignature/get.