Настройка доступа сотрудников к ящикам друг друга (делегирование)

Сотрудник, которому предоставляется доступ к почтовому ящику коллеги, может быть назначен на следующие роли:

shared_mailbox_sender — отправка писем по протоколу SMTP

Отправлять письма из чужого ящика можно в двух режимах:

• «Отправить от имени» (Send on behalf) — с адреса ящика, но от своего имени. В заголовке письма указывается, что письмо отправлено другим сотрудником от имени владельца ящика. Например, если сотрудник по имени Алексей Иванов отправляет письмо от имени своего начальника Сергея Петрова, получатель увидит примерно следующее: «От имени Сергея Петрова, Алексей Иванов».
• «Отправить как» (Send as) — с адреса ящика от имени его владельца. Для получателя письмо выглядит так, словно владелец ящика отправил его лично. Например, если сотрудник по имени Алексей Иванов отправляет письмо от имени своего начальника Сергея Петрова, получатель увидит только имя Сергея Петрова.

Роль shared_mailbox_sender позволяет отправлять письма как в режиме «Отправить от имени», так и в режиме «Отправить как».

Сможет ли сотрудник выбрать способ отправки письма, если предоставить ему оба вида доступа?

Да, если такую возможность поддерживает его почтовый клиент. Инструкции по настройке почтовых клиентов есть в справке для пользователей.

shared_mailbox_half_sender — ограниченная отправка писем по протоколу SMTP

Пользователь с такой ролью может отправлять письма только в режиме «Отправить от имени».

shared_mailbox_imap_admin — управление ящиком в IMAP-клиенте

Пользователю с такой ролью доступны чтение, разметка и удаление писем, управление папками, и настройка ящика по протоколу IMAP. Отправка писем не предусмотрена.

shared_mailbox_owner — полные права на ящик (владение)

Роль предоставляет полные права на ящик, аналогичные тем, которые есть у владельца:

• управление ящиком в IMAP-клиенте: чтение, разметка, удаление писем, управление папками, настройка ящика;
• отправка писем по протоколу SMTP: и в режиме «Отправить от имени», и в режиме «Отправить как».

При необходимости один сотрудник может быть назначен на несколько ролей одновременно.

Когда вы настраиваете доступ сотрудника к почтовому ящику, вы можете указать, кому необходимо отправлять письма-уведомления об этом. За это отвечает параметр notify, который может принимать следующие значения:

• all — владельцу почтового ящика и сотруднику, для которого настраивается доступ к нему;
• delegates — только сотруднику, для которого настраивается доступ;
• none — никому.

Использование параметра описано в разделе Как предоставить доступ.

1. Воспользуйтесь инструкцией на странице Доступ к API, чтобы получить OAuth-токен. При создании приложения выберите доступы ya360_admin:mail_read_shared_mailbox_inventory и ya360_admin:mail_write_shared_mailbox_inventory .
2. Соберите данные, которые необходимы для запросов.

   1. Определите идентификатор организации: откройте admin.yandex.by и выберите Общие настройки → Профиль организации. Идентификатор будет написан под названием организации.
   2. Определите идентификаторы владельца ящика и сотрудника, которому нужно предоставить доступ. Чтобы определить идентификатор:

      1. Выберите Пользователи → Сотрудники.
      2. Найдите строчку нужного сотрудника и нажмите на его имя.
      3. Правой кнопкой нажмите на логин сотрудника и скопируйте адрес ссылки.
      4. Вставьте адрес в любой текстовый редактор. Идентификатор — это часть адреса после uid=. Например, из адреса

         https://staff.yandex.ru/bb?org_id=5487632&uid=2260000054273165

         получится идентификатор

         2260000054273165

      А можно ли определить идентификаторы сотрудников тоже по API?

      Конечно. Есть запрос, который возвращает их список. Посмотреть документацию

3. Подготовьте файлы, которые будут содержать данные для запросов. Это можно сделать в любом текстовом редакторе.

   1. Файл с именем resource.json. В файле укажите идентификатор владельца ящика, для которого надо разрешить делегирование, в следующем формате:

      {
        "resourceId": "{ВЛАДЕЛЕЦ}"
      }

      где {ВЛАДЕЛЕЦ} — идентификатор сотрудника — владельца делегируемого ящика, полученный на шаге 2.2.

   2. Файл с именем roles.json. В файле укажите роли сотрудника, которому открывается доступ к ящику. Описание ролей

      Пример файла roles.json:

      {
        "roles": [
          "shared_mailbox_imap_admin",
          "shared_mailbox_half_sender"
        ]
      }

      В списке должна присутствовать одна из ролей shared_mailbox_sender либо shared_mailbox_owner, потому что они отвечают за чтение почты.

4. С помощью запроса к API разрешите делегирование ящика:

   • HTTP-метод: PUT
   • URL запроса:

     https://api360.yandex.net/admin/v1/org/{ОРГАНИЗАЦИЯ}/mailboxes/delegated
     Скопировано

     где {ОРГАНИЗАЦИЯ} — идентификатор организации, полученный на шаге 2.1.

     Пример

     https://api360.yandex.net/admin/v1/org/1234567/mailboxes/delegated
     Скопировано

   • Заголовки:

     Authorization: OAuth {OAUTH-ТОКЕН}
     Content-Type: application/json
     Скопировано

     где {OAUTH-ТОКЕН} — OAuth-токен, полученный на шаге 1.

   • Тело запроса: содержится в файле resource.json, созданном на шаге 3.1.

   Если вы работаете на Windows, то отправить запрос на разрешение делегирования ящика можно с помощью команды curl такого вида:

   curl -X PUT -H "Authorization: OAuth {OAUTH-ТОКЕН}" -H "Content-Type: application/json" -d "@resource.json" https://api360.yandex.net/admin/v1/org/{ОРГАНИЗАЦИЯ}/mailboxes/delegated
   Скопировано

   где

   • {OAUTH-ТОКЕН} — OAuth-токен, полученный на шаге 1;
   • resource.json — файл с телом запроса, созданный на шаге 3.1;
   • {ОРГАНИЗАЦИЯ} — идентификатор организации, полученный на шаге 2.1.

   Я не понимаю, как это сделать

   1. Подготовьте команду: скопируйте пример в любой редактор, вставьте в указанные места токен и идентификатор организации.
   2. Откройте папку, в которой лежит файл resource.json.
   3. Нажмите на пустое место в адресной строке.
   4. Напишите туда cmd и нажмите клавишу Enter.
   5. Откроется окно «Командная строка». Вставьте в него готовую команду и нажмите Enter.

5. Проанализируйте полученный ответ: в случае успешного выполнения запроса в ответе вы получите статус 200 OK с указанием идентификатора почтового ящика, разрешение на делегирование которого предоставлено.

6. С помощью запроса к API предоставьте доступ сотрудникам к делегированному ящику:

   • HTTP-метод: POST
   • URL запроса:

     https://api360.yandex.net/admin/v1/org/{ОРГАНИЗАЦИЯ}/mailboxes/set/{ВЛАДЕЛЕЦ}?actorId={СОТРУДНИК С ДОСТУПОМ}&notify={ПАРАМЕТР ОТПРАВКИ УВЕДОМЛЕНИЙ}
     Скопировано

     где

     • {ОРГАНИЗАЦИЯ} — идентификатор организации, полученный на шаге 2.1;
     • {ВЛАДЕЛЕЦ} — идентификатор сотрудника — владельца ящика, разрешение на делегирование которого получено на шаге 4;
     • {СОТРУДНИК С ДОСТУПОМ} — идентификатор сотрудника, которому нужно предоставить доступ к ящику, полученный на шаге 2.2;
     • {ПАРАМЕТР ОТПРАВКИ УВЕДОМЛЕНИЙ} — параметр, который определяет, кому необходимо отправить письмо-уведомление об изменении прав доступа к ящику. Возможные значения: all, delegates, none. Описание значений параметра приведены в разделе Уведомления.

     Пример

     https://api360.yandex.net/admin/v1/org/1234567/mailboxes/mailboxes/set/2260000054273165?actorId=3340000075421587&notify=all
     Скопировано

   • Заголовки:

     Authorization: OAuth {OAUTH-ТОКЕН}
     Content-Type: application/json
     Скопировано

     где {OAUTH-ТОКЕН} — OAuth-токен, полученный на шаге 1.

   • Тело запроса: содержится в файле roles.json, созданном на шаге 3.2.

   Если вы работаете на Windows, то отправить запрос на разрешение делегирования ящика можно с помощью команды curl такого вида:

   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={СОТРУДНИК С ДОСТУПОМ}&notify={ПАРАМЕТР ОТПРАВКИ УВЕДОМЛЕНИЙ}
   Скопировано

   где

   • {OAUTH-ТОКЕН} — OAuth-токен, полученный на шаге 1;
   • roles.json — файл с телом запроса, созданный на шаге 3.2;
   • {ОРГАНИЗАЦИЯ} — идентификатор организации, полученный на шаге 2.1;
   • {ВЛАДЕЛЕЦ} — идентификатор сотрудника — владельца ящика, разрешение на делегирование которого получено на шаге 4;
   • {СОТРУДНИК С ДОСТУПОМ} — идентификатор сотрудника, которому нужно предоставить доступ к ящику, полученный на шаге 2.2;
   • {ПАРАМЕТР ОТПРАВКИ УВЕДОМЛЕНИЙ} — параметр, который определяет, кому необходимо отправить письмо-уведомление об изменении прав доступа к ящику. Возможные значения: all, delegates, none. Описание значений параметра приведены в разделе Уведомления.
7. Проанализируйте полученный ответ: в случае успешного выполнения запроса в ответе вы получите статус 200 OK и идентификатор задачи на изменение прав. Сохраните полученный идентификатор.
8. Чтобы убедиться, что доступ предоставлен, выполните еще один запрос, подставив в него идентификатор задачи:

   curl -X GET -H "Authorization: OAuth {OAUTH-ТОКЕН}" https://api360.yandex.net/admin/v1/org/{ОРГАНИЗАЦИЯ}/mailboxes/tasks/{ID ЗАДАЧИ}
   Скопировано

   В ответ вы получите статус задачи на изменение прав. Права успешно изменены, если в ответе пришло значение complete.

• Чтобы отозвать доступ к ящику у конкретного сотрудника, выполните п.п. 6-8 инструкции по предоставлению доступа, только в файле с перечнем доступных ролей roles.json укажите пустой список:

  {
    "roles": []
  }

• Чтобы отозвать доступ у всех сотрудников, которые имеют доступ к конкретному ящику, достаточно запретить делегирование этого ящика с помощью DELETE-запроса:

  curl -X DELETE -H "Authorization: OAuth {OAUTH-ТОКЕН}" https://api360.yandex.net/admin/v1/org/{ОРГАНИЗАЦИЯ}/mailboxes/delegated/{ВЛАДЕЛЕЦ}
  Скопировано

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

Сотрудник может получить доступ к ящику коллеги только через почтовый клиент — Microsoft Outlook, Mozilla Thundebird или Почта для macOS. Настройка этих программ описана в справке для пользователей.