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, 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 261 tools over stdio and up to 260 tools over hosted HTTP. White Label contributes 20 tools: seven for branding and 13 for account, member, and activity management.

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.

MCP tools

Invitation tools require TREKMAIL_ALLOW_SENDING=true on self-hosted stdio MCP. Access-changing tools require TREKMAIL_ALLOW_DESTRUCTIVE=true; removal also requires confirm_remove=true. 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