Password per le app di posta via API e MCP

L’API REST e MCP permettono di elencare, creare, sostituire e revocare le password per le app di una casella normale, modificarne la modalità di accesso delle app di posta e impostare la modalità predefinita dell’account per le caselle future. Questa pagina è il riferimento per le integrazioni. Per le istruzioni della dashboard e della webmail, consulta Password per le app di posta sui tuoi dispositivi.

Una password per le app apre IMAP, SMTP sulle porte 465 e 587, ManageSieve e CalDAV/CardDAV. Non apre mai la nuova webmail o la dashboard. La webmail classica accede tramite IMAP e accetta password per le app. La 2FA della casella protegge solo l’accesso alla nuova webmail; le app di posta e la webmail classica non chiedono mai il suo codice.

La funzionalità non ha un vincolo di piano separato per le caselle. Restano validi i permessi dei piani per API e MCP; consulta Ambiti e permessi API.

Autenticazione, ambiti e permessi dei membri

Usa un token Bearer per le richieste REST in /api/v1. Le scritture JSON usano Content-Type: application/json e un’intestazione Idempotency-Key.

Il permesso di impostare la password viene verificato sul ruolo del membro, oltre all’ambito API del token. Questo vale per i token dei membri e i connettori autorizzati dai membri. Il token di un proprietario non richiede un ambito aggiuntivo per impostare le password. Se il membro non ha il permesso, viene restituito 403 scope_blocked_by_membership.

I connettori OAuth ospitati possono usare gli ambiti delle funzionalità REST corrispondenti. Con i gruppi di ambiti legacy, mail:read fornisce mailboxes:read e account:read; mail:write fornisce anche mailboxes:write. L’espansione degli ambiti non prevale mai sulle regole dei permessi dei membri o sulle operazioni riservate al proprietario.

Si applicano i vincoli domain_ids e mailbox_ids del token, anche alle selezioni in blocco. Gli endpoint delle password per le app ed entrambi gli endpoint delle modalità restituiscono 404 not_found quando la funzionalità è disattivata, dopo i controlli di autenticazione e middleware. Anche una casella inaccessibile o inesistente restituisce 404: non interpretare ogni 404 come un’indicazione sullo stato della funzionalità.

Panoramica degli endpoint

I percorsi seguenti includono il prefisso /api/v1. {mailbox} è l’ID della casella normale; {id} è l’ID di una voce di password per le app che le appartiene.

Tutte le scritture di questa tabella richiedono Idempotency-Key. L’endpoint della password è un’operazione di reimpostazione amministrativa esistente, distinta dalla rotazione delle password per le app.

Elencare le password per le app e comprendere i campi delle voci

GET /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token

La risposta contiene al livello principale mailbox_id, client_auth_mode, limit, active_count e data, un array di voci. limit è pari a 25 password attive per casella. Le voci attive vengono prima, dalla più recente; quelle revocate restano visibili per 90 giorni. Nessuna risposta di elenco contiene un segreto.

Ogni voce contiene:

I motivi di revoca pubblici sono revoked, rotated, mailbox_password_reset, mailbox_password_changed, login_suspended, converted_to_shared e mailbox_trashed. L’elenco esclude le credenziali generate internamente dalla piattaforma.

Creare una password per le app

POST /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: app-password-42-office-pc-001

{"name":"Outlook on the office PC"}

name è obbligatorio: da 1 a 64 caratteri stampabili. Le sequenze di spazi vengono ridotte a un solo spazio. La casella deve essere normale e attiva, con accesso non sospeso e meno di 25 password per le app attive.

La risposta 201 contiene la voce completa in data, aggiunge data.password e include message. Per esempio, questi sono i campi delle credenziali nella risposta:

{
  "data": {
    "id": 81,
    "mailbox_id": 42,
    "name": "Outlook on the office PC",
    "password": "abcdefghijklmnop"
  },
  "message": "Shown once. Use it as the password in the mail app; it does not open webmail."
}

L’esempio omette gli altri campi della voce descritti sopra. Il segreto è solo illustrativo. Un segreto reale è composto da 16 lettere minuscole generate e restituito senza spazi. Le app accettano anche spazi e maiuscole; mostralo in quattro gruppi di quattro se lo presenti a un utente.

La password viene restituita una sola volta. Tienila fuori dai log dell’applicazione. L’utente la inserisce direttamente nell’app di posta con l’indirizzo completo della casella come nome utente. Creazione e sostituzione inviano un avviso con il nome della password per le app alla casella e all’email di recupero, se impostata, senza il segreto. Fa eccezione la prima password per le app emessa con una nuova casella (vedi sotto).

Usa l’API di configurazione dei client di posta per le impostazioni di connessione. Un profilo Apple scaricato non contiene password; l’utente fornisce la password per le app quando macOS o iOS la richiede durante l’installazione.

Ottenere la prima password per le app con una nuova casella

POST /api/v1/mailboxes e POST /api/v1/mailboxes:bulk accettano un booleano facoltativo create_app_password. Con true, ogni casella creata riceve anche la sua prima password per le app, restituita una sola volta come app_password: i campi della voce descritti sopra più password. Si chiama Created with the mailbox e per essa non viene inviato alcun avviso via email, perché la casella è nuova e il chiamante ne ha appena ricevuto la password. Senza il campo (predefinito false) la risposta non cambia. Viene ignorato finché le password per le app non sono abilitate.

POST /api/v1/mailboxes
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: create-alice-001

{"domain_id":7,"local_part":"alice","password_mode":"generated_one_time","client_auth_mode":"app_password_only","create_app_password":true}

La risposta 201 contiene allora one_time_password, la password della casella per la webmail, e app_password.password per le app di posta. In una risposta in blocco, ogni riga creata ha il proprio app_password. Se non è stato possibile emetterla, app_password è null (la creazione singola aggiunge anche _app_password_warning); la casella viene comunque creata e puoi crearne una con l’endpoint descritto sopra. Un nuovo tentativo identico di una creazione singola con la stessa Idempotency-Key restituisce la stessa risposta, inclusi entrambi i segreti, senza emettere una seconda password per le app. Una ripetizione in blocco omette i segreti, come per one_time_password.

Sostituire o revocare una password

La sostituzione non richiede un corpo JSON:

POST /api/v1/mailboxes/42/app-passwords/81:rotate
Authorization: Bearer tm_live_your_token
Idempotency-Key: replace-app-password-81-001

La risposta 200 contiene la nuova voce completa in data, la sua data.password mostrata una sola volta, replaced_id al livello principale che identifica la vecchia voce e message. La sostituzione ha un nuovo data.id e lo stesso nome. La vecchia voce viene revocata con revoked_reason: "rotated", il suo segreto smette subito di funzionare e le app che lo usano vengono disconnesse. Aggiorna il dispositivo con la nuova password.

Per revocare senza creare una sostituzione:

DELETE /api/v1/mailboxes/42/app-passwords/82
Authorization: Bearer tm_live_your_token
Idempotency-Key: revoke-app-password-82-001

Non serve un corpo. La risposta 200 contiene status: "revoked" e la voce revocata completa in data. L’app perde l’accesso; gli altri dispositivi con password per le app valide si riconnettono da soli. La revoca non può essere annullata. Tentare di sostituire o revocare una voce già revocata con una nuova richiesta restituisce 409 conflict.

Cambiare la modalità di accesso delle app di posta per una casella

POST /api/v1/mailboxes/42:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-42-001

{"mode":"app_password_only"}

mode è obbligatorio e accetta:

• app_password_only: le app di posta richiedono una password per le app. Le connessioni che usano la password della casella vengono disconnesse; le app con una password per le app valida si riconnettono da sole.
• password_or_app_password: le app di posta accettano la password della casella o una password per le app.

La risposta 200 contiene mailbox_id, client_auth_mode e message. Impostare di nuovo la modalità attuale restituisce 200 senza modificare nulla. Cambiare modalità non revoca le password per le app esistenti.

Crea le password per i dispositivi prima di renderle obbligatorie. Un accesso rifiutato con la password della casella può mostrare: "Sign-in failed. This mailbox accepts app passwords only: create one in webmail under Settings > App passwords." (Accesso non riuscito. Questa casella accetta solo password per le app: creane una nella webmail in Impostazioni > Password per le app.). Alcune app mostrano solo un errore generico sulla password.

Le caselle condivise non hanno accesso diretto e restituiscono 422 mailbox_not_eligible su questo endpoint. Le caselle di sistema della piattaforma non possono passare a app_password_only; viene restituito 422 system_mailbox_protected.

Nessuna modalità modifica l’accesso alla nuova webmail, Tutte le entrate, i token della Message API, le migrazioni verso la casella, le regole di posta o l’inoltro. I membri delle caselle condivise usano le credenziali e la modalità della propria casella normale.

Cambiare le modalità in blocco

POST /api/v1/mailboxes:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-domain-7-001

{"domain_id":7,"mode":"app_password_only"}

Fornisci mode e un solo selettore:

I vincoli dell’account e del token restringono ogni selezione. Un ID esplicito fuori dall’accesso o sconosciuto restituisce 404, senza applicare una selezione parziale. Un dominio sconosciuto o di un altro account restituisce 422 validation_error. Nessun selettore o più selettori restituiscono 422 invalid_selection.

Possono corrispondere al massimo 1000 caselle. Una selezione più ampia restituisce 422 selection_too_large prima di qualsiasi modifica. Restringi il dominio o invia gruppi di ID espliciti.

{
  "data": {
    "client_auth_mode": "app_password_only",
    "matched": 24,
    "updated": 21,
    "skipped": 3
  }
}

matched conta le caselle selezionate; updated conta le modalità effettivamente cambiate; skipped conta le caselle condivise, nel cestino o in eliminazione, più quelle di sistema della piattaforma quando si richiedono password per le app. Le caselle in pausa e con accesso sospeso possono avere la modalità aggiornata per quando l’accesso tornerà disponibile. Le caselle già nella modalità richiesta contano in matched, ma non in updated o skipped, quindi l’operazione può essere ripetuta senza rischi. Gli account sospesi vengono rifiutati con 403.

Leggere lo stato della casella e impostare la modalità predefinita dell’account

Quando le password per le app sono abilitate, GET /api/v1/mailboxes e GET /api/v1/mailboxes/{mailbox} includono questi campi nelle risorse delle caselle:

• client_auth_mode: app_password_only o password_or_app_password.
• app_passwords_count: conteggio intero delle password per le app attive e visibili, escluse le credenziali interne della piattaforma.

Entrambi i campi sono omessi quando la funzionalità è disattivata. Le caselle condivise non hanno una modalità di accesso diretto utilizzabile né password per le app; richiedi invece le credenziali di una casella normale di un membro.

GET /api/v1/account richiede account:read. I normali campi al livello principale restano disponibili: id, name, email, plan, effective_plan_slug, subscription_status, limits, features, usage, safety_limits e created_at. Aggiunge new_mailbox_client_auth_mode solo quando le password per le app sono abilitate e la piattaforma applica l’impostazione predefinita dell’account alle nuove caselle. Altrimenti GET resta disponibile e omette quel campo.

Solo il proprietario dell’account può cambiare l’impostazione predefinita:

PATCH /api/v1/account
Authorization: Bearer tm_live_owner_token
Content-Type: application/json
Idempotency-Key: new-mailbox-default-001

{"new_mailbox_client_auth_mode":"app_password_only"}

Il campo obbligatorio accetta le stesse due modalità. È l’unico campo dell’account modificabile qui. La risposta contiene al livello principale id, new_mailbox_client_auth_mode e message. PATCH restituisce 404 se non sono soddisfatte entrambe le condizioni per esporre il campo e 403 scope_blocked_by_membership per qualsiasi token di membro o connettore autorizzato da un membro.

Un token del proprietario limitato da domain_ids o mailbox_ids restituisce 403 token_resource_constrained. Usa un token del proprietario senza restrizioni sulle risorse oppure cambia l’impostazione predefinita nelle impostazioni dell’account.

L’impostazione predefinita vale per le caselle future create dalla dashboard, in blocco, tramite inviti, API e agenti. Non cambia mai quelle esistenti. La creazione di una singola casella via API può fornire esplicitamente client_auth_mode in POST /api/v1/mailboxes; ometterlo applica l’impostazione predefinita dell’account. Le caselle esistenti mantengono password_or_app_password al rilascio. La modalità predefinita delle nuove caselle è app_password_only, salvo modifica da parte del proprietario dell’account.

Una reimpostazione della password della casella revoca automaticamente le password per le app

POST /api/v1/mailboxes/{mailbox}/password richiede mailboxes:write, lo stesso permesso del membro per impostare password e Idempotency-Key. Il corpo richiede password, la nuova password della casella, conforme ai requisiti delle password delle caselle. Non è un endpoint di creazione delle password per le app.

Ogni reimpostazione amministrativa riuscita tramite questo endpoint, compresa una modifica della password da parte di un agente MCP, revoca tutte le password per le app con il motivo mailbox_password_reset. Non è possibile evitarlo. Quando la funzionalità è abilitata, la risposta include app_passwords_revoked, un conteggio intero, insieme a status, sync_pending e message:

• 200, status: "updated", sync_pending: false quando la sincronizzazione del server di posta è completata.
• 202, status: "update_pending", sync_pending: true quando la password è stata salvata e la sincronizzazione è in attesa. Le password per le app sono già revocate a questo punto.

La reimpostazione revoca anche i token dei messaggi esistenti della casella. È una conseguenza della reimpostazione della password della casella, non della rotazione di una singola password per le app o del cambio di modalità delle app di posta.

Le modifiche self-service della password nella webmail revocano le password per le app solo quando l’utente seleziona Revoca anche tutte le password per le app. Recupero della password, sospensione dell’accesso, conversione in casella condivisa e spostamento in Eliminati di recente le revocano tutte. Ripristinare l’accesso o la casella non riattiva i segreti revocati. Consulta Sospendere l’accesso alla casella via API.

Idempotenza e segreti mostrati una sola volta

Usa una nuova Idempotency-Key per ogni scrittura intenzionale e riutilizzala solo per riprovare la stessa richiesta, con metodo, percorso e corpo identici, dopo un problema di trasporto. Le chiavi sono obbligatorie e possono contenere al massimo 255 caratteri. Le risposte riuscite vengono memorizzate nella cache per la finestra predefinita di 24 ore; riutilizzare una chiave per una richiesta diversa restituisce 409 idempotency_mismatch.

La ripetizione di una creazione o rotazione di password per le app restituisce gli stessi identificatori sicuri, ma omette data.password. Include _idempotency_replay_warning e l’intestazione di risposta X-Idempotency-Replayed: true. Una ripetizione non può recuperare un segreto perso. Usa il data.id restituito per ruotare la voce attiva con una nuova chiave e ottenere una sostituzione utilizzabile. Tieni traccia del nuovo ID dopo la rotazione.

Ripetere una revoca riuscita con la stessa chiave restituisce il risultato salvato. Una nuova richiesta di revoca per quella voce già revocata restituisce 409 conflict. I cambi di modalità sono naturalmente ripetibili, ma assegna una nuova chiave a ogni modifica intenzionale: riutilizzare una chiave precedente dopo un cambio di modalità può restituire una vecchia risposta invece di applicare la nuova intenzione.

Limiti di richieste ed errori

La creazione è limitata a 60 all’ora per account e la sostituzione a 30 all’ora per account. Questi limiti dell’account sono condivisi dai chiamanti API e MCP, non sono quote separate per token. I cambi di modalità in blocco hanno un limite aggiuntivo di 10 richieste al minuto. A queste rotte si applica anche il normale limite API, pari per impostazione predefinita a 60 richieste al minuto per credenziale. Una richiesta limitata restituisce 429 rate_limited; rispetta l’intestazione Retry-After prima di riprovare.

Gli errori usano l’oggetto standard error con code, message, hint, request_id e retryable. Gestisci il codice leggibile dalle macchine invece di confrontare il testo.

Strumenti MCP e controlli sulle operazioni distruttive

MCP usa le stesse autorizzazioni REST e gli stessi campi delle risposte. Gli strumenti diretti sono:

Gli strumenti di creazione delle caselle create_mailbox_generated_password e bulk_create_mailboxes accettano lo stesso input facoltativo create_app_password di REST.

Gli strumenti di scrittura accettano anche idempotency_key facoltativa. REST usa il campo mode nel corpo per i cambi di modalità delle caselle; lo strumento MCP chiama questo input client_auth_mode. I suoi selettori in blocco hanno le stesse regole di accesso e il limite di 1000 caselle di REST.

list_mailbox_app_passwords(mailbox_id=42)
create_mailbox_app_password(mailbox_id=42, name="Outlook on the office PC")
rotate_mailbox_app_password(mailbox_id=42, app_password_id=81)
revoke_mailbox_app_password(mailbox_id=42, app_password_id=82)
set_mailbox_client_auth_mode(mailbox_id=42, client_auth_mode="app_password_only")
set_mailbox_client_auth_mode(domain_id=7, client_auth_mode="app_password_only")
update_account(new_mailbox_client_auth_mode="app_password_only")

Nel server self-hosted, tutte le scritture sopra richiedono TREKMAIL_ALLOW_DESTRUCTIVE=true. Anche la creazione di una credenziale è soggetta a questo controllo, perché concede accesso alla casella. Elenchi e letture dell’account non richiedono quel flag. Chiedi all’utente di approvare la modifica prevista alle credenziali o all’accesso prima di invocare una scrittura. Gli strumenti diretti che restituiscono segreti indicano all’agente di mostrare la password una sola volta, farla incollare nell’app dall’utente e non salvarla mai in file o memoria, né ripeterla in messaggi o chiamate di strumenti successivi.

Profili dei cataloghi ChatGPT/OpenAI e Claude

Questi profili forniscono un link sicuro di configurazione nella dashboard per creazione e sostituzione, invece di generare un segreto in chat. Anche la creazione delle caselle lì è un link alla dashboard, quindi la prima password per le app arriva dal riquadro Casella creata della dashboard, non da create_app_password. La destinazione è /app/mailboxes/{mailbox_id}/security#app-passwords; l’utente accede e completa l’azione lì.

Il profilo OpenAI espone get_mailbox_app_password_setup_link e get_mailbox_app_password_replacement_setup_link. Il profilo Claude mantiene i nomi create_mailbox_app_password e rotate_mailbox_app_password, ma restituisce il link sicuro di configurazione invece di data.password. Non promettere un segreto da questi strumenti dei cataloghi e non chiedere all’utente di incollarne uno nella conversazione.

Per i parametri di connessione, usa get_mail_client_setup. Per la configurazione generale dei connettori, consulta Collegare agenti IA. Le caselle White Label usano la stessa funzionalità API e host brandizzati per webmail e posta; nelle istruzioni rivolte agli utenti chiama la credenziale password per le app.