--- metadata: - name: generator content: Diplodoc Platform v5.50.3 - property: og:type content: article - property: article:section content: Корпоративная почта - property: og:title content: Управление общими ящиками по API - property: article:tag content: Техническая инструкция alternate: - https://yandex.by/support/yandex-360/business/admin/ru/mail/sharing/shared-api.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.by/support/yandex-360/business/admin/ru/llms.txt # Управление общими ящиками по API Общий ящик — ящик, у которого нет конкретного владельца: им пользуются несколько сотрудников, например из одного отдела. Если у организации не подключен домен, создать общие ящики не получится. [Как подключить домен](https://yandex.by/support/yandex-360/business/admin/ru/domains/index.md) ## Создание и настройка общего ящика {#process} ### Шаг 1. Подготовьтесь к работе с API {#prep} 1. Для работы с API вам потребуется [OAuth-токен](*p_oauth-token), который можно получить после создания приложения в сервисе Яндекс OAuth. {#prep-step-1} * Если у вас еще нет OAuth-приложения, то для его создания и получения токена воспользуйтесь инструкцией на странице [Доступ к API](https://yandex.ru/dev/api360/doc/ru/access#new). При создании приложения выберите права `ya360_admin:mail_read_shared_mailbox_inventory` и `ya360_admin:mail_write_shared_mailbox_inventory`. * Если у вас уже есть OAuth-приложение для работы с API Яндекс 360 для бизнеса, то добавьте ему права на просмотр и изменение настроек доступа к почтовым ящикам, а затем получите новый OAuth-токен по [инструкции](https://yandex.ru/dev/api360/doc/ru/access#add). 2. Соберите данные, которые потребуются для API-запросов. 1. Определите идентификатор организации: откройте [кабинет организации](https://admin.yandex.by) и выберите **Общие настройки** → **Профиль организации**. Идентификатор будет написан под названием организации.![](../../_assets/mail/sharing/scr-org-id.png) {#prep-step-2-1} 2. Определите идентификатор сотрудника, которому нужно предоставить доступ. Чтобы определить идентификатор: {#prep-step-2-2} 1. Выберите **Пользователи** → **Сотрудники**. 2. Найдите строчку нужного сотрудника и нажмите на его имя. 3. Правой кнопкой нажмите на **логин сотрудника** и скопируйте адрес ссылки.![](../../_assets/mail/sharing/scr-user-id.png) 4. Вставьте адрес в любой текстовый редактор. Идентификатор — это часть адреса после `uid=`. Например, из адреса ```html https://staff.yandex.ru/bb?org_id=5487632&uid=2260000054273165 ``` получится идентификатор `2260000054273165`. {% cut "А можно ли определить идентификаторы сотрудников тоже по API?" %} Конечно. Есть запрос, который возвращает их список. [Посмотреть документацию](https://yandex.ru/dev/api360/doc/ru/ref/UserService/UserService_List) {% endcut %} ### Шаг 2. Создайте общий ящик {#create} 1. Подготовьте файл с именем ##parameters.json##, который будет содержать данные для запроса. Это можно сделать в любом текстовом редакторе. В файле укажите параметры создаваемого общего ящика в следующем формате: ```json { "email": "{АДРЕС}", "name": "{ИМЯ}", "description": "{ОПИСАНИЕ}" } ``` где `{АДРЕС}` — адрес электронной почты общего ящика; `{ИМЯ}` — имя общего ящика; `{ОПИСАНИЕ}` — краткое описание общего ящика. {#create-step-1} 2. Сформируйте и отправьте запрос на создание общего ящика: - HTTP-метод: `PUT` - URL запроса: ```html https://api360.yandex.net/admin/v1/org/{ОРГАНИЗАЦИЯ}/mailboxes/shared ``` где `{ОРГАНИЗАЦИЯ}` — идентификатор организации, полученный [на шаге 2.1](#prep-step-2-1) инструкции «Подготовка к работе с API». {% cut "Пример" %} ```html https://api360.yandex.net/admin/v1/org/1234567/mailboxes/shared ``` {% endcut %} - Заголовки: ```html Authorization: OAuth {OAUTH-ТОКЕН} Content-Type: application/json ``` где `{OAUTH-ТОКЕН}` — OAuth-токен, полученный [на шаге 1](#prep-step-1) инструкции «Подготовка к работе с API». - Тело запроса: содержится в файле ##parameters.json##, созданном [на шаге 1](#create-step-1) этой инструкции. Если вы работаете на Windows, то отправить запрос на разрешение делегирования ящика можно с помощью команды `curl` такого вида: ```html curl -X PUT -H "Authorization: OAuth {OAUTH-ТОКЕН}" -H "Content-Type: application/json" -d "@parameters.json" "https://api360.yandex.net/admin/v1/org/{ОРГАНИЗАЦИЯ}/mailboxes/shared" ``` где `{OAUTH-ТОКЕН}` — OAuth-токен, полученный [на шаге 1](#prep-step-1) инструкции «Подготовка к работе с API»; `parameters.json` — файл с телом запроса, созданный [на шаге 1](#create-step-1) этой инструкции; `{ОРГАНИЗАЦИЯ}` — идентификатор организации, полученный [на шаге 2.1](#prep-step-2-1) инструкции «Подготовка к работе с API». {% cut "Я не понимаю, как это сделать" %} 1. Подготовьте команду: скопируйте пример в любой редактор, вставьте в указанные места токен и идентификаторы. 2. Откройте папку, в которой лежит файл ##parameters.json##. 3. Нажмите на пустое место в адресной строке. 4. Напишите туда `cmd` и нажмите клавишу Enter. 5. Откроется окно «Командная строка». Вставьте в него готовую команду и нажмите Enter. {% endcut %} 3. Проанализируйте полученный ответ: в случае успешного выполнения запроса в ответе вы получите статус `200 OK` с указанием идентификатора созданного общего ящика. Сохраните этот идентификатор. ### Шаг 3. Предоставьте доступ {#access} Групповые операции на предоставление доступов пока не поддерживаются. За один запрос можно предоставить, изменить или удалить право доступа только для одного сотрудника к одному почтовому ящику. Но вы можете одновременно направить несколько таких запросов. 1. Подготовьте файл с именем ##roles.json##, который будет содержать данные для запроса. Это можно сделать в любом текстовом редакторе. В файле укажите роли сотрудника, которому открывается доступ к ящику. Описание ролей приведено в разделе [Роли и права доступа](https://yandex.by/support/yandex-360/business/admin/ru/mail/sharing/index.md#access-rules). Пример файла ##roles.json##: ```json { "roles": [ "shared_mailbox_imap_admin", "shared_mailbox_half_sender" ] } ``` В списке должна присутствовать одна из ролей `shared_mailbox_sender` либо `shared_mailbox_owner`, потому что они отвечают за чтение почты. 2. С помощью запроса к API предоставьте доступ сотрудникам к общему ящику: - HTTP-метод: `POST` - URL запроса: ```html https://api360.yandex.net/admin/v1/org/{ОРГАНИЗАЦИЯ}/mailboxes/set/{ЯЩИК}?actorId={СОТРУДНИК С ДОСТУПОМ}¬ify={ПАРАМЕТР ОТПРАВКИ УВЕДОМЛЕНИЙ} ``` где `{ОРГАНИЗАЦИЯ}` — идентификатор организации, полученный [на шаге 2.1](#prep-step-2-1) инструкции «Подготовка к работе с API»; `{ЯЩИК}` — идентификатор общего ящика, созданного по инструкции [Создание ящика](#create); `{СОТРУДНИК С ДОСТУПОМ}` — идентификатор сотрудника, которому нужно предоставить доступ к ящику, полученный [на шаге 2.2](#prep-step-2-2) инструкции «Подготовка к работе с API»; `{ПАРАМЕТР ОТПРАВКИ УВЕДОМЛЕНИЙ}` — параметр, который определяет, кому необходимо отправить письмо-уведомление об изменении прав доступа к ящику. Возможные значения: `all`, `delegates`, `none`. Описание значений параметра приведены в разделе [Уведомления](https://yandex.by/support/yandex-360/business/admin/ru/mail/sharing/index.md#notifies). {% cut "Пример" %} ```html https://api360.yandex.net/admin/v1/org/1234567/mailboxes/mailboxes/set/2260000054273165?actorId=3340000075421587¬ify=all ``` {% endcut %} - Заголовки: ```html Authorization: OAuth {OAUTH-ТОКЕН} Content-Type: application/json ``` где `{OAUTH-ТОКЕН}` — OAuth-токен, полученный [на шаге 1](#prep-step-1) инструкции «Подготовка к работе с API». - Тело запроса: содержится в файле ##roles.json##, созданном [на шаге 1](#access-step-1) этой инструкции. Если вы работаете на Windows, то отправить запрос на разрешение делегирования ящика можно с помощью команды `curl` такого вида: ```html curl -X POST -H "Authorization: OAuth {OAUTH-ТОКЕН}" -H "Content-Type: application/json" -d "@roles.json" "https://api360.yandex.net/admin/v1/org/{ОРГАНИЗАЦИЯ}/mailboxes/set/{ЯЩИК}?actorId={СОТРУДНИК С ДОСТУПОМ}¬ify={ПАРАМЕТР ОТПРАВКИ УВЕДОМЛЕНИЙ}" ``` где `{OAUTH-ТОКЕН}` — OAuth-токен, полученный [на шаге 1](#prep-step-1) инструкции «Подготовка к работе с API»; `roles.json` — файл с телом запроса, созданный [на шаге 1](#access-step-1) этой инструкции; `{ОРГАНИЗАЦИЯ}` — идентификатор организации, полученный [на шаге 2.1](#prep-step-2-1) инструкции «Подготовка к работе с API»; `{ЯЩИК}` — идентификатор общего ящика, созданного по инструкции [Создание ящика](#create); `{СОТРУДНИК С ДОСТУПОМ}` — идентификатор сотрудника, которому нужно предоставить доступ к ящику, полученный [на шаге 2.2](#prep-step-2-2) инструкции «Подготовка к работе с API»; `{ПАРАМЕТР ОТПРАВКИ УВЕДОМЛЕНИЙ}` — параметр, который определяет, кому необходимо отправить письмо-уведомление об изменении прав доступа к ящику. Возможные значения: `all`, `delegates`, `none`. Описание значений параметра приведены в разделе [Уведомления](https://yandex.by/support/yandex-360/business/admin/ru/mail/sharing/index.md#notifies). 3. Проанализируйте полученный ответ: в случае успешного выполнения запроса в ответе вы получите статус `200 OK` и идентификатор задачи на изменение прав. Сохраните полученный идентификатор. 4. Чтобы убедиться, что доступ предоставлен, выполните еще один запрос, подставив в него идентификатор задачи: ```html curl -X GET -H "Authorization: OAuth {OAUTH-ТОКЕН}" "https://api360.yandex.net/admin/v1/org/{ОРГАНИЗАЦИЯ}/mailboxes/tasks/{ID ЗАДАЧИ}" ``` В ответ вы получите статус задачи на изменение прав. Права успешно изменены, если в ответе пришло значение `complete`. ### Шаг 4. Помогите сотрудникам с настройкой почты {#user-instruction} [//]: # (Раскомментировать, когда ОЯ И ДЯ выедут в прод в вебе Почты: Инструкции по работе с общими ящиками есть в Справке для пользователей: - Инструкция по работе с общими ящиками в веб-интерфейсе Яндекс Почты содержится в разделе \[Совместный доступ в Почте: общие и делегированные ящики\]\(https://yandex.ru/support/yandex-360/business/mail/ru/shared-access\). - ) Инструкция по настройке почтовых клиентов содержится в разделе [Совместный доступ к ящикам в почтовых программах](https://yandex.ru/support/yandex-360/business/mail/ru/mail-clients/shared-mailboxes). ## Отключение доступа {#revoke-access} Чтобы отключить доступ к ящику конкретному сотруднику, выполните пункты инструкции по предоставлению доступа, только в файле с перечнем доступных ролей ##roles.json## укажите пустой список: ```json { "roles": [] } ``` ## Удаление ящика {#delete-mailbox} Удалить общий ящик можно с помощью DELETE-запроса: ```html curl -X DELETE -H "Authorization: OAuth {OAUTH-ТОКЕН}" "https://api360.yandex.net/admin/v1/org/{ОРГАНИЗАЦИЯ}/mailboxes/shared/{ЯЩИК}" ``` ## Документация API {#doc} Полное описание всех методов для управления доступом вы найдете в [документации](https://yandex.ru/dev/api360/doc/ru/ref/MailboxService/).
{% cut "Написать в службу поддержки" %}
{% endcut %}
[*p_api]: API — специальный механизм управления сервисами Яндекс 360, предназначенный прежде всего для автоматизации процессов. Есть два способа работать с API: создать специальное приложение (это может сделать разработчик) или использовать командную строку компьютера. [Полная документация для разработчиков](https://yandex.ru/dev/api360/doc/ru/). [*p_oauth-token]: Ключ, который предоставляет приложению ограниченный доступ к данным пользователя. Содержит информацию об аккаунте пользователя, самом приложении и список разрешенных действий. [*p_post-request]: API-запрос на создание нового ресурса на сервере. Используется для отправки данных на сервер для создания нового объекта или выполнения какого-либо действия. [*p_delete-request]: API-запрос на удаление существующего ресурса на сервере. Используется для удаления ресурса по его идентификатору или другому уникальному идентификатору.