Руководство по API и MCP для White Label

Брендинг White Label для каждого домена можно полностью настроить через API и MCP без использования панели управления. Агент может задать название и цвета бренда домена, загрузить логотипы, включить брендированные хосты панели управления и веб-почты, получить необходимые записи DNS и запросить проверку DNS. Это тот же брендинг, который сохраняет вкладка Branding в панели управления; API лишь позволяет агенту или скрипту выполнить эту работу за вас.

Брендинг настраивается для каждого домена (домен задается числовым id). Домен может использовать собственный бренд (custom), наследовать значение по умолчанию для аккаунта (inherit) или отключить брендинг. API возвращает брендированные имена хостов и записи CNAME для этого домена. Всегда точно копируйте возвращенные записи. Не создавайте имя хоста или целевое значение CNAME на основе примера из этого руководства.

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

Каждый тариф электронной почты включает 30-дневный пробный период и предварительный просмотр White Label. Используйте это время, чтобы настроить бренд и проверить его работу, прежде чем предоставлять брендированные хосты клиентам.

API применяет те же права, что и панель White Label:

• Активный пробный период или платное дополнение: доступны области чтения и записи. Включенные хосты переходят из pending_dns в active после разрешения CNAME и выпуска SSL-сертификата.
• Льготный период после отмены: владелец аккаунта сохраняет доступ только для чтения до времени, указанного в hard_delete_at. Запись блокируется, а делегированные подключения немедленно теряют доступ к White Label.
• Нет активного права: области White Label удаляются из фактических разрешений учетных данных, а соответствующие инструменты MCP не загружаются.

Если сохраненный токен раньше имел область White Label, но право больше не активно, API возвращает 403 scope_blocked_by_entitlement с конкретным следующим действием. Создание токена с более широкими правами не позволяет обойти это ограничение.

Необходимые области

Для брендинга предусмотрены отдельные области. Благодаря этому автоматизация, управляющая обычными доменами, не сможет случайно просмотреть или изменить идентичность реселлера.

Конечные точки REST

Все конечные точки находятся в https://trekmail.net/api/v1. {id} означает числовой id домена.

Все конечные точки, кроме verify-dns и preview, возвращают те же данные брендинга, что и GET, поэтому новый статус становится известен за один запрос.

Данные брендинга

{
  "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 и mail_zone имеют значение null, когда mode равен off. mail_zone.enabled представляет сохраненное намерение; два поля состояния позволяют различать ожидание, активное состояние, сбой и очистку. status хоста показывает, ожидаются ли еще DNS и SSL или хост уже активен. Значения-заполнители в примере указаны намеренно: публиковать следует только возвращенные dns_records и cname_target.

mail_zone описывает собственные почтовые имена хостов бренда (см. ниже). dns_status относится к состоянию почтовой DNS, а client_hosts_status к состоянию клиентских хостов и сертификатов; оба поля могут иметь значения off, pending_dns, active или failed. records содержит записи DNS, которые должен опубликовать ваш провайдер. dav_url всегда можно использовать безопасно: адрес остается на TrekMail, пока не будут готовы брендированный сертификат DAV и ограниченный веб-маршрут. Переключайтесь только после того, как dav_ready станет равен true; после этого cert_expires_at укажет ближайший срок действия сертификата для брендированных хостов почтовых приложений.

Чтение текущего брендинга

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

Настройка бренда (частичное слияние)

PATCH выполняет частичное слияние. Все пропущенные поля сохраняются, поэтому отправляйте только то, что хотите изменить.

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

Поля тела запроса:

Загрузка логотипа

Логотипы передаются в base64. slot может быть равен light, dark или favicon. Принимаются PNG и JPG для любого слота, а также ICO для favicon. Максимальный размер: 1 MB. SVG отклоняется из соображений безопасности. Стандартный scope=domain изменяет только домен в режиме custom и никогда не следует унаследованному профилю. Чтобы намеренно изменить общий профиль через домен inherit, передайте scope=account_default и используйте токен branding:write без ограничений. Токены с ограничением по домену не могут изменять значение аккаунта по умолчанию.

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

Удалите слот с помощью 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"

Оба запроса возвращают данные брендинга с обновленными logo_url / logo_dark_url / favicon_url. PUT принимает scope в теле JSON, а DELETE в параметре запроса. Неявное изменение с областью домена для унаследованного профиля возвращает 422 inherited_brand.

Проверка DNS

После создания записей CNAME (см. процесс ниже) поставьте проверку в очередь:

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

Проверка выполняется в фоновом режиме. Снова запросите GET /branding и следите, как status хоста меняется на active. Если срок White Label истек, запрос вернет 403 scope_blocked_by_entitlement с подсказкой о повторной активации.

При наличии почтовой зоны бренда запрос также повторно проверяет ее, поэтому mail_zone.dns_status и mail_zone.client_hosts_status изменяются в рамках того же вызова. Для самой зоны этот запрос вообще не обязателен: мы регулярно повторно проверяем ожидающие зоны и включаем их в течение нескольких минут после разрешения записей. verify-dns лишь запускает проверку сейчас, а не во время следующего планового прохода.

Почта в собственном домене бренда

mail_zone_enabled показывает имя реселлера в почтовых приложениях и клиентах синхронизации DAV его клиентов. Включите эту возможность, затем опубликуйте каждую запись, возвращенную в mail_zone.records. Среди них есть запись TXT для SPF и записи CNAME для IMAP и DAV. Точные имена и целевые значения в ответе являются окончательными.

Используйте CNAME вместо записи A, когда это требуется в возвращенной записи, и оставляйте облако Cloudflare серым. Почтовые клиенты и клиенты DAV должны подключаться напрямую; прокси DNS может нарушить проверку сертификатов и работу протоколов вне браузера. Ответ содержит все записи для публикации, поэтому не добавляйте предполагаемые почтовые записи.

После разрешения записей TrekMail выпускает сертификаты и активирует имена хостов. Следите, пока mail_zone.client_hosts_status не станет равен active, а mail_zone.dav_ready не станет равен true. Продолжайте использовать возвращенный dav_url; он меняется с адреса платформы на брендированный адрес только после того, как DAV можно безопасно обслуживать. Если состояние хоста равно failed, повторно запустите проверку DNS и откройте обращение в поддержку, если ошибка сохраняется.

Создание интерактивного предварительного просмотра

POST /branding/preview создает URL на 72 часа, чтобы вы могли увидеть брендированный интерфейс до активации DNS:

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"

Ответ содержит URL предварительного просмотра, срок действия которого истекает через 72 часа. Если брендинг выключен или бренд еще не задан, возвращается 422 no_brand, поскольку просматривать нечего.

Удаление брендинга

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 очищает только этот домен; scope=all очищает брендинг во всем аккаунте. Запрос возвращает данные брендинга.

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

Семь инструментов отвечают за брендинг в наборе white_label, состоящем из 20 инструментов. Они регистрируются только тогда, когда подключение имеет фактическую область брендинга и доступен White Label. Инструмент чтения требует branding:read, остальные шесть требуют branding:write. Для локально размещенного сервера MCP администратор также может отдельно разрешать действия записи.

get_domain_branding предназначен только для чтения. Во время льготного периода после отмены владельцем он остается доступен, а все шесть инструментов записи исчезают. Без права White Label ни один из этих инструментов не объявляется в tools/list.

Автономный сквозной процесс

Если DNS вашего домена размещена в Cloudflare, агент может без участия человека перевести домен из состояния без брендинга в активный брендированный хост. Существующие инструменты DNS Cloudflare (apply_cloudflare_dns) могут записать CNAME, возвращенные get_domain_branding.

1. Настройте бренд. set_domain_branding(mode=custom, name, primary_color, accent_color, dashboard_enabled=true, webmail_enabled=true).
2. Загрузите логотипы (необязательно). set_domain_brand_logo(slot="light", content_base64=…), повторите для dark и favicon.
3. Получите записи DNS. get_domain_branding → скопируйте возвращенный массив dns_records. Не угадывайте и не создавайте значения самостоятельно.
4. Запишите CNAME. Опубликуйте записи с отключенным прокси. В Cloudflare это означает серое облако, чтобы проверка DNS и SSL могла выполняться.
5. Проверьте. verify_domain_branding_dns.
6. Опрашивайте. Повторяйте вызов get_domain_branding, пока status каждого хоста не станет равен active.
7. Откройте предварительный просмотр (необязательно). Используйте create_branding_preview, чтобы получить URL рабочей демонстрации до направления клиентов на брендированный домен.

Практический пример (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

Попросите агента сообщить брендированные имена хостов и их окончательные состояния, чтобы убедиться, что они действительно активированы, а не просто остались в pending_dns.

Важные особенности

• Право определяет доступность API и MCP. Для записи требуется активный пробный период или платное дополнение. После отмены владелец получает период восстановления только для чтения; все остальные немедленно теряют эти инструменты.
• PATCH выполняет частичное слияние. Пропущенные поля сохраняются. Чтобы изменить только акцентный цвет, отправьте {"accent_color":"#10b981"}. Повторно отправлять название, логотипы или переключатели не нужно.
• Для повторного включения требуется mode. Если брендинг имеет состояние off, запрос PATCH без mode не включит его. Передайте mode=custom (или inherit) для повторного включения.
• Для sender_email необходим проверенный домен DKIM. Заданный адрес отправителя должен принадлежать домену, для которого в аккаунте уже подготовлен ключ DKIM, иначе обновление будет отклонено. Проверьте DKIM домена (retry_domain_dkim / get_dns_check) перед настройкой собственного отправителя.
• Логотипы передаются в base64, ≤1 MB, SVG запрещен. Передавайте PNG или JPG (для favicon также разрешен ICO) в content_base64. SVG отклоняется. Сначала сжимайте большие исходные файлы.
• Не проксируйте возвращенные записи CNAME. Оранжевое облако Cloudflare или другой прокси CDN мешает проверке DNS и SSL. Публикуйте dns_records в полученном виде, с proxied:false.
• Для действий записи необходим правильный доступ. Все инструменты, кроме get_domain_branding, изменяют данные, поэтому используйте необходимую область записи и включите запись, если администратор локального MCP-сервера решил ограничить такие действия.

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

• Настройка White Label Lite
• Что такое White Label Lite и для кого он предназначен
• Рекомендации по ресурсам бренда White Label
• Управление клиентами White Label и участниками команды через API и MCP
• Обзор API
• Подключение ИИ-агентов (MCP)