--- metadata: - name: generator content: Diplodoc Platform v5.50.2 - property: og:type content: article - property: article:section content: Corporate email - property: og:title content: Managing shared mailboxes via API - property: article:tag content: Technical manual alternate: - https://yandex.com/support/yandex-360/business/admin/en/mail/sharing/shared-api.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com/support/yandex-360/business/admin/en/llms.txt # Managing shared mailboxes via API A shared mailbox is a mailbox that has no specific owner and is used by multiple employees, for example, from one department. To create shared mailboxes, your organization needs to be connected to a domain. [How connect a domain](https://yandex.com/support/yandex-360/business/admin/en/domains/index.md) ## Creating and configuring a shared mailbox {#process} ### Step 1. Prepare to work with the API {#prep} 1. To work with the API, you'll need an [OAuth token](*p_oauth-token), which you can get after creating an application in the Yandex OAuth service. {#prep-step-1} * If you don't have an OAuth application yet, follow the instructions on the [Access to API](https://yandex.ru/dev/api360/doc/ru/access#new) 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](https://yandex.ru/dev/api360/doc/ru/access#add). 2. Gather data needed for API requests. 1. Find the organization ID: open [the company account](https://admin.yandex.com/?lang=en) and select **General settings** → **Company profile**. You can see the ID below the organization name.![](../../_assets/mail/sharing/scr-org-id.png) {#prep-step-2-1} 2. Find the ID of the employee who needs access. To do this: {#prep-step-2-2} 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.![](../../_assets/mail/sharing/scr-user-id.png) 4. Insert the address into any text editor. The ID is the part of the address after `uid=`. For example, in the address ```html https://staff.yandex.ru/bb?org_id=5487632&uid=2260000054273165 ``` the ID is `2260000054273165`. {% cut "Is it possible to find employee IDs using the API?" %} Sure. There's a request that returns the list of IDs. [View documentation](https://yandex.ru/dev/api360/doc/ru/ref/UserService/UserService_List) {% endcut %} ### Step 2. Create a shared mailbox {#create} 1. Prepare a file named ##parameters.json## that will contain the data for the request. You can do it in any text editor. In the file, specify the parameters of the shared mailbox in the following format: ```json { "email": "{ADDRESS}", "name": "{NAME}", "description": "{DESCRIPTION}"" } ``` where `{ADDRESS}` is the email address of the shared mailbox; `{NAME}` is the name of the shared mailbox; `{DESCRIPTION}` is a brief description of the shared mailbox. {#create-step-1} 2. Form and send a request to create a shared mailbox: - HTTP method: `PUT` - Request URL: ```html https://api360.yandex.net/admin/v1/org/{ORGANIZATION}/mailboxes/shared ``` where `{ORGANIZATION}` is the ID of the organization you obtained in [Step 2.1](#prep-step-2-1) of the "Prepare to work with the API" guide. {% cut "Example" %} ```html https://api360.yandex.net/admin/v1/org/1234567/mailboxes/shared ``` {% endcut %} - Headers: ```html Authorization: OAuth {OAUTH TOKEN} Content-Type: application/json ``` where `{OAUTH-TOKEN}` is the OAuth token you obtained in [Step 1](#prep-step-1) of the "Prepare to work with the API" guide. - Request body is in the ##parameters.json## file you created in [Step 1](#create-step-1) of this guide. If you use Windows, you can submit a request to allow mailbox delegation using a `curl` command formatted as follows: ```html curl -X PUT -H "Authorization: OAuth {OAUTH-ТОКЕН}" -H "Content-Type: application/json" -d "@parameters.json" https://api360.yandex.net/admin/v1/org/{ORGANIZATION}/mailboxes/shared ``` where `{OAUTH-TOKEN}` is the OAuth token you obtained in [Step 1](#prep-step-1) of the "Prepare to work with the API" guide. `parameters.json` is the file with the request body created in [Step 1](#create-step-1) of this guide. `{ORGANIZATION}` is the ID of the organization you obtained in [Step 2.1](#prep-step-2-1) of the "Prepare to work with the API" guide. {% cut "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 ##parameters.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. {% endcut %} 3. Analyze the response: if the request is successful, you'll get the `200 OK` status code with the ID of the created shared mailbox. Save this ID. ### Step 3. Grant access. {#access} 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. 1. 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](https://yandex.com/support/yandex-360/business/admin/en/mail/sharing/index.md#access-rules). Sample ##roles.json## file: ```json { "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. 2. Send a request to the API to provide employees with access to the shared mailbox: - HTTP method: `POST` - Request URL: ```html https://api360.yandex.net/admin/v1/org/{ORGANIZATION}/mailboxes/set/{MAILBOX}?actorId={EMPLOYEE WITH ACCESS}¬ify={NOTIFICATION DELIVERY PARAMETER} ``` where `{ORGANIZATION}` is the ID of the organization you obtained in [Step 2.1](#prep-step-2-1) of the "Prepare to work with the API" guide. `{MAILBOX}` is the shared mailbox ID you obtained according to the [Create a mailbox](#create) guide. `{EMPLOYEE WITH ACCESS}` is the ID of the employee who requires access to the mailbox. You obtained it in [Step 2.2](#prep-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](https://yandex.com/support/yandex-360/business/admin/en/mail/sharing/index.md#notifies). {% cut "Example" %} ```html https://api360.yandex.net/admin/v1/org/1234567/mailboxes/mailboxes/set/2260000054273165?actorId=3340000075421587¬ify=all ``` {% endcut %} - Headers: ```html Authorization: OAuth {OAUTH TOKEN} Content-Type: application/json ``` where `{OAUTH-TOKEN}` is the OAuth token you obtained in [Step 1](#prep-step-1) of the "Prepare to work with the API" guide. - Request body is in the ##roles.json## file you created in [Step 1](#access-step-1) of this guide. If you use Windows, you can submit a request to allow mailbox delegation using a `curl` command formatted as follows: ```html 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/{MAILBOX}?actorId={EMPLOYEE WITH ACCESS}¬ify={NOTIFICATION DELIVERY PARAMETER} ``` where `{OAUTH-TOKEN}` is the OAuth token you got at [Step 1](#prep-step-1) of the "Preparing to work with shared mailboxes" instruction. `roles.json` is the file with the request body created at [Step 1](#access-step-1) of this instruction. `{ORGANIZATION}` is the ID of the organization you got at [Step 2.1](#prep-step-2-1) of the "Preparing to work with shared mailboxes" instruction. `{MAILBOX}` is the shared mailbox ID you got when following the instructions under [Create a mailbox](#create). `{EMPLOYEE WITH ACCESS}` is the ID of the employee who needs to be granted access to the mailbox. You got it at [Step 2.2](#prep-step-2-2) of the "Preparing to work with shared mailboxes" instruction. `{NOTIFICATION DELIVERY PARAMETER}` is the parameter that determines who needs to receive a notification email about changes in mailbox access rights. Possible values: `all`, `delegates`, `none`. For the descriptions of the parameter values, see [Notifications](https://yandex.com/support/yandex-360/business/admin/en/mail/sharing/index.md#notifies). 3. 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. 4. To check that access has been granted, send another request with task ID pasted into it: ```html 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 {#user-instruction} [//]: # (Раскомментировать, когда ОЯ И ДЯ выедут в прод в вебе Почты: Инструкции по работе с общими ящиками есть в Справке для пользователей: - Инструкция по работе с общими ящиками в веб-интерфейсе Яндекс Почты содержится в разделе \[Совместный доступ в Почте: общие и делегированные ящики\]\(https://yandex.ru/support/yandex-360/business/mail/ru/shared-access\). - ) For instructions on setting up email clients, see [Shared access to mailboxes in email clients](https://yandex.ru/support/yandex-360/business/mail/ru/mail-clients/shared-mailboxes). ## Disabling access {#revoke-access} 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: ```json { "roles": [] } ``` ## Deleting a mailbox {#delete-mailbox} To delete a shared mailbox, use a DELETE request: ```html curl -X DELETE -H "Authorization: OAuth {OAUTH TOKEN}" https://api360.yandex.net/admin/v1/org/{ORGANIZATION}/mailboxes/shared/{MAILBOX} ``` ## API documentation {#doc} For a complete description of all access control methods, see the [documentation](https://yandex.ru/dev/api360/doc/ru/ref/MailboxService/).
{% cut "Contact support" %} {% endcut %}
[*p_api]: API is a special mechanism for managing Yandex 360 services, designed primarily for process automation. There are two ways to work with the API: create a special application (which can be done by a developer) or use the computer's command line. [Complete documentation for developers](https://yandex.com/dev/api360/doc/ru/). [*p_oauth-token]: Special code allowing access to data on behalf of a specific user. [*p_post-request]: An API request to create a new resource on the server. It's used to send data to the server to create a new item or perform an action. [*p_delete-request]: An API request to delete an existing resource on the server. It's used to delete a resource by its ID or another unique identifier.