Managing delegated mailboxes via API

A delegated mailbox is a mailbox that can be accessed by other employees. This can be useful when employees need to respond to customers in place of their colleague who went on vacation or in other similar situations.

You can only delegate mailboxes that have their owners' accounts created on the organization's domain.

Delegation process

Step 1. Prepare to work with the API

To work with the API, you'll need an OAuth token, which you can get after creating an application in the Yandex OAuth service.
- If you don't have an OAuth application yet, follow the instructions on the Access to API page to create one and obtain a token. When creating an application, select the permissions ya360_admin:mail_read_shared_mailbox_inventory and ya360_admin:mail_write_shared_mailbox_inventory.
- If you already have an OAuth application for working with the Yandex 360 for Business API, add permissions to view and edit mailbox access settings to it and then get a new OAuth token following these instructions.
Gather data needed for API requests.
1. Find the organization ID: open the company account and select General settings → Company profile. You can see the ID below the organization name.
2. Find the ID of the employee who needs access. To do this:
  1. Select Users → Employees.
  2. Find the line with the employee you need and click their name.
  3. Right-click the employee's username and copy the link address.
  4. Insert the address into any text editor. The ID is the part of the address after uid=. For example, in the address
```
https://staff.yandex.ru/bb?org_id=5487632&uid=2260000054273165
```
    the ID is 2260000054273165.
    
    Is it possible to find employee IDs using the API?
    Sure. There's a request that returns the list of IDs. View documentation

Step 2. Enable mailbox delegation

Note

There's a limit on the number of delegated mailboxes in the organization. For more information about the existing limitations, see the Limits section on the "Shared access" page.

When you enable delegation for a mailbox, this mailbox is considered delegated even if access by other employees is not yet configured. When you no longer need shared access to the mailbox, disable the delegation option so that it doesn't count toward the available limit.

Prepare a file named resource.json that will contain the data for the request. You can do it in any text editor. In the file, specify the ID of the owner of the mailbox for which you're enabling delegation. Use the following format:
```
{
   "resourceId": "{OWNER}"
}
```
where{OWNER} is the ID of the delegated mailbox owner you obtained in Step 2.2 of the "Prepare to work with the API" guide.
Enable mailbox delegation by sending a request to the API:
- HTTP method: PUT
- Request URL:
```
https://api360.yandex.net/admin/v1/org/{ORGANIZATION}/mailboxes/delegated
```
  where {ORGANIZATION} is the ID of the organization you obtained in Step 2.1 of the "Prepare to work with the API" guide.
  Example
  https://api360.yandex.net/admin/v1/org/1234567/mailboxes/delegated
- Headers:
```
Authorization: OAuth {OAUTH TOKEN}
Content-Type: application/json
```
  where {OAUTH-TOKEN} is the OAuth token you obtained in Step 1 of the "Prepare to work with the API" guide.
- Request body is in the resource.json file you created in Step 1 of this guide.
If you use Windows, you can submit a request to enable mailbox delegation using a curl command formatted as follows:
```
curl -X PUT -H "Authorization: OAuth {OAUTH TOKEN}" -H "Content-Type: application/json" -d "@resource.json" https://api360.yandex.net/admin/v1/org/{ORGANIZATION}/mailboxes/delegated
```
where
{OAUTH-TOKEN} is the OAuth token you obtained in Step 1 of the "Prepare to work with the API" guide.
resource.json is the file with the request body created in Step 1 of this guide.
{ORGANIZATION} is the ID of the organization you obtained at Step 2.1 of the "Prepare to work with the API" guide.
I don't understand how to do this
1. Prepare the command: copy and paste the sample code above into any text editor, replacing the values with your token and IDs.
2. Open the folder containing the resource.json file.
3. Click on empty space in the address bar.
4. Type cmd there and press Enter.
5. The "Command line" window will open. Insert the command you've prepared and press Enter.
Analyze the response you get: if the request is successful, you'll get the 200 OK status code with the ID of the mailbox for which the delegation option was enabled.

Step 3. Grant access to the mailbox

To allow other employees to access the mailbox, you first need to enable the delegation option.

Group operations for access provisioning are not yet supported. With one request, you can provide, modify, or restrict access rights only for one employee and only to one mailbox. But you can submit multiple such requests at a time.

Prepare a file named roles.json that will contain the data for the request. You can do it in any text editor. In the file, specify the roles of the employee to whom you're granting access to the mailbox. For the description of roles, see Roles and access rights.

Sample roles.json file:
```
{
   "roles": [
      "shared_mailbox_imap_admin",
      "shared_mailbox_half_sender"
   ]
}
```
The list should include either the shared_mailbox_sender role or the shared_mailbox_owner role, as they're responsible for read access.
Send a request to the API to provide employees with access to the delegated mailbox:
- HTTP method: POST
- Request URL:
```
https://api360.yandex.net/admin/v1/org/{ORGANIZATION}/mailboxes/set/{OWNER}?actorId={EMPLOYEE WITH ACCESS}&notify={NOTIFICATION DELIVERY PARAMETER}
```
  where
  {ORGANIZATION} is the ID of the organization you obtained in Step 2.1 of the "Prepare to work with the API" guide.
  {OWNER} is the mailbox owner ID you obtained in Step 2.2 of the "Prepare to work with the API" guide.
  {EMPLOYEE WITH ACCESS} is the ID of the employee who requires access to the mailbox. You obtained it in Step 2.2 of the "Prepare to work with the API" guide.
  {NOTIFICATION DELIVERY PARAMETER} is the parameter that determines who receives a notification email about changes to mailbox access. Possible values: all, delegates, none. For the descriptions of the parameter values, see Notifications.
  Example
  https://api360.yandex.net/admin/v1/org/1234567/mailboxes/mailboxes/set/2260000054273165?actorId=3340000075421587&notify=all
- Headers:
```
Authorization: OAuth {OAUTH TOKEN}
Content-Type: application/json
```
  where {OAUTH-TOKEN} is the OAuth token you obtained in Step 1 of the "Prepare to work with the API" guide.
- Request body is in the roles.json file you created in Step 1 of this guide.
If you use Windows, you can submit a request to provide mailbox access using a curl command formatted as follows:
```
curl -X POST -H "Authorization: OAuth {OAUTH TOKEN}" -H "Content-Type: application/json" -d "@roles.json" https://api360.yandex.net/admin/v1/org/{ORGANIZATION}/mailboxes/set/{OWNER}?actorId={EMPLOYEE WITH ACCESS}&notify={NOTIFICATION DELIVERY PARAMETER}
```
where
{OAUTH-TOKEN} is the OAuth token you obtained in Step 1 of the "Prepare to work with the API" guide.
roles.json is the file with the request body created in Step 1 of this guide.
{ORGANIZATION} is the ID of the organization you obtained in Step 2.1 of the "Prepare to work with the API" guide.
{OWNER} is the mailbox owner ID you obtained in Step 2.2 of the "Prepare to work with the API" guide.
{EMPLOYEE WITH ACCESS} is the ID of the employee who requires access to the mailbox. You obtained it in Step 2.2 of the "Prepare to work with the API" guide.
{NOTIFICATION DELIVERY PARAMETER} is the parameter that determines who receives a notification email about changes to mailbox access. Possible values: all, delegates, none. For the descriptions of the parameter values, see Notifications.
Analyze the response you get: if the request is successful, you'll get the 200 OK status code with the ID of the task for changing permissions. Save the ID you obtained.
To check that access has been granted, send another request with task ID pasted into it:
```
curl -X GET -H "Authorization: OAuth {OAUTH TOKEN}" https://api360.yandex.net/admin/v1/org/{ORGANIZATION}/mailboxes/tasks/{TASK ID}
```
In response, you'll get the status of the task for changing permissions. The permissions are successfully changed if the response contains the value complete.

Step 4. Help employees with email setup

For instructions on setting up email clients, see Shared access to mailboxes in email clients.

Manage mailbox access

To change an employee's access to the mailbox, follow the instructions for granting access and update their roles in the roles.json file.

Disconnect from a delegated mailbox

Disable access to the mailbox

To disable access to the mailbox for a specific employee, follow the instruction for granting access and specify an empty list in the roles.json file that lists available roles:

   {
      "roles": []
   }

When you disable access for an employee, the mailbox is still considered delegated, even if the only person that retains access to it is its owner. To undelegate the mailbox, you need to disable the delegation option.

Disable mailbox delegation

To disable the option to delegate the mailbox, send a DELETE request:

curl -X DELETE -H "Authorization: OAuth {OAUTH TOKEN}" https://api360.yandex.net/admin/v1/org/{ORGANIZATION}/mailboxes/delegated/{OWNER}

When you disable the mailbox delegation option, all employees who have access to this mailbox will lose this access.

API documentation

For a complete description of all access control methods, see the documentation.