Alias di dominio tramite API e MCP

Un alias di dominio consente a un dominio di seguire gli indirizzi di ricezione di un altro. Se hello@company.example può ricevere posta, hello@brand.example può recapitarla nello stesso posto senza creare e gestire una seconda casella o un secondo alias.

Questa funzione serve solo alla ricezione. Non crea un indirizzo mittente, non modifica SMTP e non consente di inviare come dominio collegato.

Quando è utile

Gli alias di dominio sono adatti a un’azienda con più domini di brand, un vecchio dominio che riceve ancora posta dai clienti o domini nazionali separati che devono condividere gli stessi nomi delle caselle.

Ad esempio:

hello@brand.example   → hello@company.example
billing@brand.example → billing@company.example

La parte prima di @ rimane identica. Se l’indirizzo corrispondente non esiste sul dominio principale, TrekMail non lo inventa.

Piani e limiti

Un dominio collegato può seguire un solo dominio principale alla volta. Un dominio principale può servire vari domini collegati, fino al normale limite di domini dell’account. Un dominio non può essere sia collegato sia principale: questo semplifica l’instradamento ed evita cicli.

Entrambi i domini devono appartenere allo stesso account, usare TrekMail per la posta in arrivo, essere attivi e avere record MX funzionanti. Se in seguito cambia lo stato del piano, dell’account o del DNS, TrekMail conserva il collegamento salvato ma sospende la consegna finché il requisito non viene ripristinato.

Cosa mantiene la priorità

L’alias di dominio viene applicato solo dopo che TrekMail ha controllato gli indirizzi esatti già configurati sul dominio collegato. Caselle, alias, indirizzi di inoltro, inoltri delle caselle e impostazioni catch-all esistenti mantengono la priorità documentata.

Una regola intenzionale per sales@brand.example non viene quindi sostituita silenziosamente da sales@company.example.

API REST

I tre endpoint usano l’ID del dominio collegato:

L’endpoint mantiene il percorso originale /matching-addresses per non interrompere le integrazioni esistenti. Il pannello e la documentazione usano il termine di settore più chiaro alias di dominio.

PUT e DELETE richiedono un header Idempotency-Key. È sicuro ripetere la stessa richiesta riuscita con la stessa chiave.

Collegare un dominio

PUT /api/v1/domains/42/matching-addresses
Authorization: Bearer tm_live_...
Idempotency-Key: matching-brand-company-v1
Content-Type: application/json

{
  "primary_domain_id": 7
}

Leggere il risultato

{
  "configured": true,
  "enabled": true,
  "delivering": true,
  "status": "delivering",
  "paused_reason": null,
  "alias_domain": {
    "id": 42,
    "domain": "brand.example"
  },
  "primary_domain": {
    "id": 7,
    "domain": "company.example"
  },
  "primary_domain_restricted": false
}

configured indica se il collegamento è salvato. delivering indica se ora funziona. Controlla entrambi invece di considerare una riga salvata come prova del flusso della posta.

Quando un token può accedere al dominio collegato ma non a quello principale, la risposta imposta primary_domain_restricted su true e nasconde l’identità del dominio principale. Non rivela mai un dominio esterno all’elenco consentito del token.

Stati di consegna

Strumenti MCP

Lo stesso flusso è disponibile con tre strumenti per domini:

• get_domain_alias: legge il collegamento salvato e lo stato di consegna attuale;
• set_domain_alias: collega o modifica il dominio principale;
• remove_domain_alias: lo scollega dopo confirm_remove: true.

MCP ospitato applica i permessi approvati durante OAuth. L’amministratore di un MCP ospitato localmente può richiedere un’approvazione esplicita per le scritture. Entrambi applicano piano, ambiti del token, elenco dei domini consentiti e convalida lato server.

I nomi degli strumenti e i titoli per i clienti usano alias di dominio. L’endpoint REST conserva il percorso originale per compatibilità.

Rimozione sicura e downgrade

Rimuovere un collegamento non elimina domini o caselle. Caselle esatte, alias, indirizzi di inoltro e regole catch-all restano invariati. Gli indirizzi senza corrispondenza che dipendevano solo da questa funzione possono iniziare a respingere la posta; controlla il dominio prima di confermare.

L’eliminazione di un dominio collegato ne rimuove automaticamente il collegamento. TrekMail non elimina un dominio principale finché ne dipendono domini collegati; scollegali prima.

Dopo il downgrade a Nano, il collegamento rimane salvato ma smette di consegnare. Tornando a Starter o superiore viene ripristinato senza reinserire il dominio principale.

Registro di controllo

Ogni modifica API o MCP compare in Agenti IA e API → Registro di controllo. Gli eventi di collegamento e modifica registrano entrambi gli ID di dominio, l’eventuale dominio principale precedente, il token, l’ID richiesta e l’ora. La rimozione registra il collegamento eliminato. Negli eventi non vengono scritti contenuti email o credenziali.

Lista per la risoluzione dei problemi

1. Verifica che entrambi i domini risultino Attivi e usino TrekMail per la posta in arrivo.
2. Controlla che i record MX di entrambi siano validi.
3. Verifica che l’account abbia Starter, Pro o Agency.
4. Esamina insieme configured, delivering, status e paused_reason.
5. Controlla se una casella esatta, un alias, un indirizzo di inoltro o una regola catch-all gestisce già l’indirizzo.
6. Consulta nel registro l’ultimo collegamento, modifica o rimozione.