Domeinaliassen via API en MCP beheren

Met een domeinalias kan het ene domein de ontvangstadressen van een ander domein volgen. Als hello@company.example e-mail kan ontvangen, kan hello@brand.example die op dezelfde plek bezorgen zonder een tweede mailbox of alias te maken en beheren.

Deze functie is alleen voor ontvangst. Ze maakt geen Van-adres, wijzigt SMTP niet en laat niemand verzenden als het gekoppelde domein.

Wanneer dit nuttig is

Domeinaliassen zijn geschikt voor een bedrijf met meerdere merkdomeinen, een oud domein dat nog klantmail ontvangt of afzonderlijke landdomeinen die dezelfde mailboxnamen moeten delen.

Bijvoorbeeld:

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

Het deel vóór @ blijft exact hetzelfde. Als het overeenkomende adres op het primaire domein niet bestaat, verzint TrekMail het niet.

Abonnementen en limieten

Een gekoppeld domein kan één primair domein tegelijk volgen. Een primair domein kan meerdere gekoppelde domeinen bedienen, tot de normale domeinlimiet van het account. Een domein kan niet zowel gekoppeld als primair zijn. Zo blijft routering eenvoudig en ontstaan geen lussen.

Beide domeinen moeten bij hetzelfde account horen, TrekMail voor inkomende mail gebruiken, actief zijn en werkende MX-records hebben. Als het abonnement, account of de DNS-status later verandert, bewaart TrekMail de koppeling maar pauzeert de bezorging tot weer aan de voorwaarde wordt voldaan.

Wat prioriteit houdt

De domeinalias wordt pas uitgevoerd nadat TrekMail exacte adressen heeft gecontroleerd die al op het gekoppelde domein zijn ingesteld. Bestaande mailboxen, aliassen, doorstuuradressen, mailboxdoorsturing en catch-all-instellingen houden hun beschreven prioriteit.

Een bewuste regel voor sales@brand.example wordt dus niet ongemerkt vervangen door sales@company.example.

REST API

De drie endpoints gebruiken de ID van het gekoppelde domein:

Het endpoint behoudt het oorspronkelijke pad /matching-addresses, zodat bestaande integraties niet stukgaan. Dashboard en documentatie gebruiken de duidelijkere vakterm domeinalias.

PUT en DELETE vereisen een Idempotency-Key-header. Dezelfde geslaagde aanvraag met dezelfde sleutel herhalen is veilig.

Een domein koppelen

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
}

Het resultaat lezen

{
  "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 zegt of de koppeling is opgeslagen. delivering zegt of deze nu werkt. Controleer beide en zie een opgeslagen rij niet als bewijs dat de mail stroomt.

Als een token het gekoppelde maar niet het primaire domein mag benaderen, stelt het antwoord primary_domain_restricted in op true en verbergt het de identiteit van het primaire domein. Een domein buiten de toelatingslijst van de token wordt nooit onthuld.

Bezorgstatussen

MCP-tools

Dezelfde workflow is beschikbaar via drie domeintools:

• get_domain_alias: opgeslagen koppeling en live bezorgstatus lezen;
• set_domain_alias: primair domein koppelen of wijzigen;
• remove_domain_alias: ontkoppelen na confirm_remove: true.

Gehoste MCP past de tijdens OAuth goedgekeurde rechten toe. Een beheerder van lokaal gehoste MCP kan expliciete goedkeuring voor schrijfacties eisen. Beide routes handhaven abonnement, tokenscopes, domeintoelatingslijst en servervalidatie.

Toolnamen en titels voor klanten gebruiken domeinalias. Het REST-endpoint behoudt zijn oorspronkelijke pad voor compatibiliteit.

Veilig verwijderen en downgraden

Een koppeling verwijderen wist geen domein of mailbox. Exacte mailboxen, aliassen, doorstuuradressen en catch-all-regels blijven ongewijzigd. Niet-overeenkomende adressen die alleen van deze functie afhingen, kunnen mail gaan weigeren. Controleer het domein dus voor bevestiging.

Een gekoppeld domein verwijderen wist automatisch de koppeling. TrekMail verwijdert geen primair domein zolang gekoppelde domeinen ervan afhangen; ontkoppel die eerst.

Na een downgrade naar Nano blijft de koppeling opgeslagen maar stopt de bezorging. Terugkeren naar Starter of hoger herstelt haar zonder het primaire domein opnieuw in te voeren.

Auditlogboek

Elke API- of MCP-wijziging verschijnt onder AI-agenten en API → Auditlogboek. Koppel- en wijzigingsgebeurtenissen leggen beide domein-ID’s, zo nodig het vorige primaire domein, de handelende token, aanvraag-ID en tijd vast. Verwijdering legt de verwijderde koppeling vast. Er wordt geen e-mailinhoud of aanmeldinformatie vastgelegd.

Checklist voor probleemoplossing

1. Bevestig dat beide domeinen Actief zijn en TrekMail voor inkomende mail gebruiken.
2. Controleer of de MX-records van beide domeinen gezond zijn.
3. Bevestig dat het account Starter, Pro of Agency gebruikt.
4. Bekijk configured, delivering, status en paused_reason samen.
5. Controleer of een exacte mailbox, alias, doorstuuradres of catch-all-regel het adres al beheert.
6. Controleer het auditlogboek op de laatste koppeling, wijziging of verwijdering.