Indirizzi Invia come tramite API e MCP

TrekMail separa due attività che usano credenziali e autorizzazioni diverse:

1. L’interfaccia Dashboard/Ops gestisce i profili SMTP riutilizzabili e l’instradamento dei domini. Usa un token tm_live_ con smtp:read o smtp:write.
2. L’interfaccia Webmail/Messaggi gestisce gli indirizzi mittente disponibili per una casella e una posta in arrivo collegata. Usa un token tm_msg_ con messages:read, messages:write o messages:send.

Questa separazione è intenzionale. Un token della casella può selezionare un percorso di invio già autorizzato, ma non può rivelare le credenziali SMTP né gestire l’infrastruttura di un altro account.

In breve

• Se invii solo con external_account_id, i destinatari vedono l’indirizzo dell’account collegato e viene usato il suo server SMTP.
• Se invii anche un identity_id legato all’origine, i destinatari vedono l’indirizzo aziendale dell’identità. TrekMail usa il percorso del dominio o il profilo SMTP salvato assegnato a tale identità, quindi salva la copia Inviati nella posta in arrivo collegata.
• Starter consente di configurare e usare questa funzione nella webmail. Pro e Agency consentono anche di automatizzarla tramite API o MCP. Nano non offre spazi per account collegati.

Gli strumenti API e MCP disponibili evolvono con il prodotto. Invia come usa le famiglie SMTP e messaggi e ogni connessione vede solo il sottoinsieme consentito dal piano, dagli ambiti e dalle autorizzazioni approvate.

Modello di instradamento

Quando external_account_id viene inviato senza identity_id, TrekMail usa il server SMTP dell’account esterno e il suo indirizzo.

Quando vengono inviati entrambi i valori, TrekMail considera l’account esterno come destinazione posta in arrivo/Inviati e l’identità come mittente visibile + percorso SMTP:

connected Gmail inbox
  + Send As identity sales@example.com
  + identity route: domain or saved SMTP profile
  = recipients see sales@example.com
    mail is delivered through the identity route
    the Sent copy is appended to that Gmail account

L’identità e l’account esterno devono essere collegati tra loro. Omettere l’origine o fornire un’identità di un’altra casella restituisce 422 identity_unavailable.

1. Esaminare o configurare SMTP nell’API della dashboard

Usa un token Ops.

La lettura di un profilo non restituisce mai la password. L’endpoint di utilizzo è il modo sicuro con cui un agente può spiegare l’impatto prima di modificare o eliminare un profilo condiviso.

Strumenti MCP: get_domain_smtp, set_domain_smtp, list_domain_smtp_profiles, get_domain_smtp_profile_usage, create_domain_smtp_profile, update_domain_smtp_profile, delete_domain_smtp_profile, test_domain_smtp, get_domain_smtp_test_status, get_account_smtp_default, set_account_smtp_default.

2. Elencare gli indirizzi per la posta in arrivo esatta

Usa un token Messaggi:

GET /api/v1/messages/identities?external_account_id=42
Authorization: Bearer tm_msg_...

La risposta include le identities specifiche dell’origine, tutte le external_identities configurate, i sending_addresses, i send_as_domains idonei, la reply_from_policy della casella e, solo per la casella del proprietario dell’account, gli smtp_profiles salvati che possono essere selezionati direttamente.

MCP: chiama list_identities con external_account_id.

MCP ospitato e stdio locale

Gli strumenti per i messaggi presentano un’importante differenza di trasporto:

• MCP HTTP ospitato (OAuth): fornisci anche mailbox_id in ogni chiamata di uno strumento per i messaggi. Il server ospitato lo usa per creare un token messaggi di breve durata per quella casella esatta. Ad esempio, chiama list_identities con { "mailbox_id": 7, "external_account_id": 42 }.
• MCP stdio self-hosted (tm_msg_): non fornire mailbox_id. Il token messaggi statico è già legato a una casella, quindi lo schema dello strumento richiede solo external_account_id.

external_account_id non sostituisce mai mailbox_id: seleziona una posta in arrivo collegata all’interno della casella già autorizzata. Gli strumenti SMTP della dashboard restano limitati all’account e non accettano mailbox_id in nessuno dei due trasporti.

3. Creare un’identità Invia come

POST /api/v1/messages/identities
Authorization: Bearer tm_msg_...
Idempotency-Key: send-as-sales-v1
Content-Type: application/json

{
  "kind": "send_as",
  "external_account_id": 42,
  "email": "sales@example.com",
  "name": "Example Sales",
  "reply_to": "sales@example.com",
  "smtp_mode": "domain"
}

email deve già essere l’indirizzo principale di questa casella o un alias attivo abilitato all’invio. Il dominio deve essere attivo e appartenere allo stesso account. smtp_mode: domain segue il percorso del dominio configurato nella dashboard. smtp_mode: profile fissa l’identità a smtp_connection_id; la selezione diretta del profilo è limitata alla casella del proprietario dell’account. L’appartenenza non permette di creare una normale identità send_as per l’indirizzo condiviso.

external_account_id è facoltativo ed è importante chiarirne il significato:

• Includilo quando leggi la posta di quell’indirizzo tramite una posta in arrivo Gmail, Outlook o IMAP collegata. L’identità viene quindi legata a tale casella e può essere usata solo con essa.
• Omettilo quando la posta viene invece inoltrata a una casella TrekMail, nel flusso di lavoro della casella condivisa in cui un cliente conserva la posta presso il proprio provider e inoltra le copie a una casella del team.

Una posta in arrivo personale collegata non può mai essere associata a una casella condivisa: è privata per la persona che l’ha collegata. In questo caso, ometti external_account_id.

MCP: create_identity con kind=send_as. Sul MCP ospitato, includi il mailbox_id principale come descritto sopra.

4. Inviare, creare una bozza, pianificare, rispondere o inoltrare

Le normali operazioni sui messaggi accettano la stessa coppia di origini:

{
  "external_account_id": 42,
  "identity_id": 91,
  "to": ["customer@example.net"],
  "subject": "Hello",
  "body": { "text": "Hello from Example Sales" }
}

identity_id è supportato dall’invio immediato, dal salvataggio/aggiornamento delle bozze e dall’invio pianificato. La preparazione di risposte/inoltri accetta external_account_id e seleziona l’identità corrispondente dalle intestazioni di consegna. L’identità selezionata viene autorizzata di nuovo quando un messaggio in coda viene effettivamente eseguito; disabilitarne l’alias, il dominio, il profilo o l’account collegato interrompe la consegna invece di passare silenziosamente a un altro indirizzo mittente.

Strumenti MCP: send_message, save_draft, update_draft, schedule_message, prepare_reply, prepare_reply_all e prepare_forward.

Inviare come casella condivisa

Per inviare dalla casella condivisa tramite Message API o MCP, il membro deve avere Leggi e Invia come. Usa il suo token con shared_mailbox_id. Un token della casella condivisa può leggere, ma non inviare.

{
  "shared_mailbox_id": 5,
  "to": ["customer@example.net"],
  "subject": "Re: your order",
  "body": { "text": "Answered by the team" }
}

Il token resta legato al membro, e così la traccia di audit: un invio dall'indirizzo del team registra chi lo ha effettuato. GET /messages/identities?shared_mailbox_id=5 elenca gli indirizzi da cui quella casella può inviare.

Due rifiuti da attendersi:

• shared_mailbox_not_a_sender (403): il token appartiene a una casella condivisa. La lettura non è toccata; solo l'invio richiede un membro.
• shared_mailbox_send_denied (403): Il membro deve avere Leggi e Invia come.

Gli indirizzi del team nella webmail personale non vengono elencati né accettati come identità della Message API. Una identity_id rifiutata restituisce 422 identity_unavailable; modificare o eliminare un indirizzo del team restituisce 422 identity_delegated. Questi errori includono hint e identity_id, con shared_mailbox_id e member_id quando disponibili. Un invio condiviso rifiutato include shared_mailbox_id e, se il membro può solo inviare, member_id. Leggi il suggerimento prima di riprovare: omettere il contesto condiviso o l’identità invia da un altro indirizzo.

Message API permette di programmare con shared_mailbox_id per membri con i permessi Leggi e Invia come. La webmail non offre invii programmati all’interno di una casella condivisa. Per elencare, cambiare l’orario o annullare, passa lo stesso shared_mailbox_id; le righe appartengono alla casella condivisa. La riga non identifica chi ha programmato l’invio.

MCP: send_message, schedule_message e list_identities accettano shared_mailbox_id. Nel MCP ospitato, mailbox_id resta il membro.

Criterio di risposta

PATCH /api/v1/messages/identities/reply-policy
Authorization: Bearer tm_msg_...
Idempotency-Key: reply-policy-v1

{ "reply_from_policy": "recipient" }

recipient risponde dall’indirizzo che ha ricevuto il messaggio quando possibile. default parte sempre dal valore predefinito della casella per la posta normale. MCP usa set_reply_from_policy.

Regole di sicurezza e isolamento

• Le credenziali SMTP non vengono mai incluse nella risposta dell’API messaggi o di MCP.
• Ogni account esterno e identità è limitato alla casella del token messaggi.
• Un’identità Invia come collegata è utilizzabile solo con il suo external_account_id esatto; un’identità appartenente alla casella è utilizzabile solo senza di esso.
• L’indirizzo mittente deve essere già autorizzato come indirizzo della casella o alias abilitato all’invio; l’API non può inventare indirizzi mittente arbitrari.
• Prima della creazione è necessario un percorso funzionante, che viene controllato nuovamente al momento della consegna.
• Le intestazioni Reply-To personalizzate non possono essere in conflitto con il valore salvato nel campo Rispondi a di un’identità.
• Le modifiche di identità e profilo tramite MCP richiedono l’autorizzazione di scrittura appropriata. Un amministratore MCP ospitato localmente può richiedere un’approvazione esplicita per le azioni di scrittura; anche l’invio richiede una conferma per messaggio.

Non sono necessarie nuove stringhe di ambito del token. I token smtp:* e messages:* esistenti continuano a funzionare secondo le autorizzazioni correnti.

Quale limite di invio si applica?

Le chiamate API mantengono anche le proprie protezioni contro gli abusi: per impostazione predefinita, 60 richieste di invio al minuto per token messaggi e 100 invii API al giorno nell’intera casella. Si applicano indipendentemente dal server che consegna infine l’email.