Gestire i team White Label con API e MCP

Gli account White Label possono essere gestiti senza tornare alla dashboard. L'API REST e il server MCP coprono lo stato di configurazione dell'account, clienti e membri del team, ruoli, accesso ai domini, inviti, sospensioni, rimozioni, ripristini e cronologia delle attività. Il branding fa parte dello stesso set di strumenti White Label e dispone di una propria guida al branding.

Il limite importante è semplice: una connessione non può mai concedere più accesso di quello già posseduto dalla persona che la utilizza. Un responsabile limitato a determinati domini non può invitare qualcuno in domini non correlati e un ruolo personalizzato non può concedere autorizzazioni che il chiamante non possiede.

Funzionalità disponibili

Il catalogo MCP completo contiene ora 261 strumenti tramite stdio e fino a 260 strumenti tramite HTTP ospitato. White Label offre 20 strumenti: sette per il branding e 13 per la gestione di account, membri e attività.

Questi strumenti non vengono caricati per tutti. TrekMail valuta in tempo reale il diritto White Label dell'account, l'appartenenza attuale della persona, il token o la concessione OAuth, eventuali restrizioni di dominio, i set di strumenti selezionati e le impostazioni di sicurezza locali prima di creare tools/list. Una connessione senza accesso a White Label non riceve affatto gli schemi.

Stati del diritto

Con accesso in lettura a White Label, chiama GET /api/v1/white-label o lo strumento get_white_label per distinguere active dalla modalità grace in sola lettura e per visualizzare l'avanzamento della configurazione e la scadenza del periodo di tolleranza. Un account non disponibile non può chiamare questo endpoint: quando una credenziale memorizzata include ancora un ambito White Label che l'account non può più utilizzare, l'API restituisce scope_blocked_by_entitlement e spiega dove riattivarlo.

Ambiti

L'endpoint delle attività di un membro richiede sia activity:read sia members:read, perché la risposta contiene un record del membro oltre all'attività. La connessione OAuth ospitata utilizza il selettore tools:white_label per richiedere questa famiglia di strumenti; gli ambiti REST effettivi restano comunque limitati dall'account e dall'appartenenza.

Per un server MCP in hosting autonomo, aggiungi white_label a TREKMAIL_TOOLSETS quando utilizzi un elenco consentito di set di strumenti. Gli strumenti di scrittura rispettano anche le protezioni di sicurezza locali descritte di seguito.

Endpoint REST

Tutti i percorsi si trovano sotto https://trekmail.net/api/v1.

Ogni scrittura in questa tabella richiede un header Idempotency-Key. La ripetizione della stessa richiesta con la stessa chiave restituisce il risultato sicuro originale; i segreti monouso presenti in una ripetizione, come un token di invito, vengono oscurati. Il riutilizzo di una chiave con un corpo diverso restituisce idempotency_mismatch.

Leggere prima il catalogo degli accessi

Non inserire direttamente nel codice di un'integrazione le autorizzazioni dei ruoli. Chiama il catalogo degli accessi prima di un invito o di una modifica dell'accesso. I suoi indicatori grantable riflettono l'appartenenza attuale del chiamante e possono cambiare quando il proprietario modifica tale appartenenza.

I ruoli attualmente disponibili per i nuovi inviti sono:

• client - gestisce i domini e le caselle di posta assegnati senza vedere il rapporto privato del rivenditore con TrekMail.
• webmail_only - compare nell'elenco del team, ma non riceve autorizzazioni per la dashboard.
• domain_admin - gestisce i domini assegnati e i relativi DNS, ma non le caselle di posta.
• mailbox_operator - gestisce le caselle di posta nei domini assegnati, ma non i domini stessi.
• read_only - può esaminare l'area consentita dell'account senza modificarla.
• custom - riceve solo le autorizzazioni elencate in permissions.

Alcuni ruoli richiedono domain_ids espliciti; altri possono utilizzare all_domains. Il catalogo degli accessi indica quale regola si applica. Se il chiamante tenta di concedere un ruolo, un'autorizzazione o un insieme di domini più ampio, TrekMail restituisce scope_blocked_by_membership invece di restringere silenziosamente l'invito.

Invitare un cliente

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"
  }'

La risposta include il membro, indica se la consegna dell'e-mail è riuscita e fornisce un URL di invito monouso. Un problema di consegna non elimina l'invito: il proprietario può copiare l'URL o inviarlo nuovamente in seguito.

Per un ruolo personalizzato, leggi grantable_permissions dal catalogo degli accessi e invia i valori selezionati in permissions. È richiesta almeno un'autorizzazione.

Seguire lo stato del membro

Ogni risposta relativa a un membro include allowed_operations. Usa questo elenco invece di fare supposizioni:

• Un invito in sospeso può essere aggiornato, sospeso, inviato nuovamente o rimosso.
• Un membro attivo può essere aggiornato, sospeso o rimosso.
• Un membro sospeso può essere aggiornato, riattivato o rimosso.
• Un membro rimosso può essere ripristinato.
• La riga del proprietario è visibile come contesto, ma non può essere modificata tramite questi endpoint.

L'elenco viene inoltre filtrato per il chiamante corrente. È vuoto per una connessione in sola lettura, per l'appartenenza del chiamante stesso e per i membri le cui autorizzazioni sono più ampie di quelle che il chiamante può gestire.

I chiamanti non possono rimuovere o sospendere se stessi. I chiamanti delegati non possono inoltre gestire un membro il cui accesso sia più ampio del proprio. Le transizioni non valide restituiscono membership_state_conflict con un suggerimento per rileggere il membro.

La sospensione o la rimozione di una persona revoca le chiavi API e delle caselle di posta create nell'ambito di tale appartenenza. La riattivazione o il ripristino dell'appartenenza non recupera mai le vecchie chiavi; la persona deve riconnettersi o creare nuove credenziali.

Limiti di attività e privacy

GET /white-label/activity restituisce inviti, modifiche di ruolo e dominio, sospensioni, rimozioni, ripristini e azioni di sicurezza correlate. Filtra con action, member_id e per_page.

GET /white-label/members/{id}/activity combina le azioni del membro sull'account con gli accessi recenti, inclusi ora, indirizzo IP, posizione approssimativa, browser, sistema operativo e tipo di dispositivo. Questa route richiede deliberatamente entrambi gli ambiti di lettura. I chiamanti con restrizioni di dominio possono richiedere solo membri che rientrano completamente nel proprio limite di domini; un membro inaccessibile viene restituito come 404, in modo che l'endpoint non riveli l'esistenza di un altro tenant o cliente.

Strumenti MCP

Gli strumenti di invito richiedono TREKMAIL_ALLOW_SENDING=true su MCP stdio in hosting autonomo. Gli strumenti che modificano l'accesso richiedono TREKMAIL_ALLOW_DESTRUCTIVE=true; la rimozione richiede anche confirm_remove=true. Queste opzioni sono controlli di sicurezza locali, non autorizzazioni API aggiuntive. MCP ospitato applica una propria politica di sicurezza approvata.

Gli strumenti creano chiavi di idempotenza deterministiche quando non ne fornisci una. Specificare un proprio idempotency_key è utile quando un flusso di lavoro potrebbe riavviarsi in un processo diverso.

Un flusso di automazione sicuro

1. Chiama get_white_label. Fermati in caso di scope_blocked_by_entitlement; in una risposta grace riuscita, continua solo con operazioni di lettura.
2. Chiama get_white_label_access_catalog immediatamente prima di concedere l'accesso.
3. Elenca o leggi il membro di destinazione prima di modificarlo.
4. Controlla allowed_operations, il ruolo previsto, le autorizzazioni e gli ID dei domini.
5. Usa una chiave di idempotenza stabile per la scrittura.
6. Leggi nuovamente il membro e comunica lo stato risultante e le autorizzazioni effettive.
7. Controlla l'attività White Label quando è necessario un record di audit della modifica.

Errori che indicano cosa fare