Account collegati tramite API e MCP

Gli account collegati consentono a una casella webmail di leggere e inviare messaggi da caselle esterne, Gmail, Yahoo, iCloud, Outlook.com/Microsoft 365 o qualsiasi server IMAP. L’API messaggi e gli strumenti MCP offrono la stessa funzionalità a livello di programmazione: puoi elencare, aggiungere, verificare, modificare e rimuovere gli account collegati, oltre a indirizzare le normali chiamate per i messaggi (elenco, lettura, invio, contrassegni, spostamento, eliminazione e cartelle) a un account collegato invece che alla casella del token.

In parole semplici: mailbox_id sceglie la casella TrekMail per conto della quale l’agente può agire, mentre external_account_id sceglie Gmail o un’altra casella collegata al suo interno. Non sono intercambiabili.

Piani, limiti e dimensioni del catalogo

La gestione degli account collegati offre sette strumenti per i messaggi. Un token con ambiti limitati vede solo gli strumenti che può effettivamente usare, non l’intero catalogo del prodotto.

Prima di iniziare

• Gli account collegati sono una funzionalità della webmail e usano l’interfaccia del token per i messaggi (/api/v1/messages/...), autorizzata da un token per i messaggi con gli ambiti riportati di seguito, non da un token API della dashboard.
• I limiti del piano si applicano a ogni casella: Starter 5, Pro 10, Agency 30. Il piano Nano non include gli account collegati.
• Ogni endpoint è limitato alla casella del token. Un token può vedere e gestire solo i propri account collegati, mai quelli di un’altra casella.
• Le credenziali e i token OAuth sono sempre mascherati nelle risposte. Puoi scrivere una password o una password per app, ma non puoi mai leggerla in seguito.
• Gli account Outlook.com e Microsoft 365 vengono collegati tramite l’accesso Microsoft (OAuth) nell’interfaccia webmail. Dopo il collegamento, l’API può gestirli e usarli, ma non esegue il passaggio interattivo di consenso Microsoft.

Ambiti

Per indirizzare una chiamata per i messaggi a un account collegato è necessario lo stesso ambito già richiesto dalla chiamata (ad esempio, per elencarne i messaggi occorre messages:read; per inviarli occorre messages:send).

Gestione degli account collegati

Percorso di base: /api/v1/messages/external-accounts

Aggiungere un account

POST /api/v1/messages/external-accounts
Scope: messages:write

Corpo della richiesta:

Chiama prima POST /external-accounts/detect per compilare automaticamente provider e le impostazioni del server. Prima del salvataggio, la chiamata di archiviazione esegue un test IMAP + SMTP reale. Un 422 con una categoria di errore (auth, tls, network, transient_throttle) indica che le credenziali non hanno funzionato e non è stato memorizzato nulla.

Indirizzare le chiamate a un account collegato

Ogni endpoint per i messaggi che opera su una casella accetta un external_account_id facoltativo. Forniscilo per eseguire la chiamata su quell’account collegato invece che sulla casella del token; omettilo per usare la casella stessa. Si applica a elenco, lettura, invio, risposta, contrassegni, spostamento, eliminazione ed elenco delle cartelle.

GET /api/v1/messages?external_account_id=42&folder=INBOX
Scope: messages:read

POST /api/v1/messages/send
Scope: messages:send
{
  "external_account_id": 42,
  "to": "someone@example.com",
  "subject": "Sent from my connected account",
  "text": "..."
}

L’invio con il solo external_account_id avviene tramite il server SMTP dell’account (con SPF/DKIM del suo provider). Se invece fornisci un identity_id legato all’origine, viene usato il dominio o il percorso del profilo salvato dell’identità Invia come, continuando a salvare la copia Inviati nella casella collegata. L’account deve essere integro (status: active); un account disconnesso restituisce un errore che chiede di ricollegarlo. Consulta Indirizzi Invia come tramite API e MCP.

Strumenti MCP

La stessa funzionalità è disponibile per gli agenti IA tramite MCP (sia sul server stdio privato sia sul server MCP pubblico):

Gli strumenti per i messaggi list_messages, read_message, send_message, list_folders, update_message_flags, move_message, delete_message, prepare_reply, prepare_reply_all e prepare_forward accettano l’argomento facoltativo external_account_id. Anche l’invio, la creazione di bozze e la pianificazione accettano un identity_id legato all’origine restituito da list_identities.

Poiché gli strumenti di gestione aprono connessioni in uscita verso server di posta arbitrari con credenziali fornite dall’utente, seguono le stesse misure di sicurezza del resto della funzionalità degli account collegati: elenco di host consentiti, blocco degli intervalli privati, elenco di porte consentite e limiti di connessione per host.