Manage White Label Teams with API and MCP

White Label accounts can be managed without switching back to the dashboard. The REST API and MCP server cover the account's setup status, clients and team members, roles, domain access, invitations, suspensions, removals, restores, client storage limits, and activity history. Branding is covered by the same White Label toolset and its own branding guide.

The important boundary is simple: a connection can never hand out more access than the person behind it already has. A domain-limited manager cannot invite someone to unrelated domains, and a custom role cannot grant permissions the caller does not hold.

What is available

The complete MCP catalog now contains 284 tools over stdio and up to 283 tools over hosted HTTP. White Label contributes 23 tools: seven for branding, 13 for account, member, and activity management, and three for client storage limits.

These tools are not loaded for everybody. TrekMail evaluates the account's live White Label entitlement, the person's current membership, the token or OAuth grant, any domain constraint, the selected toolsets, and local safety settings before building tools/list. A connection without White Label access does not receive the schemas at all.

Entitlement states

With White Label read access, call GET /api/v1/white-label or the get_white_label tool to distinguish active from read-only grace, and to see setup progress and the grace deadline. An unavailable account cannot call that endpoint: when a stored credential still names a White Label scope that the account can no longer use, the API returns scope_blocked_by_entitlement and explains where to reactivate it.

Scopes

The member activity endpoint needs both activity:read and members:read, because its response contains a member record as well as activity. The hosted OAuth connection uses the tools:white_label selector to request this tool family; the effective REST scopes are still capped by the account and membership.

For a self-hosted MCP server, add white_label to TREKMAIL_TOOLSETS when you use a toolset allow-list. Write tools also respect the local safety gates described below.

REST endpoints

All paths are under https://trekmail.net/api/v1.

Every write in this table requires an Idempotency-Key header. Repeating the same request with the same key returns the original safe result; one-time secrets in a replay, such as an invitation token, are redacted. Reusing a key with a different body returns idempotency_mismatch.

Read the access catalog first

Do not hard-code role permissions into an integration. Call the access catalog before an invitation or access change. Its grantable flags reflect the caller's current membership and can change when the owner adjusts that membership.

The roles currently offered for new invitations are:

• client — runs the assigned domains and mailboxes without seeing the reseller's private relationship with TrekMail.
• webmail_only — appears in the team list but receives no dashboard permissions.
• domain_admin — manages assigned domains and their DNS, not mailboxes.
• mailbox_operator — manages mailboxes inside assigned domains, not the domains themselves.
• read_only — can inspect the permitted account surface without changing it.
• custom — receives only the permissions listed in permissions.

Some roles require explicit domain_ids; others can use all_domains. The access catalog tells you which rule applies. If the caller tries to grant a broader role, permission, or domain set, TrekMail returns scope_blocked_by_membership instead of silently narrowing the invitation.

Invite a client

curl -s -X POST "https://trekmail.net/api/v1/white-label/members" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invite-northwind-admin-20260904" \
  -d '{
    "email": "admin@northwind.example",
    "role": "client",
    "all_domains": false,
    "domain_ids": [123, 124],
    "note": "Northwind primary contact"
  }'

The response includes the member, whether email delivery succeeded, and a one-time invitation URL. A delivery problem does not erase the invitation: the owner can copy the URL or resend it later.

For a custom role, read grantable_permissions from the access catalog and send the selected values in permissions. At least one permission is required.

Follow the member state

Every member response includes allowed_operations. Use that list instead of guessing:

• A pending invitation can be updated, suspended, resent, or removed.
• An active member can be updated, suspended, or removed.
• A suspended member can be updated, resumed, or removed.
• A removed member can be restored.
• The owner row is visible for context but cannot be changed through these endpoints.

The list is also filtered for the current caller. It is empty for a read-only connection, for the caller's own membership, and for members whose permissions are broader than the caller may manage.

Callers cannot remove or suspend themselves. Delegated callers also cannot manage a member whose access is broader than their own. Invalid transitions return membership_state_conflict with a hint to read the member again.

Suspending or removing someone revokes the API and mailbox keys created under that membership. Resuming or restoring the membership never brings those old keys back; the person must reconnect or create new credentials.

Activity and privacy boundaries

GET /white-label/activity returns invitations, role and domain changes, suspensions, removals, restores, and related security actions. Filter with action, member_id, and per_page.

GET /white-label/members/{id}/activity combines that member's account actions with recent sign-ins, including time, IP address, approximate location, browser, operating system, and device type. This route deliberately requires both read scopes. Domain-constrained callers can only request members that fall completely inside their domain boundary; an inaccessible member is returned as 404, so the endpoint does not reveal that another tenant or client exists.

Client storage limits

A client storage limit gives a client's domains one amount of space, in MB, for their mailboxes and Drive. See Give each client their own storage limit for how it works in the dashboard. A limit whose domains nobody on the team has, for example one created here before the client is invited, appears on the Team & clients page under Storage limits without a client.

• Reading takes members:read. A caller confined to some domains sees only the limits whose domains are all its own. Another client's limit, or one that also covers a domain outside its reach, is left out of the list and answers 404, like an id that does not exist.
• Changing takes members:write and a caller that reaches every domain of the account. A member confined to some domains gets 403 scope_blocked_by_membership; a key confined to some domains gets 403 token_resource_constrained.
• POST follows the Team page: domains without a limit get a new one (201); domains that already share one limit change it, and the given domains without a limit join it (200).
• PATCH takes storage_limit_mb, domain_ids, or both. domain_ids replaces the whole set, and domains left out go back to the account's storage.
• Each limit returns storage_limit_mb, domain_ids, allocated_mb (fixed mailbox sizes), pending_invites_mb (fixed sizes of open invitations), pool_mb (what mailboxes on shared storage share), used_bytes, and member_ids.

Every member record carries client_limit: the one limit all of the member's domains are under, as id, storage_limit_mb, allocated_mb and used_bytes, or null. For a caller confined to some domains it is also null when that limit covers a domain outside the caller's reach.

A mailbox's own size is set with PATCH /mailboxes/{id}/storage (mailboxes:write), or the set_mailbox_storage tool, described in the API overview.

MCP tools

Invitation tools require TREKMAIL_ALLOW_SENDING=true on self-hosted stdio MCP. Access-changing tools and the client storage limit tools require TREKMAIL_ALLOW_DESTRUCTIVE=true; removing a member or a limit also requires confirm_remove=true. set_mailbox_storage, outside the White Label toolset, has the same gate. These switches are local safety controls, not extra API permissions. Hosted MCP applies its own approved safety policy.

The tools create deterministic idempotency keys when you do not provide one. Supplying your own idempotency_key is useful when a workflow may restart in a different process.

A safe automation flow

1. Call get_white_label. Stop on scope_blocked_by_entitlement; in a successful grace response, continue only with reads.
2. Call get_white_label_access_catalog immediately before granting access.
3. List or read the target member before changing it.
4. Check allowed_operations, the intended role, permissions, and domain ids.
5. Use a stable idempotency key for the write.
6. Read the member again and report the resulting status and effective permissions.
7. Check White Label activity when you need an audit record of the change.

Errors that tell you what to do