Tenant-scoped REST endpoints for domains, mailboxes, aliases, groups, DKIM, account security, reports, recovery, and delivery diagnostics.
Authenticate once, keep the returned bearer token private, and send it in the Authorization header on every protected request. Principal endpoints use the same route for domains, accounts, groups, lists, roles, API keys, and OAuth clients; the object type controls what is created or filtered.
https://api.mailbux.comHeaderAuthorization: Bearer <access_token>Create the domain principal and publish DNS records.
Add individual principals with addresses and quotas.
Assign roles, groups, aliases, forwarders, and app passwords.
Check DKIM, reports, spam training, and diagnostics.
Get an access token, discover login metadata, and inspect the tenant-scoped permissions available to the caller.
/api/oauthStarts the OAuth authorization-code flow for a tenant administrator or authorized account owner.
curl -X POST "https://api.mailbux.com/api/oauth" \
-u "[email protected]:your-password" \
-H "Content-Type: application/json" \
-d '{
"type": "code",
"client_id": "mailbux-admin",
"redirect_uri": "https://api.mailbux.com/api/oauth/callback"
}'/auth/tokenExchanges the authorization code for an access token and refresh token used on protected API calls.
curl -X POST "https://api.mailbux.com/auth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=authorization_code" \
--data-urlencode "code=<auth_code>" \
--data-urlencode "client_id=mailbux-admin"/api/discover/{email}Returns sign-in metadata for the email domain, including the provider used by that organization.
/api/accountReturns the authenticated account, locale, edition, tenant context, and effective permissions.
Tenant administrators work inside their organization boundary. These calls expose profile, quota, and plan context when enabled for the account.
/api/accountUse the account descriptor as the first call after login to learn what the token can manage.
/api/principal?types=tenantReturns tenant principals visible to the caller. Most customer tokens only see their own organization.
/api/principal/{tenant_id}Updates tenant-owned metadata such as display name, logo, allowed roles, or quota fields when the permission is granted.
/userapi/account-planReturns the Mailbux plan, limits, and account-level usage visible to the signed-in customer.
Create domains first, then publish the DNS records returned by Mailbux before adding production mailboxes.
/api/principal?types=domainLists domains available in the caller tenant.
/api/principalCreates a domain principal that can later hold mailboxes, aliases, groups, and DKIM signing.
curl -X POST "https://api.mailbux.com/api/principal" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"type": "domain",
"name": "example.com",
"description": "Primary company domain"
}'/api/principal/{domain}Fetch domain details, update allowed fields, or delete a domain after dependent accounts have been removed.
/api/dns/records/{domain}Returns the MX, SPF, DKIM, DMARC, and verification records to publish for the domain.
/userapi/dkimGenerates and returns Mailbux DKIM signing records for a customer domain.
/api/dkimCreates a DKIM signature object for a domain when advanced DKIM management is enabled.
Mailboxes are individual principals. Aliases and catch-all addresses are additional values on the account email list.
/api/principal?types=individualLists individual mailboxes inside the tenant.
/api/principalCreates a mailbox with login name, password, addresses, quota, tenant, and roles.
curl -X POST "https://api.mailbux.com/api/principal" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"type": "individual",
"tenant": "example",
"name": "[email protected]",
"description": "Jane Doe",
"secrets": ["StrongPassword123!"],
"emails": ["[email protected]"],
"quota": 1073741824,
"roles": ["user"]
}'/api/principal/{email}Fetch mailbox details, change password or quota, suspend access, update membership, or delete the account.
/api/principal/{email}Adds an address to the account emails array, or removes it later.
curl -X PATCH "https://api.mailbux.com/api/principal/[email protected]" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '[{
"action": "addItem",
"field": "emails",
"value": "[email protected]"
}]'/api/principal/{email}Adds @example.com to an account so unmatched addresses at that domain deliver to the mailbox.
Groups can receive mail and expose a shared inbox to members. Mailing lists distribute mail to internal or external recipients.
/api/principal?types=group,listReturns collaboration groups and mailing lists visible to the tenant administrator.
/api/principalCreates a group principal with addresses, members, optional quota, and shared access behavior.
/api/principalCreates a mailing-list principal with internal members and optional external recipients.
/api/principal/{principal_id}Adds or removes members, addresses, roles, or list subscriptions from a group or mailing list.
/api/principal/{principal_id}Removes the group or mailing list principal from the tenant.
Forwarders route incoming messages from a Mailbux address to one or more external destinations.
/api/forwarders?domain={domain}Returns forwarders configured for a domain.
/api/forwardersCreates a forwarding rule with optional local mailbox copy.
curl -X POST "https://api.mailbux.com/api/forwarders" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"fromEmail": "[email protected]",
"to": "[email protected],[email protected]",
"keepLocal": true,
"description": "Info desk forwarding"
}'/api/forwarders/{id}Removes a forwarding rule by id.
Grant scoped automation access without sharing a user password.
/api/principal?types=role,apiKey,oauthClientLists roles, API keys, and OAuth clients visible to the tenant administrator.
/api/principalCreates a reusable permission bundle that can be assigned to users, groups, or API keys.
/api/principalCreates a tenant-scoped API key for automation. API keys are for management calls, not mailbox login.
/api/principalRegisters an OAuth client used by an internal app or trusted integration.
/api/principal/{principal_id}Updates secrets and permissions or removes the role, API key, or OAuth client.
Manage authentication factors, app passwords, suspended access, and encryption-at-rest preferences.
/api/account/authReturns the signed-in account authentication state, including app password and two-factor configuration where available.
/api/account/authAdds app passwords, updates password state, or changes two-factor authentication for the signed-in account.
/api/account/cryptoReturns the signed-in account encryption-at-rest configuration.
/api/account/cryptoUpdates the signed-in account encryption-at-rest mode when available on the plan.
/api/principal/{email}Uses permission fields to disable or restore authentication for a tenant mailbox.
Tenant admins can train filtering and review domain reports where their plan exposes those tools.
/api/spam-filter/train/spamUploads a raw message sample and marks it as unwanted mail for training.
/api/spam-filter/train/hamUploads a raw message sample and marks it as legitimate mail for training.
/api/spam-filter/train/{spam|ham}/{account_id}Applies a spam or not-spam training sample to one mailbox account.
/api/reports/dmarcReturns incoming DMARC aggregate reports for domains visible to the caller.
/api/reports/tlsReturns SMTP TLS reporting data for tenant domains.
/api/reports/arfReturns ARF feedback reports related to tenant traffic.
Recover messages that are still inside the account retention window.
/api/store/undelete/{account_id}Lists deleted messages that can still be restored for the account.
/api/store/undelete/{account_id}Restores selected deleted message records by hash and collection.
Read-only troubleshooting helpers for customer-owned domains and outbound delivery checks.
/api/troubleshoot/tokenIssues a short-lived token used by delivery diagnostic streams.
/api/troubleshoot/delivery/{recipient}Runs a delivery diagnostic for a recipient address using a short-lived token.
This page is limited to customer and tenant workflows. The following platform-only operations are not part of the public Mailbux end-user API reference.