Creazione e gestione dei token API

Apri TrekMail in Claude, scegli Connect, accedi e autorizza l’accesso. Non devi creare un token API. Controlla i permessi o scollega l’app in Agenti IA e API → Token → App collegate.

Il tuo marchio White Label: usa l’indirizzo MCP del tuo pannello personalizzato e assegna al connettore il nome del marchio. Aggiungilo come custom connector; la pagina pubblica TrekMail usa l’accesso TrekMail e non sostituisce il collegamento del tuo marchio.

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).

Leggere le email con una sola chiave

Su Pro e Agency, scegli Leggi email quando crei una chiave API. Il permesso esplicito è mailboxes:messages:read; mailboxes:read mostra solo indirizzi e dati di configurazione. Tutte le caselle include quelle attuali e future; puoi invece limitare l’accesso a domini e caselle selezionati. Le chiavi esistenti non ricevono nuovi permessi automaticamente.

Usa la chiave dell’account con le rotte GET qui sotto. Invio, eliminazione e modifiche richiedono ancora credenziali e permessi separati per i messaggi. MCP ospitato accetta OAuth, non tm_live_ o tm_msg_. L’errore sul tipo di token indica all’agente la rotta o l’autorizzazione corretta.

GET /api/v1/mailboxes/{mailbox}/messages
GET /api/v1/mailboxes/{mailbox}/folders
GET /api/v1/mailboxes/{mailbox}/messages/{uid}
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/raw
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/attachments/{index}

Scegliere e modificare i permessi dell’app

Apri i dettagli di una chiave API o app collegata, scegli Modifica accesso, controlla e conferma. Il segreto della chiave API resta uguale. Ridurre permessi, risorse o durata limita anche i token delle caselle esistenti e annulla gli invii non iniziati. Le nuove connessioni OAuth possono essere limitate subito; ampliare l’accesso richiede una nuova approvazione. Modificare una connessione precedente la scollega e salva le scelte per riconnetterla. I token dei messaggi possono solo perdere permessi o scadere prima.

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 (attuali e futuri)", "Solo i domini selezionati" oppure "Tutti i domini (attuali e futuri) tranne…" per escludere alcuni domini.
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, compresi quelli che aggiungerai in seguito. Due opzioni restringono l'accesso:

• Solo i domini selezionati: il token raggiunge i domini selezionati e nient'altro. Un dominio aggiunto in seguito resta escluso finché non modifichi il token e lo selezioni.
• Tutti i domini (attuali e futuri) tranne…: il token raggiunge tutti i domini tranne quelli selezionati, compresi quelli aggiunti in seguito. Utile per tenere i tuoi agenti lontani dalla posta di un cliente senza modificare il token a ogni nuovo dominio.

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. In entrambi i casi il token non può nemmeno modificare impostazioni valide per l'intero account che riguarderebbero domini fuori dalla sua portata, come l'impostazione predefinita per le nuove caselle.

Per un membro del team limitato ad alcuni domini, "tranne…" indica i domini di quel membro meno quelli selezionati; i domini aggiunti in seguito all'account non sono inclusi. Se elimini un dominio escluso e lo aggiungi di nuovo, conta come un nuovo dominio: escludilo di nuovo.

Rigenerare un token

Rigenera un token quando ti serve di nuovo il suo segreto o se il segreto potrebbe essere trapelato. Il token mantiene nome, permessi, domini, caselle, scadenza e cronologia di controllo. Cambia solo il segreto.

1. Vai a Agenti IA e API → Token e apri i Dettagli del token.
2. Fai clic su Rigenera.
3. Scegli quando il vecchio segreto smette di funzionare: Subito, Tra 1 ora, Tra 24 ore, Tra 3 giorni o Tra 7 giorni. Il vecchio segreto non funziona mai oltre la scadenza del token stesso.
4. Fai clic su Rigenera e copia il nuovo segreto. Come per un nuovo token, viene mostrato una sola volta.

Finché il vecchio segreto funziona, i dettagli del token mostrano fino a quando e offrono Disattiva ora. Sostituisci il segreto in ogni app entro quella data: le richieste che usano ancora il vecchio segreto ricevono poi 401 Unauthorized.

I token messaggio (tm_msg_...) creati con il vecchio segreto smettono di funzionare nello stesso momento. Un'app che crea da sé i propri token messaggio può crearne di nuovi con il nuovo segreto. Se il segreto potrebbe essere trapelato, scegli Subito.

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, rigenerazione 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, ma puoi rigenerarlo: apri i suoi Dettagli, fai clic su Rigenera e copia il nuovo segreto. Il token mantiene le sue impostazioni.
• Il token funziona ma restituisce 404 per alcuni domini: Probabilmente ha un vincolo di dominio. Apri Dettagli del token, scegli Modifica accesso e aggiungi i domini mancanti, oppure passa a "Tutti i domini (attuali e futuri)" o a "Tutti i domini (attuali e futuri) tranne…".
• 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.