Маршрутизация почты

Настройте правила маршрутизации исходящих писем, чтобы направлять их через свои почтовые серверы. Это позволит использовать собственные инструменты контроля и безопасности при обработке исходящей почты. Например, для защиты от утечки данных можно перенаправить исходящие письма через ваш сервер, где система будет блокировать или шифровать письма, содержащие конфиденциальную информацию.

Кроме того, маршрутизация позволяет реализовать гибридную конфигурацию почты: разместить часть ящиков на вашем внутреннем почтовом сервере (например, Exchange), а другую часть — в Яндекс Почте.

Управлять правилами маршрутизации почты можно только через API.

Как отправлять запросы

Для работы с API вам потребуются:

1. OAuth-токен с правами ya360_admin:mail_read_domain_routes и ya360_admin:mail_write_domain_routes.
   • Если OAuth-приложение есть, добавьте ему права и получите новый OAuth-токен. Как это сделать
   • Если OAuth-приложения нет, создайте его, укажите права доступа и получите OAuth-токен. Как это сделать
2. Идентификатор организации. Чтобы его узнать, откройте кабинет организации и выберите Общие настройки → Профиль организации. Идентификатор будет написан под названием организации.

Для отправки запросов и ручного тестирования можно использовать стандартную утилиту cURL в командной строке или терминале:

• Windows: Нажмите Win + R, введите cmd и нажмите Enter.
• macOS: Нажмите Cmd + Пробел, введите terminal и нажмите Enter.
• Linux: Нажмите Ctrl + Alt + T.

Откроется окно терминала. Вставьте в него готовый запрос и нажмите Enter.

Добавить или обновить правило

Можно добавить одно правило для всех исходящих писем организации или настроить маршрутизацию для каждого отдельного домена.

При этом правила для доменов имеют приоритет выше, чем общее правило для всех писем.

curl -X POST -H "Authorization: OAuth {oauth_token}" -H "Content-Type: application/json" -d '{
  "items": [
    {
      "recipient_domain": "",
      "relay": "{сервер}",
      "recipient_category": "{категория}",
      "description": "{описание}"
    }
  ]
}' https://cloud-api.yandex.net/v1/mail/organizations/{orgId}/routes/set

curl -X POST -H "Authorization: OAuth {oauth_token}" -H "Content-Type: application/json" -d '{
  "items": [
    {
      "recipient_domain": "{домен}",
      "relay": "{сервер}",
      "recipient_category": "{категория}",
      "description": "{описание}"
    },
    {
      "recipient_domain": "{домен}",
      "relay": "{сервер}",
      "recipient_category": "{категория}",
      "description": "{описание}"
    }
  ]
}' https://cloud-api.yandex.net/v1/mail/organizations/{orgId}/routes/set

Просмотреть список правил

Вы можете посмотреть все правила маршрутизации, настроенные в организации.

Сформируйте и отправьте POST-запрос:

curl -X POST -H "Authorization: OAuth {oauth_token}" -H "Content-Type: application/json" -d '{}' https://cloud-api.yandex.net/v1/mail/organizations/{orgId}/routes/search

В код подставьте значения:

• {oauth_token} — OAuth-токен;
• {orgId} — идентификатор организации.

Ответ на запрос возвращает список всех правил маршрутизации.

Найти правило

Можно найти правила, настроенные для определенных доменов.

Сформируйте и отправьте POST-запрос:

curl -X POST -H "Authorization: OAuth {oauth_token}" -H "Content-Type: application/json" -d '{
  "items": [
    {
      "recipient_domain": "{домен}"
    },
    {
      "recipient_domain": "{домен}"
    }
  ]
}' https://cloud-api.yandex.net/v1/mail/organizations/{orgId}/routes/search

В код подставьте значения:

• {oauth_token} — OAuth-токен;
• {orgId} — идентификатор организации;
• {домен} — домен, по которому нужно найти правило.

В запросе можно указать не больше 1000 доменов. Допускается использовать IDN-домены. Если указано несколько доменов, они не должны повторяться.

Ответ на запрос возвращает список правил маршрутизации для указанных доменов.

Удалить правило

Вы можете удалить одно или несколько правил маршрутизации.

Сформируйте и отправьте POST-запрос:

curl -X POST -H "Authorization: OAuth {oauth_token}" -H "Content-Type: application/json" -d '{
 "items": [
   {
     "recipient_domain": "{домен}"
   },
   {
     "recipient_domain": "{домен}"
   }
 ]
}' https://cloud-api.yandex.net/v1/mail/organizations/{orgId}/routes/remove

В код подставьте значения:

• {oauth_token} — OAuth-токен;
• {orgId} — идентификатор организации;
• {домен} — домен, для которого нужно удалить правило.

В запросе можно указать не больше 1000 доменов. Допускается использовать IDN-домены. Если указано несколько доменов, они не должны повторяться.

Чтобы удалить правило для всех исходящих писем организации, в качестве домена укажите пустое значение "".

Результатом успешного запроса является ответ с кодом 200 OK.

Решение проблем

Если запрос завершился ошибкой, проверьте код ответа сервера — это поможет определить и устранить причину.

Возможные коды ошибок:

• 400 Bad request — параметры запроса не заданы или заданы неверно. Проверьте корректность переданных данных.
• 401 Unauthorized — пользователь не авторизован. Убедитесь, что OAuth-токен действующий и указан верно.
• 403 Forbidden — у пользователя или приложения нет прав на доступ к правилам маршрутизации. Проверьте наличие у OAuth-токена необходимых прав доступа.
• 405 Method not allowed — неподдерживаемый HTTP-метод. Проверьте, что используется разрешенный метод, например POST.
• 422 Business logic error — ошибки в спецификации запроса. Проверьте формат и содержимое запроса.
• 500 Internal server error — внутренняя ошибка сервера. Повторите запрос позже.

Кроме кода ошибки, в ответе может быть дополнительная информация, посмотреть ее можно в параметре details.

Документация API

Полное описание всех методов для управления маршрутизацией почты в организации вы найдете в документации.