Guida API e MCP al branding White Label

Il branding White Label per dominio può essere configurato interamente tramite API e MCP, senza usare la dashboard. Un agente può impostare il nome e i colori del marchio di un dominio, caricare loghi, attivare host personalizzati per dashboard e webmail, leggere i record DNS da creare e richiedere la verifica DNS. È lo stesso branding scritto dalla scheda Branding della dashboard; l'API consente semplicemente a un agente o uno script di farlo per te.

Il branding viene configurato per dominio (il dominio è l'id numerico). Un dominio può avere un proprio marchio (custom), ereditare quello predefinito dell'account (inherit) oppure essere disattivato. L'API restituisce i nomi host personalizzati e i record CNAME del dominio. Copia sempre esattamente i record restituiti. Non creare un nome host o una destinazione CNAME basandoti su un esempio di questa guida.

Il controllo dell'add-on

Ogni piano email include una prova e un'anteprima White Label di 30 giorni. Usa questo periodo per configurare il marchio e provare l'esperienza prima di rendere disponibili ai clienti gli host personalizzati.

L'API applica gli stessi diritti della dashboard White Label:

• Prova attiva o add-on a pagamento: gli scope di lettura e scrittura sono disponibili. Gli host attivati passano da pending_dns ad active dopo la risoluzione del CNAME e l'emissione del certificato SSL.
• Periodo di tolleranza dopo l'annullamento: il proprietario dell'account mantiene l'accesso in sola lettura fino all'ora indicata in hard_delete_at. Le scritture vengono bloccate e le connessioni delegate perdono immediatamente l'accesso White Label.
• Nessun diritto attivo: gli scope White Label vengono rimossi dalle autorizzazioni effettive delle credenziali e i relativi strumenti MCP non vengono caricati.

Se un token memorizzato aveva in precedenza uno scope White Label ma il diritto non è più attivo, l'API restituisce 403 scope_blocked_by_entitlement con il passo successivo da eseguire. Creare un token più ampio non aggira il diritto.

Scope richiesti

Il branding dispone di scope propri. In questo modo, un'automazione che gestisce domini ordinari non può vedere o modificare per errore l'identità del rivenditore.

Endpoint REST

Tutti gli endpoint si trovano sotto https://trekmail.net/api/v1. {id} è l'id numerico del dominio.

Tutti gli endpoint tranne verify-dns e preview restituiscono lo stesso payload di branding restituito da GET, quindi una singola richiesta comunica il nuovo stato.

Il payload del branding

{
  "data": {
    "mode": "custom",
    "white_label_addon_active": true,
    "brand": {
      "id": 42,
      "name": "Northwind Mail",
      "primary_color": "#2563eb",
      "accent_color": "#10b981",
      "logo_url": "https://trekmail.net/storage/branding/42/light.png",
      "logo_dark_url": "https://trekmail.net/storage/branding/42/dark.png",
      "favicon_url": "https://trekmail.net/storage/branding/42/favicon.png",
      "support_email": "support@northwind.com",
      "support_url": "https://help.northwind.com",
      "sender_email": "noreply@northwind.com"
    },
    "mail_zone": {
      "enabled": true,
      "domain": "northwind.com",
      "dns_status": "pending_dns",
      "client_hosts_status": "pending_dns",
      "records": [
        { "type": "TXT", "name": "spf.northwind.com", "value": "v=spf1 include:spf.trekmail.net -all" },
        { "type": "CNAME", "name": "imap.northwind.com", "value": "imap.trekmail.net" },
        { "type": "CNAME", "name": "dav.northwind.com", "value": "trekmail.net" }
      ],
      "dav_url": "https://trekmail.net/dav/files/account/",
      "dav_ready": false,
      "cert_expires_at": null,
      "checked_at": "2026-08-29T06:20:11+00:00"
    },
    "hosts": [
      { "kind": "dashboard", "hostname": "dashboard.northwind.com", "subdomain_label": "dashboard", "enabled": true, "status": "pending_dns" },
      { "kind": "webmail", "hostname": "mail.northwind.com", "subdomain_label": "mail", "enabled": true, "status": "pending_dns" }
    ],
    "dns_records": [
      { "type": "CNAME", "name": "<returned dashboard host>", "value": "<returned CNAME target>", "proxied": false },
      { "type": "CNAME", "name": "<returned webmail host>", "value": "<returned CNAME target>", "proxied": false }
    ],
    "cname_target": "<returned CNAME target>"
  }
}

brand e mail_zone sono null quando mode è off. mail_zone.enabled è l'intenzione salvata; usa i suoi due campi di stato per distinguere gli stati in attesa, attivo, non riuscito e di pulizia. Lo status dell'host indica se DNS e SSL sono ancora in attesa o se l'host è attivo. I valori segnaposto nell'esempio sono intenzionali: i dns_records e il cname_target restituiti sono gli unici valori da pubblicare.

mail_zone descrive i nomi host email propri del marchio (vedi sotto). dns_status riguarda lo stato del DNS email e client_hosts_status riguarda lo stato di host client e certificati; entrambi possono indicare off, pending_dns, active o failed. records elenca i record DNS che il provider deve pubblicare. Puoi sempre usare in sicurezza dav_url: rimane su TrekMail finché il certificato DAV personalizzato e la route web con restrizioni non sono pronti. Passa al nuovo indirizzo solo quando dav_ready diventa true; cert_expires_at indicherà quindi la scadenza più vicina dei certificati per gli host personalizzati delle app email.

Leggere il branding attuale

curl -s "https://trekmail.net/api/v1/domains/123/branding" \
  -H "Authorization: Bearer tm_live_your_token"

Impostare il marchio (unione parziale)

PATCH esegue un'unione parziale. Ogni campo omesso viene conservato, quindi invia solo ciò che vuoi modificare.

curl -s -X PATCH "https://trekmail.net/api/v1/domains/123/branding" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: brand-123-initial" \
  -d '{
    "mode": "custom",
    "name": "Northwind Mail",
    "primary_color": "#2563eb",
    "accent_color": "#10b981",
    "dashboard_enabled": true,
    "dashboard_label": "dashboard",
    "webmail_enabled": true,
    "webmail_label": "mail",
    "mail_zone_enabled": true,
    "support_email": "support@northwind.com",
    "support_url": "https://help.northwind.com",
    "sender_email": "noreply@northwind.com"
  }'

Campi del corpo:

Caricare un logo

I loghi vengono inviati in base64. slot può essere light, dark o favicon. Formati accettati: PNG e JPG per qualsiasi slot, oltre a ICO per favicon. Dimensione massima 1 MB. SVG viene rifiutato per motivi di sicurezza. Lo scope=domain predefinito modifica soltanto un dominio in modalità custom; non segue mai un profilo ereditato. Per modificare intenzionalmente il profilo condiviso tramite un dominio inherit, passa scope=account_default e usa un token branding:write senza vincoli. I token vincolati a un dominio non possono modificare il valore predefinito dell'account.

curl -s -X PUT "https://trekmail.net/api/v1/domains/123/branding/logo/light" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: brand-123-logo-light" \
  -d "{\"content_base64\":\"$(base64 -w0 logo-light.png)\"}"

Rimuovi uno slot con DELETE:

curl -s -X DELETE "https://trekmail.net/api/v1/domains/123/branding/logo/dark" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Idempotency-Key: brand-123-logo-dark-remove"

Entrambi restituiscono il payload del branding con logo_url / logo_dark_url / favicon_url aggiornato. PUT accetta scope nel corpo JSON; DELETE lo accetta come parametro di query. Una modifica implicita con scope di dominio su un profilo ereditato restituisce 422 inherited_brand.

Verificare il DNS

Dopo aver creato i record CNAME (consulta il flusso sotto), accoda la verifica:

curl -s -X POST "https://trekmail.net/api/v1/domains/123/branding/verify-dns" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Idempotency-Key: brand-123-verify"

{ "data": { "status": "queued", "hosts": 2 } }

L'operazione viene eseguita in background. Leggi di nuovo GET /branding e osserva lo status dell'host passare ad active. Se White Label scade, la richiesta restituisce 403 scope_blocked_by_entitlement con un suggerimento per la riattivazione.

La richiesta ricontrolla anche la zona email del marchio, se presente, quindi mail_zone.dns_status e mail_zone.client_hosts_status avanzano nella stessa chiamata. Non è necessario chiamarla per la zona: ricontrolliamo periodicamente le zone in attesa e le attiviamo entro pochi minuti dalla risoluzione dei record. verify-dns chiede semplicemente di farlo subito invece di attendere il controllo successivo.

Email sul dominio proprio del marchio

mail_zone_enabled mostra il nome del rivenditore nelle app email e nei client di sincronizzazione DAV dei suoi clienti. Attivalo, quindi pubblica ogni record restituito in mail_zone.records. Sono inclusi un record TXT SPF e record CNAME IMAP e DAV. I nomi e le destinazioni esatti nella risposta sono autorevoli.

Usa un CNAME invece di un record A quando il record restituito lo richiede e lascia grigia la nuvola di Cloudflare. I client email e DAV devono connettersi direttamente; un proxy DNS può interrompere le verifiche dei certificati e i protocolli non browser. La risposta indica ogni record da pubblicare, quindi non aggiungere record email ipotetici.

Quando i record vengono risolti, TrekMail emette i certificati e attiva i nomi host. Osserva mail_zone.client_hosts_status fino ad active e mail_zone.dav_ready fino a true. Continua a usare il dav_url restituito; passa dall'indirizzo della piattaforma a quello personalizzato soltanto quando DAV può essere distribuito in sicurezza. Se lo stato dell'host indica failed, esegui di nuovo la verifica DNS e apri un ticket di assistenza se continua a non riuscire.

Creare un'anteprima live

POST /branding/preview crea un URL valido 72 ore per vedere l'esperienza personalizzata prima che il DNS sia attivo:

curl -s -X POST "https://trekmail.net/api/v1/domains/123/branding/preview" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Idempotency-Key: brand-123-preview"

La risposta contiene un URL di anteprima che scade dopo 72 ore. Restituisce 422 no_brand quando non esiste un marchio da visualizzare perché il branding è disattivato o non è ancora stato impostato.

Eliminare il branding

curl -s -X DELETE "https://trekmail.net/api/v1/domains/123/branding?scope=domain" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Idempotency-Key: brand-123-remove"

scope=domain cancella solo questo dominio; scope=all cancella il branding nell'intero account. Restituisce il payload del branding.

Strumenti MCP

Sette strumenti gestiscono il branding nel set di 20 strumenti white_label. Vengono registrati soltanto quando la connessione dispone di uno scope di branding effettivo e White Label è disponibile. Lo strumento di lettura richiede branding:read; gli altri sei richiedono branding:write. Un server MCP ospitato localmente può inoltre richiedere che l'amministratore consenta le azioni di scrittura.

get_domain_branding è in sola lettura. Durante il periodo di tolleranza per l'annullamento del proprietario rimane disponibile, mentre tutti e sei gli strumenti di scrittura scompaiono. Senza il diritto White Label, nessuno di questi strumenti viene annunciato in tools/list.

Il flusso autonomo completo

Se il DNS del dominio è su Cloudflare, un agente può portare un dominio privo di branding fino a un host personalizzato attivo senza intervento umano, perché gli strumenti DNS Cloudflare esistenti (apply_cloudflare_dns) possono scrivere i CNAME restituiti da get_domain_branding.

1. Imposta il marchio. set_domain_branding(mode=custom, name, primary_color, accent_color, dashboard_enabled=true, webmail_enabled=true).
2. Carica i loghi (facoltativo). set_domain_brand_logo(slot="light", content_base64=…), quindi ripeti per dark e favicon.
3. Leggi i record DNS. get_domain_branding → copia l'array dns_records restituito. Non ipotizzare o generare valori.
4. Scrivi i CNAME. Pubblica i record con il proxy disattivato. In Cloudflare significa una nuvola grigia, affinché la convalida DNS e SSL possa funzionare.
5. Verifica. verify_domain_branding_dns.
6. Esegui il polling. Richiama get_domain_branding finché lo status di ogni host non è active.
7. Visualizza l'anteprima (facoltativo). Usa create_branding_preview per un URL dimostrativo live prima di indirizzare i clienti al dominio personalizzato.

Esempio pratico (MCP)

set_domain_branding(
  domain_id=123,
  mode="custom",
  name="Northwind Mail",
  primary_color="#2563eb",
  accent_color="#10b981",
  dashboard_enabled=true,
  webmail_enabled=true,
  support_email="support@northwind.com",
  sender_email="noreply@northwind.com"
)

set_domain_brand_logo(domain_id=123, slot="light", content_base64="iVBORw0KGgo…")
set_domain_brand_logo(domain_id=123, slot="dark", content_base64="iVBORw0KGgo…")

get_domain_branding(domain_id=123)
# → Copy the returned dns_records exactly. Do not substitute an example host or target.

apply_cloudflare_dns(domain_ids=[123])   # writes the CNAMEs, proxy off

verify_domain_branding_dns(domain_id=123)

# poll until active
get_domain_branding(domain_id=123)
# → hosts[].status: "active"

create_branding_preview(domain_id=123)   # optional live demo

Chiedi all'agente di comunicare i nomi host personalizzati e gli stati finali degli host, per sapere se sono davvero attivi e non soltanto in pending_dns.

Aspetti importanti

• Il diritto controlla la superficie API e MCP. Per le scritture è necessaria una prova attiva o un add-on a pagamento. Dopo l'annullamento, il proprietario ottiene una finestra di recupero in sola lettura; tutti gli altri perdono immediatamente questi strumenti.
• PATCH è un'unione parziale. I campi omessi vengono conservati. Per cambiare solo il colore secondario, invia {"accent_color":"#10b981"}. Non devi inviare nuovamente nome, loghi o opzioni.
• La riattivazione dallo stato off richiede mode. Se il branding è off, un PATCH senza mode non lo riattiva. Passa mode=custom (o inherit) per riattivarlo.
• sender_email richiede un dominio DKIM verificato. L'indirizzo del mittente impostato deve appartenere a un dominio che abbia già una chiave DKIM predisposta nell'account, altrimenti l'aggiornamento viene rifiutato. Verifica il DKIM del dominio (retry_domain_dkim / get_dns_check) prima di impostare un mittente personalizzato.
• I loghi sono in base64, ≤1 MB e senza SVG. Invia PNG o JPG (è consentito anche ICO per favicon) come content_base64. SVG viene rifiutato. Comprimi prima i file sorgente di grandi dimensioni.
• Mantieni senza proxy i record CNAME restituiti. La nuvola arancione di Cloudflare o un altro proxy CDN impedisce la convalida DNS e SSL. Pubblica i dns_records così come vengono restituiti, con proxied:false.
• Le azioni di scrittura richiedono l'accesso corretto. Ogni strumento tranne get_domain_branding modifica dati, quindi usa lo scope di scrittura richiesto e abilita le scritture se l'amministratore del server MCP locale ha scelto di proteggerle.