Ambiti API e autorizzazioni dei piani

Gli ambiti controllano esattamente ciò che può fare un token API. Ogni token contiene un insieme di ambiti e l’API li verifica a ogni richiesta.

Come funzionano gli ambiti

Quando crei un token, selezioni gli ambiti da includere. L’API applica tre limiti massimi a ogni richiesta:

1. Diritti dell’account: il piano attuale e gli add-on attivi determinano quali funzionalità sono disponibili in quel momento.
2. Appartenenza: una persona con accesso delegato non può concedere o usare più di quanto consentito dal proprio ruolo e accesso ai domini.
3. Concessione delle credenziali: il token o il consenso OAuth deve includere l’ambito richiesto dall’endpoint.

L’errore identifica il limite non superato. insufficient_scope indica che l’ambito non è mai stato concesso alla credenziale, scope_blocked_by_membership indica che il ruolo della persona è più ristretto e scope_blocked_by_entitlement indica che il diritto White Label richiesto non è attivo.

Due livelli di ambiti: OAuth e ambiti API

OAuth supporta sei comodi gruppi legacy, tutti gli ambiti API granulari e i selettori tools:* che controllano solo l’esposizione. I gruppi legacy sono:

Ogni gruppo OAuth legacy si espande in ambiti API granulari, come domains:read e drive:account:write. Le nuove integrazioni possono richiedere direttamente questi ambiti. Gli ambiti White Label sono deliberatamente assenti dai vecchi gruppi mail:*, quindi un connettore esistente non ottiene mai l’amministrazione da rivenditore dopo un aggiornamento. Deve richiedere esplicitamente gli ambiti White Label necessari. Un selettore tools:white_label limita l’esposizione in MCP, ma non concede da solo alcuna autorizzazione API.

Tre modalità di connessione e come concedono le funzionalità

Esistono tre modi in cui un agente o un’integrazione può accedere a TrekMail, e il meccanismo di controllo è diverso in ciascuno. È importante perché gli "indicatori di funzionalità" MCP (TREKMAIL_ALLOW_DESTRUCTIVE, TREKMAIL_ALLOW_SENDING, TREKMAIL_ALLOW_MIGRATION) esistono soltanto in uno di essi.

In sintesi: MCP HTTP ospitato filtra gli strumenti annunciati in base alla credenziale OAuth; MCP stdio combina gli ambiti del token con i set di strumenti, la modalità di sola lettura e i controlli di sicurezza locali; l’API REST è controllata direttamente dagli ambiti granulari presenti nel token. L’autorizzazione API in fase di esecuzione rimane decisiva in tutte le modalità.

Riferimento degli ambiti

Account e fatturazione

billing:autopay è l’unico ambito che trasferisce denaro, quindi vale la pena leggerlo due volte.

È deliberatamente separato da billing:read: una connessione autorizzata a vedere la fattura non deve poterla aumentare, e concedere la lettura della fatturazione non significa acconsentire alla spesa. Non viene mai incluso automaticamente, un token o una connessione lo possiede solo se lo hai concesso esplicitamente, ed è assente da tutti i vecchi gruppi di ambiti generici, quindi una connessione autorizzata prima della sua introduzione non può spendere nulla.

Cosa consente: acquistare crediti di verifica e-mail e avviare un abbonamento. Cosa non consente, in alcun modo: annullare, effettuare il downgrade o modificare un abbonamento esistente. Non esistono endpoint per queste operazioni. La spesa è inoltre limitata per acquisto, giorno e mese per l’intero account, indipendentemente dal numero di connessioni che possiedono l’ambito.

È disponibile per tutti i piani perché i crediti di verifica sono venduti per tutti i piani, incluso Nano.

Domini

La consegna tramite alias di dominio è disponibile a partire da Starter. I token Starter possono leggere lo stato salvato e attuale; collegare, modificare o rimuovere tramite API/MCP richiede la funzionalità domains:write di Pro/Agency. Le modifiche nel pannello rimangono disponibili con Starter. Consulta Alias di dominio tramite API e MCP.

White Label

Questi ambiti dei token operativi compaiono solo quando è attiva una prova o un add-on White Label a pagamento. Durante il periodo di tolleranza dopo la cancellazione, il proprietario mantiene gli ambiti di lettura; i membri delegati e tutti gli ambiti di scrittura vengono rimossi.

L’appartenenza attuale applica un ulteriore limite. Un cliente o collega non può mai ampliare il proprio ruolo, l’accesso ai domini o le autorizzazioni personalizzate creando un token più ampio. Consulta Gestire i team White Label con API e MCP.

Caselle di posta

Messaggi (token dei messaggi)

Gli ambiti dei messaggi sono contenuti nei token dei messaggi (prefisso tm_msg_), non nei token operativi (prefisso tm_live_). I token dei messaggi vengono creati tramite l’API usando un token operativo con l’ambito mailboxes:message-tokens:manage. Hanno protezioni specifiche dell’API oltre ai normali limiti del percorso di invio: per impostazione predefinita, le letture consentono 30 richieste al minuto e 5,000 letture riuscite al giorno per token; l’invio consente 60 richieste al minuto per token e 100 invii API al giorno per l’intera casella. Un secondo contatore di sicurezza del token ha un valore predefinito di 500 invii al giorno, quindi normalmente prevale il limite inferiore della casella.

Tutti i nuovi endpoint dell’API webmail (contatti, calendario, identità, modelli, mittenti bloccati, bozze, invii programmati, cartelle, allegati) corrispondono ai tre ambiti dei messaggi esistenti; non sono stati aggiunti nuovi ambiti. I token esistenti continuano a funzionare senza modifiche.

messages:read non concede l’accesso in scrittura. In OAuth ospitato, l’approvazione della funzionalità più ampia messages:send fornisce insieme accesso in lettura, scrittura e invio; un token tm_msg_ creato manualmente mantiene esattamente gli ambiti selezionati alla creazione.

Ticket di assistenza

Starter: sola lettura tramite API. Apri e rispondi ai ticket dal pannello.

Configurazione SMTP

SMTP è configurato per dominio (/api/v1/domains/{id}/smtp), con un’unica impostazione predefinita per l’intero account (/api/v1/smtp/default) che determina il punto di partenza dei nuovi domini. Consulta Panoramica dell’API per l’elenco completo degli endpoint. Gli endpoint legacy a livello di account /api/v1/smtp continuano a rispondere per compatibilità, ma non controllano più il percorso.

Migrazioni

Gli ambiti di migrazione sono contenuti nei token operativi (prefisso tm_live_). Starter può visualizzare le migrazioni tramite l’API ed eseguirle dal pannello. Pro e Agency possono anche avviare, annullare, riprovare ed eliminare migrazioni tramite API e MCP.

Cloudflare

Drive

Gli ambiti Drive appartengono ai token operativi. Un token può essere limitato a caselle selezionate e Drive nasconderà a quel token gli altri spazi delle caselle. Acquisto, ridimensionamento e cancellazione dell’add-on Drive non sono operazioni di scrittura API/MCP; le modifiche di fatturazione restano nel pannello.

Nano + add-on Drive: con un add-on di archiviazione Drive attivo, Nano ottiene l’intero insieme di ambiti Drive. Non viene sbloccato altro: solo Drive e gli ambiti Verificatore e-mail già disponibili per Nano. Se annulli l’add-on, gli ambiti di lettura restano attivi durante il periodo di tolleranza di 7 giorni per consentirti di completare i download o la migrazione; scrittura, condivisione ed eliminazione definitiva vengono interrotte immediatamente.

Verificatore e-mail

Gli ambiti Verificatore e-mail sono disponibili per tutti i piani, incluso Nano. L’unico limite è il saldo dei crediti. Consulta API Verificatore e-mail per il riferimento completo degli endpoint.

Livelli di accesso dei piani

Gli ambiti White Label sono aggiuntivi e non fanno parte del piano base Pro o Agency. Compaiono per questi account solo quando il relativo diritto White Label è attivo.

Cosa accade dopo un downgrade

Se effettui il downgrade da Pro a Starter, i token esistenti con ambiti di scrittura non vengono eliminati. L’API blocca invece in fase di esecuzione le richieste che usano ambiti non consentiti.

Ad esempio, un token con mailboxes:create in un piano Starter riceverà 403 con il codice token_scope_blocked_by_plan quando prova a creare una casella. Gli ambiti di lettura sullo stesso token continueranno a funzionare.

Per risolvere il problema, revoca il vecchio token e creane uno nuovo con i soli ambiti consentiti dal piano attuale.

Ambiti pericolosi

Gli ambiti mailboxes:delete, domains:delete, migrations:write e cloudflare:delete sono contrassegnati come pericolosi nel pannello. I token con questi ambiti possono avviare l’eliminazione di caselle o domini, rimuovere token Cloudflare o eseguire altre azioni irreversibili. Valuta se il tuo caso d’uso ne ha davvero bisogno.

Per un server MCP ospitato localmente, l’amministratore può richiedere TREKMAIL_ALLOW_DESTRUCTIVE=true prima che gli strumenti di eliminazione siano disponibili. MCP ospitato usa gli ambiti approvati durante OAuth.

L’ambito messages:send consente di inviare e-mail reali dalla casella. In un server MCP ospitato localmente, l’invio può anche richiedere TREKMAIL_ALLOW_SENDING=true e confirm_send=true a ogni chiamata. Consulta Protezioni di sicurezza e intenti di eliminazione per i dettagli.

L’ambito migrations:write consente di avviare migrazioni e-mail che si connettono a server IMAP esterni usando credenziali salvate. In un server MCP ospitato localmente, la scrittura delle migrazioni può anche richiedere TREKMAIL_ALLOW_MIGRATION=true e parametri di conferma per ogni chiamata (confirm_start, confirm_cancel, confirm_retry).

Vincoli di dominio

Gli ambiti controllano cosa può fare un token. I vincoli di dominio controllano dove può farlo.

Un token limitato a domini specifici può vedere e modificare solo le risorse all’interno di tali domini. È utile per concedere a un collaboratore o agente l’accesso al dominio di un singolo cliente senza esporre gli altri.

I controlli degli ambiti avvengono prima dei controlli dei vincoli di dominio. Se un token non possiede l’ambito richiesto, la richiesta non riesce con 403 indipendentemente dai vincoli di dominio.

Soluzioni rapide

• 403 "insufficient_scope": il token non possiede l’ambito richiesto per questo endpoint. Crea un nuovo token con gli ambiti corretti.
• 403 "token_scope_blocked_by_plan": il piano non consente più uno o più ambiti del token. Aggiorna il piano oppure revoca il token e creane uno nuovo con ambiti consentiti.
• 403 "scope_blocked_by_entitlement": White Label non è attivo oppure è stata tentata una scrittura durante il periodo di tolleranza dopo la cancellazione. Riattivalo prima di autorizzare nuovamente la connessione.
• 403 "scope_blocked_by_membership": il ruolo del membro attuale o l’autorizzazione personalizzata non consente l’azione. Chiedi al proprietario dell’account di modificare l’appartenenza.
• Alcuni ambiti sono nascosti nel modulo di creazione: il piano non supporta questi ambiti. Vengono mostrati solo quelli consentiti.