Domain Aliases via API and MCP

A domain alias lets one domain follow the receiving addresses on another domain. If hello@company.example can receive mail, then hello@brand.example can deliver to the same place without creating and maintaining a second mailbox or alias.

This feature is receive-only. It does not create a From address, change SMTP, or let anyone send as the connected domain.

When it is useful

Domain aliases work well when a business has several brand domains, an old domain that still receives customer mail, or separate country domains that should share the same inbox names.

For example:

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

The part before @ stays exactly the same. If the matching address on the primary domain does not exist, TrekMail does not invent it.

Plans and limits

One connected domain can follow one primary domain at a time. A primary domain can serve several connected domains, up to the account's ordinary domain limit. A domain cannot be both a connected domain and a primary domain, which keeps routing simple and prevents loops.

Both domains must belong to the same account, use TrekMail for incoming mail, be active, and have working MX records. If the plan, account, or DNS state changes later, TrekMail keeps the saved connection but pauses delivery until the requirement is restored.

What keeps priority

The domain alias runs only after TrekMail checks exact addresses already configured on the connected domain. Existing mailboxes, aliases, forwarding addresses, mailbox forwarding, and catch-all settings keep their documented priority.

That means an intentional sales@brand.example rule is not silently replaced by sales@company.example.

REST API

The three endpoints use the connected domain's ID:

The endpoint keeps the original /matching-addresses path so existing integrations do not break. The dashboard and documentation use the clearer industry term domain alias.

PUT and DELETE require an Idempotency-Key header. Repeating the same successful request with the same key is safe.

Connect a domain

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
}

Read the result

{
  "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 tells you whether the connection is saved. delivering tells you whether it is working now. Check both instead of treating a saved row as proof that mail is flowing.

When a token may access the connected domain but not the primary domain, the response sets primary_domain_restricted to true and hides the primary domain's identity. It never leaks a domain outside the token's allow-list.

Delivery states

MCP tools

The same workflow is available through three domain tools:

• get_domain_alias — read the saved connection and live delivery state;
• set_domain_alias — connect or change the primary domain;
• remove_domain_alias — disconnect it after confirm_remove: true.

For self-hosted stdio MCP, changing or removing a connection also requires TREKMAIL_ALLOW_DESTRUCTIVE=true. Hosted MCP applies the permissions approved during OAuth. Both paths still enforce the account plan, token scopes, domain allow-list, and server-side validation.

The tool names and customer-facing titles use domain alias. The REST endpoint keeps its original path for compatibility.

Safe removal and downgrades

Removing a connection does not delete either domain or any mailbox. Exact mailboxes, aliases, forwarding addresses, and catch-all rules remain unchanged. Unmatched addresses that relied only on matching may start bouncing, so review the domain before confirming removal.

Deleting a connected domain removes its connection automatically. TrekMail will not delete a primary domain while connected domains still depend on it; disconnect those domains first.

After a downgrade to Nano, the connection stays saved but stops delivering. Returning to Starter or higher restores it without re-entering the primary domain.

Audit trail

Every API or MCP change appears under AI Agents & API → Audit Log. Connect and change events record both domain IDs, the previous primary domain when applicable, the acting token, request ID, and time. Removal records which connection was removed. No email content or credentials are written to these events.

Troubleshooting checklist

1. Confirm both domains show Active and use TrekMail for incoming mail.
2. Check that both domains' MX records are healthy.
3. Confirm the account is on Starter, Pro, or Agency.
4. Look at configured, delivering, status, and paused_reason together.
5. Check whether an exact mailbox, alias, forwarding address, or catch-all rule already owns the address.
6. Review the audit log for the last connect, change, or removal.