API- en MCP-gids voor White Label-branding

White Label-branding per domein kan volledig via de API en MCP worden geconfigureerd, zonder dat het dashboard nodig is. Een agent kan de merknaam en kleuren van een domein instellen, logo's uploaden, aangepaste dashboard- en webmailhosts inschakelen, de vereiste DNS-records lezen en DNS-verificatie aanvragen. Dit is dezelfde branding die het tabblad Branding van het dashboard opslaat; met de API kan een agent of script dit voor u doen.

Branding wordt per domein geconfigureerd (het domein is de numerieke id). Een domein kan een eigen merk hebben (custom), de accountstandaard overnemen (inherit) of uitgeschakeld zijn. De API retourneert de aangepaste hostnamen en CNAME-records voor dat domein. Kopieer de geretourneerde records altijd exact. Maak geen hostnaam of CNAME-doel op basis van een voorbeeld in deze gids.

De add-oncontrole

Elk e-mailabonnement bevat een proefperiode en voorbeeldweergave van White Label voor 30 dagen. Gebruik die periode om het merk te configureren en de ervaring te testen voordat u aangepaste hosts beschikbaar maakt voor klanten.

De API volgt dezelfde rechten als het White Label-dashboard:

• Actieve proefperiode of betaalde add-on: lees- en schrijfbewerkingen zijn beschikbaar. Ingeschakelde hosts gaan van pending_dns naar active nadat hun CNAME is omgezet en SSL is uitgegeven.
• Respijtperiode na opzegging: de accounteigenaar behoudt alleen-lezen toegang tot het weergegeven tijdstip hard_delete_at. Schrijfbewerkingen worden geblokkeerd en gedelegeerde verbindingen verliezen direct toegang tot White Label.
• Geen actief recht: White Label-scopes worden verwijderd uit de effectieve machtigingen van de referentie en de bijbehorende MCP-tools worden niet geladen.

Als een opgeslagen token eerder een White Label-scope had maar het recht niet meer actief is, retourneert de API 403 scope_blocked_by_entitlement met een concrete vervolgstap. Een breder token maken omzeilt het recht niet.

Vereiste scopes

Branding heeft eigen scopes. Zo kan automatisering die gewone domeinen beheert niet per ongeluk de identiteit van de reseller bekijken of wijzigen.

REST-endpoints

Alle endpoints vallen onder https://trekmail.net/api/v1. {id} is de numerieke domein-id.

Elk endpoint behalve verify-dns en preview retourneert dezelfde brandingpayload als GET, zodat één aanvraag de nieuwe status toont.

De brandingpayload

{
  "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 en mail_zone zijn null wanneer mode gelijk is aan off. mail_zone.enabled is de opgeslagen intentie; gebruik de twee statusvelden om onderscheid te maken tussen wachtende, actieve, mislukte en opschoonstatussen. De status van een host geeft aan of DNS en SSL nog wachten of dat de host actief is. De tijdelijke waarden in het voorbeeld zijn opzettelijk: de geretourneerde dns_records en cname_target zijn de enige waarden die u moet publiceren.

mail_zone beschrijft de eigen mailhostnamen van het merk (zie hieronder). dns_status omvat de DNS-status voor mail en client_hosts_status omvat de status van clienthosts en certificaten; beide geven off, pending_dns, active of failed aan. records vermeldt de DNS-records die uw provider moet publiceren. dav_url kan altijd veilig worden gebruikt: deze blijft op TrekMail totdat het aangepaste DAV-certificaat en de beperkte webroute klaar zijn. Schakel pas over wanneer dav_ready gelijk wordt aan true; cert_expires_at vermeldt dan de vroegste certificaatvervaldatum voor de aangepaste mail-apphosts.

De huidige branding lezen

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

Het merk instellen (gedeeltelijk samenvoegen)

PATCH is een gedeeltelijke samenvoeging. Elk veld dat u weglaat blijft behouden, dus stuur alleen wat u wilt wijzigen.

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"
  }'

De velden in de body:

Een logo uploaden

Logo's worden als base64 aangeleverd. slot is light, dark of favicon. Toegestaan: PNG en JPG voor elk slot, plus ICO voor favicon. Maximaal 1 MB. SVG wordt geweigerd om veiligheidsredenen. De standaard scope=domain wijzigt alleen een domein in de modus custom; deze volgt nooit een overgenomen profiel. Om het gedeelde profiel bewust te wijzigen via een inherit-domein, geeft u scope=account_default door en gebruikt u een onbeperkt branding:write-token. Domeingebonden tokens kunnen de accountstandaard niet wijzigen.

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)\"}"

Verwijder een slot met 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"

Beide retourneren de brandingpayload met de bijgewerkte logo_url / logo_dark_url / favicon_url. PUT accepteert scope in de JSON-body; DELETE accepteert deze als queryparameter. Een impliciete domeingebonden wijziging van een overgenomen profiel retourneert 422 inherited_brand.

DNS verifiëren

Nadat u de CNAME-records hebt gemaakt (zie het proces hieronder), zet u de verificatie in de wachtrij:

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 } }

Dit wordt op de achtergrond uitgevoerd. Lees GET /branding opnieuw en volg hoe de status van de host naar active gaat. Als White Label verloopt, retourneert de aanvraag 403 scope_blocked_by_entitlement met een aanwijzing voor heractivering.

De aanvraag controleert ook opnieuw de mailzone van het merk wanneer die bestaat, zodat mail_zone.dns_status en mail_zone.client_hosts_status tijdens dezelfde aanroep veranderen. Voor de zone hoeft u de aanvraag helemaal niet te doen: wachtende zones worden volgens een schema opnieuw gecontroleerd en binnen enkele minuten na de DNS-resolutie ingeschakeld. verify-dns vraagt alleen om dit nu uit te voeren in plaats van bij de volgende controle.

Mail op het eigen domein van het merk

mail_zone_enabled plaatst de naam van de reseller in de mail-apps en DAV-synchronisatieclients van klanten. Schakel dit in en publiceer vervolgens elk record dat in mail_zone.records wordt geretourneerd. Deze bevatten een SPF TXT-record en IMAP- en DAV-CNAME-records. De exacte namen en doelen in uw reactie zijn bepalend.

Gebruik een CNAME in plaats van een A-record wanneer het geretourneerde record daarom vraagt en laat de Cloudflare-wolk grijs. Mail- en DAV-clients moeten rechtstreeks verbinding maken; een DNS-proxy kan certificaatcontroles en niet-browserprotocollen verstoren. De reactie vermeldt elk record dat u moet publiceren, dus voeg geen gegokte mailrecords toe.

Zodra de records worden omgezet, geeft TrekMail de certificaten uit en activeert het de hostnamen. Volg mail_zone.client_hosts_status tot active en mail_zone.dav_ready tot true. Blijf de geretourneerde dav_url gebruiken; deze verandert pas van het platformadres naar het aangepaste adres wanneer DAV veilig kan worden aangeboden. Als de hoststatus failed aangeeft, voert u de DNS-verificatie opnieuw uit en opent u een supportticket als het probleem aanhoudt.

Een live voorbeeld maken

POST /branding/preview maakt een URL die 72 uur geldig is, zodat u de aangepaste ervaring kunt bekijken voordat DNS actief is:

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"

De reactie bevat een voorbeeld-URL die na 72 uur verloopt. Deze retourneert 422 no_brand wanneer er geen merk is om te bekijken omdat branding is uitgeschakeld of nog niet is ingesteld.

Branding verwijderen

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 wist alleen dit domein; scope=all wist branding voor het hele account. Retourneert de brandingpayload.

MCP-tools

Zeven tools beheren branding binnen de toolset white_label met 20 tools. Ze worden alleen geregistreerd wanneer de verbinding een effectieve brandingscope heeft en White Label beschikbaar is. De leestool vereist branding:read; de andere zes vereisen branding:write. Bij een lokaal gehoste MCP-server kan de beheerder bovendien schrijftoegang moeten toestaan.

get_domain_branding is alleen-lezen. Tijdens de respijtperiode na opzegging door de eigenaar blijft de tool beschikbaar, terwijl alle zes schrijftools verdwijnen. Zonder White Label-recht wordt geen van deze tools aangeboden in tools/list.

Het autonome end-to-endproces

Als de DNS van uw domein bij Cloudflare staat, kan een agent een domein zonder branding volledig zonder menselijke stappen omzetten naar een actieve aangepaste host. De bestaande Cloudflare DNS-tools (apply_cloudflare_dns) kunnen namelijk de CNAME's schrijven die get_domain_branding retourneert.

1. Stel het merk in. set_domain_branding(mode=custom, name, primary_color, accent_color, dashboard_enabled=true, webmail_enabled=true).
2. Upload logo's (optioneel). set_domain_brand_logo(slot="light", content_base64=…), herhaal voor dark en favicon.
3. Lees de DNS-records. get_domain_branding → kopieer de geretourneerde array dns_records. Raad of genereer geen waarden.
4. Schrijf de CNAME's. Publiceer de records met de proxy uitgeschakeld. In Cloudflare betekent dit een grijze wolk zodat DNS- en SSL-validatie kunnen werken.
5. Verifieer. verify_domain_branding_dns.
6. Poll. Roep get_domain_branding opnieuw aan totdat de status van elke host active is.
7. Bekijk een voorbeeld (optioneel). Gebruik create_branding_preview voor een live demo-URL voordat u klanten naar het aangepaste domein stuurt.

Uitgewerkt voorbeeld (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

Vraag de agent om de aangepaste hostnamen en definitieve hoststatussen te melden, zodat u weet dat alles echt actief is geworden en niet alleen op pending_dns staat.

Aandachtspunten

• Het recht bepaalt toegang tot de API en MCP. Voor schrijfbewerkingen is een actieve proefperiode of betaalde add-on vereist. De eigenaar krijgt na opzegging een alleen-lezen herstelperiode; alle anderen verliezen deze tools direct.
• PATCH is een gedeeltelijke samenvoeging. Weggelaten velden blijven behouden. Om alleen de accentkleur te wijzigen, stuurt u {"accent_color":"#10b981"}. U hoeft de naam, logo's of opties niet opnieuw te sturen.
• Opnieuw inschakelen vanuit uit vereist mode. Als branding momenteel off is, schakelt een PATCH zonder mode deze niet opnieuw in. Geef mode=custom (of inherit) door om opnieuw in te schakelen.
• sender_email vereist een geverifieerd DKIM-domein. Het ingestelde Van-adres moet behoren tot een domein waarvoor al een DKIM-sleutel op het account is ingericht, anders wordt de update geweigerd. Verifieer de DKIM van het domein (retry_domain_dkim / get_dns_check) voordat u een aangepaste afzender instelt.
• Logo's zijn base64, ≤1 MB, zonder SVG. Stuur PNG of JPG (ICO is ook toegestaan voor favicon) als content_base64. SVG wordt geweigerd. Comprimeer grote bronbestanden eerst.
• Gebruik geen proxy voor geretourneerde CNAME-records. Een oranje Cloudflare-wolk of andere CDN-proxy verhindert DNS- en SSL-validatie. Publiceer de dns_records zoals ze zijn geretourneerd, met proxied:false.
• Schrijfacties vereisen de juiste toegang. Elke tool behalve get_domain_branding wijzigt gegevens. Gebruik daarom de vereiste schrijfscope en schakel schrijven in als de beheerder van uw lokaal gehoste MCP-server ervoor heeft gekozen dit te beveiligen.