Creazione e gestione dei token API

I token API controllano cosa può fare un'applicazione o un agente nel tuo account. Ogni token ha un nome, degli ambiti, vincoli di dominio facoltativi e una data di scadenza.

Vuoi collegare un client MCP? Se supporta l'autorizzazione nel browser, aggiungi https://trekmail.net/mcp come server MCP remoto e approva l'accesso nel browser. In genere non è necessario creare o incollare un token. I token tm_live_ manuali sono destinati a script, processi CI, MCP in hosting autonomo e client che non supportano questo flusso. Consulta Collegare agenti IA (MCP).

Prima di iniziare

• Tutti i piani, compreso Nano, possono creare token API. I piani Nano sono limitati agli ambiti Email Verifier (verify:read, verify:write).
• I piani Starter consentono ambiti dell'infrastruttura di sola lettura, oltre agli ambiti completi di Drive ed Email Verifier. Starter può anche gestire l'inoltro nella dashboard, ma l'accesso in scrittura all'inoltro tramite API (mailboxes:forwarding:write) richiede Pro o Agency. Pro e Agency abilitano tutti gli ambiti.
• Il proprietario può gestire tutte le credenziali dell'account. Un membro delegato autorizzato per i token API può gestire soltanto le credenziali che ha creato e concedere solo ambiti e domini già presenti nella sua appartenenza.
• Suggerimento: Fai clic su Avvia tour nella pagina Agenti IA e API per una breve panoramica su opzioni di connessione, token, app collegate e registro di controllo.

Creare un token di automazione Drive

L'API Drive e gli strumenti MCP usano token operativi (tm_live_...). Seleziona soltanto gli ambiti Drive necessari al flusso di lavoro:

• Report di sola lettura: drive:account:read, drive:mailbox:read o drive:addon:read.
• Automazione dei caricamenti: aggiungi drive:account:write o drive:mailbox:write.
• Link pubblici di consegna: aggiungi drive:account:share o drive:mailbox:share.
• Pulizia permanente: usa drive:account:purge o drive:mailbox:purge soltanto in un token separato e sottoposto a rigidi controlli.

L'acquisto, il ridimensionamento e l'annullamento dell'add-on Drive non sono disponibili tramite token API. Gli agenti possono leggere lo stato e i prezzi dell'add-on con drive:addon:read, ma le modifiche all'abbonamento restano nella dashboard.

Creare un token di automazione White Label

White Label usa cinque ambiti dei token operativi: branding:read, branding:write, members:read, members:write e activity:read. Compaiono soltanto quando l'account dispone dell'accesso White Label. members:write è contrassegnato come pericoloso perché può rimuovere l'accesso e revocare le chiavi di un'altra persona.

Per un'integrazione di stato e controllo in sola lettura, seleziona branding:read, members:read e activity:read. Aggiungi branding:write solo per la configurazione del marchio e del DNS. Aggiungi members:write soltanto se l'automazione deve invitare o modificare persone.

Durante il periodo di tolleranza per l'annullamento, il proprietario mantiene i tre ambiti di lettura per il recupero, mentre le operazioni di scrittura e le credenziali White Label delegate smettono di funzionare. La riattivazione non ripristina una credenziale revocata; creane o autorizzane una nuova.

Creare un token

1. Vai a Agenti IA e API → Token.
2. Fai clic su Crea token.
3. Compila il modulo:
   • Nome: Un'etichetta per identificare il token (ad esempio, "Agente Claude", "Pipeline CI/CD").
   • Scadenza: Scegli 7 giorni, 30 giorni, 90 giorni, una data personalizzata o mai.
   • Ambiti: Seleziona le operazioni che il token può eseguire. Tutti gli ambiti consentiti sono selezionati per impostazione predefinita.
   • Vincolo di dominio: Scegli "Tutti i domini" o seleziona domini specifici per limitare l'accesso del token.
4. Fai clic su Crea token.

Dopo la creazione, il token in testo normale viene mostrato una sola volta. Copialo immediatamente o usa il pulsante Scarica per salvarlo come file .txt.

Il token non può essere visualizzato di nuovo. Salvalo in modo sicuro prima di chiudere la conferma.

Creare un token messaggio

I token messaggio consentono agli agenti di leggere e inviare email da una casella specifica. Sono separati dai token operativi e vengono creati a livello di programmazione tramite l'API usando il token operativo.

Per creare un token messaggio, l'agente chiama:

curl -s -X POST \
  -H "Authorization: Bearer tm_live_your_ops_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-message-token-my-agent" \
  -d '{"name":"my-agent","scopes":["messages:read","messages:send"]}' \
  https://trekmail.net/api/v1/mailboxes/{MAILBOX_ID}/message-tokens

Scegli gli ambiti minimi richiesti dal flusso di lavoro:

Il token in testo normale (tm_msg_...) viene restituito una sola volta. Aggiungilo alla configurazione MCP come TREKMAIL_MESSAGE_TOKEN.

I token messaggio sono disponibili nei piani Pro e Agency. Il token operativo deve avere l'ambito mailboxes:message-tokens:manage.

Per una casella Gmail collegata o un'altra casella esterna, usa external_account_id. Per fare in modo che i destinatari vedano invece un indirizzo aziendale autorizzato, usa anche un identity_id restituito dall'endpoint delle identità. Consulta Indirizzi Invia come tramite API e MCP.

Formato dei token

TrekMail usa due prefissi per distinguere i tipi di token:

I primi 8 caratteri dopo il prefisso vengono memorizzati come prefisso visibile nella dashboard per facilitare l'identificazione.

Ambiti

Gli ambiti controllano cosa può fare il token. Le opzioni disponibili dipendono dal piano:

• Nano: Solo Email Verifier (verify:read, verify:write). L'aggiunta di Drive Storage fornisce inoltre all'account le funzionalità dell'API Drive e MCP a cui ha diritto.
• Starter: Accesso completo a Drive ed Email Verifier e accesso di sola lettura a tutto il resto (domini, caselle, inoltro, filtri email, risposta automatica, migrazioni, ticket, SMTP, Cloudflare). Usa la dashboard per le operazioni di scrittura che Starter non espone tramite API, come creare migrazioni, rispondere ai ticket o modificare la risposta automatica.
• Pro e Agency: Accesso completo. Lettura, scrittura, creazione ed eliminazione in tutte le famiglie, oltre ai token messaggio per leggere e inviare email tramite API.

Gli ambiti White Label sono un diritto dell'add-on e non una scorciatoia nella tabella dei piani. Vengono offerti solo quando White Label è attivo; il proprietario mantiene l'accesso di recupero in sola lettura durante il periodo di tolleranza per l'annullamento.

Consulta Ambiti API e permessi dei piani per il riferimento relativo a ogni ambito.

Vincoli di dominio

Per impostazione predefinita, i token possono accedere a tutti i domini dell'account. Per limitare un token a domini specifici:

1. Seleziona Domini selezionati nella sezione dei vincoli di dominio.
2. Seleziona i domini a cui deve accedere il token.

Un token vincolato riceve risposte 404 quando tenta di accedere a risorse di altri domini; l'API si comporta come se tali domini non esistessero.

Revocare un token

1. Vai a Agenti IA e API → Token.
2. Trova il token nell'elenco.
3. Fai clic su Revoca.
4. Conferma la revoca.

I token revocati smettono immediatamente di funzionare. Qualsiasi richiesta API che usa un token revocato riceve 401 Unauthorized.

La revoca è permanente e non può essere annullata. Crea un nuovo token se devi ripristinare l'accesso.

Stato del token

I token hanno tre stati:

Usa il filtro di stato nella pagina Token per visualizzare i token in base allo stato.

Registro di controllo

Ogni creazione e revoca di un token appare nella scheda Registro di controllo. Gli eventi includono il nome del token, l'azione e l'ora.

Soluzioni rapide

• "Ambiti non disponibili nel tuo piano": Il piano non include tali ambiti. Nano resta limitato a verify:read e verify:write (aggiungi l'add-on Drive Storage per ottenere anche gli ambiti drive:*). Starter aggiunge l'accesso in lettura in tutte le famiglie dell'infrastruttura, oltre all'accesso completo a Drive ed Email Verifier. Pro e Agency abilitano la scrittura ovunque.
• Token in testo normale smarrito: Il token non può essere recuperato. Revocalo e creane uno nuovo.
• Il token funziona ma restituisce 404 per alcuni domini: Probabilmente ha un vincolo di dominio. Revocalo e ricrealo con "Tutti i domini" oppure aggiungi i domini mancanti al vincolo.
• Un ambito White Label restituisce scope_blocked_by_entitlement: Riattiva White Label, quindi crea o autorizza una credenziale con l'ambito richiesto.
• Un token delegato ha smesso di funzionare dopo una modifica del ruolo: La riduzione, la sospensione o la rimozione dell'accesso del membro revoca immediatamente le credenziali interessate. Crea un nuovo token dopo che il proprietario ha ripristinato l'accesso corretto.