Доменные псевдонимы через API и MCP

Доменный псевдоним позволяет одному домену следовать адресам приёма другого. Если hello@company.example принимает почту, то hello@brand.example может доставлять её туда же без создания и обслуживания второго ящика или псевдонима.

Функция предназначена только для приёма. Она не создаёт адрес отправителя, не меняет SMTP и не позволяет отправлять от имени подключённого домена.

Когда это полезно

Доменные псевдонимы удобны компании с несколькими фирменными доменами, старым доменом, всё ещё принимающим письма клиентов, или отдельными национальными доменами с одинаковыми именами ящиков.

Например:

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

Часть перед @ остаётся неизменной. Если соответствующего адреса в основном домене нет, TrekMail его не создаёт.

Тарифы и ограничения

Подключённый домен может следовать одному основному домену. Основной домен может обслуживать несколько подключённых в пределах обычного лимита доменов аккаунта. Домен не может одновременно быть подключённым и основным, что упрощает маршрутизацию и предотвращает циклы.

Оба домена должны принадлежать одному аккаунту, использовать TrekMail для входящей почты, быть активными и иметь рабочие записи MX. Если позднее изменится состояние тарифа, аккаунта или DNS, TrekMail сохранит связь, но приостановит доставку до восстановления требования.

Что сохраняет приоритет

Доменный псевдоним применяется после проверки точных адресов, уже настроенных в подключённом домене. Существующие ящики, псевдонимы, адреса и правила переадресации, а также catch-all сохраняют документированный приоритет.

Поэтому правило sales@brand.example не будет незаметно заменено на sales@company.example.

REST API

Три endpoint используют ID подключённого домена:

Endpoint сохраняет исходный путь /matching-addresses, чтобы не нарушать существующие интеграции. Панель и документация используют более понятный отраслевой термин доменный псевдоним.

PUT и DELETE требуют заголовок Idempotency-Key. Успешный запрос можно безопасно повторить с тем же ключом.

Подключение домена

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
}

Чтение результата

{
  "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 показывает, сохранена ли связь. delivering показывает, работает ли она сейчас. Проверяйте оба значения: сохранённая строка ещё не доказывает доставку почты.

Если токен имеет доступ к подключённому, но не основному домену, ответ задаёт primary_domain_restricted равным true и скрывает основной домен. Домены вне списка разрешений токена не раскрываются.

Состояния доставки

Инструменты MCP

Тот же процесс доступен через три инструмента:

• get_domain_alias: чтение сохранённой связи и текущего состояния доставки;
• set_domain_alias: подключение или изменение основного домена;
• remove_domain_alias: отключение после confirm_remove: true.

Размещённый MCP применяет разрешения OAuth. Администратор локального MCP может требовать явное одобрение записи. Оба варианта проверяют тариф, области токена, список разрешённых доменов и серверную валидацию.

Названия инструментов и клиентские заголовки используют термин доменный псевдоним. REST endpoint сохраняет исходный путь для совместимости.

Безопасное удаление и снижение тарифа

Удаление связи не удаляет домены или ящики. Точные ящики, псевдонимы, переадресации и catch-all не меняются. Адреса, зависевшие только от сопоставления, могут начать отклонять почту, поэтому сначала проверьте домен.

Удаление подключённого домена автоматически удаляет связь. TrekMail не удалит основной домен, пока от него зависят подключённые; сначала отключите их.

После перехода на Nano связь сохраняется, но доставка прекращается. Возврат к Starter или выше восстанавливает её без повторного ввода основного домена.

Журнал аудита

Каждое изменение API или MCP отображается в ИИ-агенты и API → Журнал аудита. События подключения и изменения записывают оба ID доменов, прежний основной домен при наличии, токен, ID запроса и время. Удаление записывает удалённую связь. Содержимое писем и учётные данные не записываются.

Проверка неполадок

1. Убедитесь, что оба домена Активны и используют TrekMail для входящей почты.
2. Проверьте записи MX обоих доменов.
3. Подтвердите тариф Starter, Pro или Agency.
4. Проверяйте вместе configured, delivering, status и paused_reason.
5. Проверьте, не обслуживает ли адрес точный ящик, псевдоним, переадресация или catch-all.
6. Найдите в журнале последнее подключение, изменение или удаление.

Связанные статьи

• Обзор тарифов TrekMail
• Области API и разрешения тарифов
• Обзор REST API TrekMail
• Подключение ИИ-агентов к TrekMail через MCP
• Маршрутизация входящей почты домена
• Обзор псевдонимов почты