Managing message delivery permissions for groups and departments

In your corporate email, you can make it so that emails sent to a specific address reach multiple employees at once. For example, if you want all your sales managers to receive emails sent to sales@example.com.

To do this, all email recipients must belong to the same department or group.

Each mailing list is limited to 10,000 recipients.

If you need to add more recipients, divide the them into multiple groups.

How to create a mailing list

Create a new group or department following the instructions in Employees, departments, and groups. When creating one, specify the address of the mailing list.
Add recipients to this group or department.

If all the necessary recipients are already in one group or department, you don't need to create anything new — just add the mailing list address to the properties of this group or department.

Mailing list senders

By default, all users can send messages to mailing lists. However, you can limit the list of users who have this permission. To do this, specify authorized mailing list senders. You need this to prevent situations where any user can send messages to the mailing list or accidentally reply to the mailing list, reaching all its participants.

If an unauthorized user sends a message to the mailing list, it won't reach anyone. This will happen even if the To, Cc, and Bcc fields contain other email addresses to which the user has the permission to send messages. Yandex Mail will inform the user that the message wasn't sent.

When the mailing list of a group or department has a list of authorized senders:

Users with email addresses created not on the domains of Yandex 360 for Business organizations can't send messages to the mailing list.
You can't send invitations from Yandex Calendar to such a groups or department.

How to create a list of authorized senders or add employees to it

You can create a list of senders via an API request. The number of these requests isn't limited. The list will be updated each time you add a new sender to it.

Prepare to work with the API.
1. Get an OAuth token that will be used to manage access and authorization:
  - Follow the instructions on the Access to API page. When creating the application, select the following permissions:
    - ya360_admin:mail_read_mail_list_permissions and ya360_admin:mail_write_mail_list_permissions — submitting requests to add authorized senders for mailing lists.
    - directory:read_groups — submitting requests to view information about groups, including mailing list IDs.
    - directory:read_departments — submitting requests to view information about departments, including mailing list IDs.
    - directory:read_users — submitting requests to view information about the company employees.
  - If the OAuth application is already created but doesn't have the necessary access permissions, add them and get a new token by following the instructions.
2. Explore how to send API requests if you haven't done this before.
  Creating and submitting HTTP requests
  To create a request, you need to know:
  - HTTP method: This method determines the specific operation you're going to perform. For example, retrieving information from the server or updating it.
  - Request URL: Address of the resource to which you're sending the request.
  - Headers: Here's where you can include additional information, such as authentication or data formats details.
  - Request body: Optional part that's used in some methods (such as POST) to transmit specific data.
  There are various ways to submit HTTP requests depending on the tool or programming language you're using. One such method is to submit requests using cURL.
  
  If you're using Windows and want to submit any request mentioned in this section using cURL:
  1. Prepare the command: copy the provided example into any editor and replace the placeholders in curly brackets with the required information.
  2. Open the folder containing the file with the request body (if the example includes one). If there's no body, submit the request from any folder.
  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.

Get the required IDs.

Find your organization ID: open the company account and select General settings → Company profile. You can see the ID below the organization name.

Screenshot

Determine the ID of the mailing list for which you need to specify authorized senders. You can do this by submitting requests to the Yandex 360 for Business API.

Group mailing list

Request component	Value
HTTP method	`GET`
Request URL	`https://api360.yandex.net/directory/v1/org/{ORGANIZATION}/groups` where `{ORGANIZATION}` is the ID of the organization you got at Step 2.1.
Headers	`Authorization: OAuth {OAUTH-TOKEN}` where `{OAUTH-TOKEN}` is the OAuth token you got at Step 1.1.

You can submit a request using the curl command in the following format:

curl -X GET -H "Authorization: OAuth {OAUTH-TOKEN}" https://api360.yandex.net/directory/v1/org/{ORGANIZATION}/groups

For instructions on how to submit a command if you're using Windows, see Step 1.2.

The mailing list ID is in the emailId field of the response. In the groups array, find the part that contains the description of the required group (its name is in the name field, and the mailing list address is in the email field) and copy the value from the emailId field.

For more information on how to make a request for obtaining a list of the organization's groups, see the API documentation.

Department mailing list

Request component	Value
HTTP method	`GET`
Request URL	`https://api360.yandex.net/directory/v1/org/{ORGANIZATION}/departments` where `{ORGANIZATION}` is the ID of the organization you got at Step 2.1.
Headers	`Authorization: OAuth {OAUTH-TOKEN}` where `{OAUTH-TOKEN}` is the OAuth token you got at Step 1.1.

You can submit a request using the curl command in the following format:

curl -X GET -H "Authorization: OAuth {OAUTH-TOKEN}" https://api360.yandex.net/directory/v1/org/{ORGANIZATION}/departments

For instructions on how to submit a command if you're using Windows, see Step 1.2.

The mailing list ID is in the emailId field of the response. In the departments array, find the part that contains the description of the required department (its name is in the name field, and the mailing list address is in the email field) and copy the value from the emailId field.

For more details about the request to get the list of the organization's departments, see the API documentation.

Get the IDs of users who require permission to send messages to the mailing list.

Employees

Via API

In the organization's account

Request component	Value
HTTP method	`GET`
Request URL	`https://api360.yandex.net/directory/v1/org/{ORGANIZATION}/users` where `{ORGANIZATION}` is the ID of the organization you got at Step 2.1.
Headers	`Authorization: OAuth {OAUTH-TOKEN}` where `{OAUTH-TOKEN}` is the OAuth token you got at Step 1.1.

You can submit a request using the curl command in the following format:

curl -X GET -H "Authorization: OAuth {OAUTH-TOKEN}" https://api360.yandex.net/directory/v1/org/{ORGANIZATION}/users

For instructions on how to submit a command if you're using Windows, see Step 1.2.

Employee IDs are in the id field of the response. In the users array, find the part that contains the description of the user (their first name and last name are in the name field, and the username is in the nickname field) and copy the value from the id field.

For more details about the request to get the list of the organization's employees, see the API documentation.

Go to the Yandex 360 for Business organization account.
Select Users → Employees.
Click the line with the employee you need. A card with user details will open.
Right-click the employee's name and copy the link.
Insert the address into any text editor. The employee ID is the part of the address after uid=.

Shared mailboxes

Go to the Yandex 360 for Business organization account.
Select Mail → Shared mailboxes.
Find the required mailbox in the list and click its name.
Copy the page URL from the browser's address bar.
Insert the address into any text editor. The shared mailbox ID is the part of the address after shared/ and up to ?uid=.
For example, in the address https://admin.yandex.ru/shared-mailboxes/shared/1130000068825371?uid=1130000068703774, the mailbox ID is 1130000068825371.

Groups

To get group IDs, check the response to the request that retrieves the list of the organization's groups. For instructions on how to submit this request, see Group mailing list in Step 2.2. The id field of the groups array contains all groups' IDs.

Departments

To get department IDs, check the response to the request that retrieves the list of the organization's departments. For instructions on how to submit this request, see Department mailing list in Step 2.2. The id field of the departments array contains all departments' IDs.

Organization

For instructions on obtaining an organization ID, see Step 2.1.

Create and submit a request to add approved senders.

Prepare the list of users who can send messages to the mailing list. To do this, create a file with the request body in any text editor. For example, permissions-list.json. The file will have a structure similar to this one:

{
   "role_actions": [{
         "type": "grant",
         "roles": [
            "mail_list_sender"
         ],
         "subjects": [{
               "type": "organization",
               "id": 1234567,
               "org_id": 1234567
            },{
               "type": "department",
               "id": 777,
               "org_id": 1234567
            },{
               "type": "group",
               "id": 555,
               "org_id": 1234567
            },{
               "type": "user",
               "id": 1150000062907856,
               "org_id": 1234567
            },{
               "type": "user",
               "id": 1150000062907859,
               "org_id": 1234567
            }
         ]
      }
   ]
}

Update the file to include details about the organization, its departments, groups, or employees authorized to send messages to the mailing list. Describe each of them using a structure that contains the following fields, as shown in the example:

Parameter	Data type	Description
`type`	Line	Type of entity that's granted permission to send messages to mailing lists: `organization` — entire organization. `department` — department. `group` — group. `shared_mailbox` — shared mailbox. `user` — user. There can be multiple items with types `department`, `group`, `shared_mailbox`, and `user` in the file. The value `organization` means that permission to send messages to the mailing list will be granted to all employees of the organization (including from shared mailbox addresses), while external contacts won't be able to do this.
`id`	Integer	Type of entity that's granted permission to send messages to mailing lists. You received the IDs in Step 2.3.
`org_id`	Integer	Organization ID. In the field, specify: ID of your organization for employees, groups, and departments that belong to it. "0" for external contacts that don't belong to the organization.

Create and submit an API request to create a new list or update an existing one (if you've created it earlier).

Request component	Value
HTTP method	`POST`
Request URL	`https://cloud-api.yandex.net/v1/admin/org/{ORGANIZATION}/mail-lists/{MAILING_LIST}/update-permissions` where `{ORGANIZATION}` — ID of the organization you got at Step 2.1. `{MAILING_LIST}` — ID of the mailing list for which you're creating a whitelist of users with permission to send messages. You obtained it in Step 2.2. Example `https://cloud-api.yandex.net/v1/admin/org/1234567/mail-lists/1150000045826541/update-permissions`
Headers	`Authorization: OAuth {OAUTH TOKEN} Content-Type: application/json` where `{OAUTH-TOKEN}` is the OAuth token you got at Step 1.1.
Request body	You can find it in the `permissions-list.json` file you created in Step 3.1.

You can submit a request to create a mail forwarding rule using the curl command in the following format:

curl -X POST -H "Authorization: OAuth {OAUTH-TOKEN}" -H "Content-Type: application/json" -d "@permissions-list.json" https://cloud-api.yandex.net/v1/admin/org/{ORGANIZATION}/mail-lists/{MAILING_LIST}/update-permissions

For instructions on how to submit a command if you're using Windows, see Step 1.2.

Check the contents of the sender list.

Create and submit a request to get the list:

Request component	Value
HTTP method	`GET`
Request URL	`https://cloud-api.yandex.net/v1/admin/org/{ORGANIZATION}/mail-lists/{MAILING_LIST}/permissions` where `{ORGANIZATION}` — ID of the organization you got at Step 2.1. `{MAILING_LIST}` — ID of the mailing list for which you're creating a whitelist of users with permission to send messages. You obtained it in Step 2.2. Example `https://cloud-api.yandex.net/v1/admin/org/1234567/mail-lists/1150000045826541/permissions`
Headers	`Authorization: OAuth {OAUTH-TOKEN}` where `{OAUTH-TOKEN}` is the OAuth token you got at Step 1.1.

You can submit a request to get a list of mail processing rules using the curl command in the following format:

curl -X GET -H "Authorization: OAuth {OAUTH-TOKEN}" https://cloud-api.yandex.net/v1/admin/org/{ORGANIZATION}/mail-lists/{MAILING_LIST}/permissions

For instructions on how to submit a command if you're using Windows, see Step 1.2.

Analyze the received response. It should contain a list of all organizations, departments, groups, and users whose data was included in the requests according to the instructions from Step 3.2.

How to remove an employee, group, or department from the list

Include information about employees, groups, or departments that were previously granted permission to send messages to the mailing list in the permissions-list-del.json file. Use the following format:
```
{
   "role_actions": [{
         "type": "revoke",
         "roles": [
            "mail_list_sender"
         ],
         "subjects": [{
               "type": "user",
               "id": 1150000062907856,
               "org_id": 1234567
            }
         ]
      }
   ]
}
```
The structure of this file is similar to the file from Step 3.1 (the one that specifies the list of authorized senders). The distinction is that the role_actions.type field specifies a different action type: revoke for revoking permissions instead of grant for granting them.
Make an API request according to the instructions from Step 3.2, adding the permissions-list-del.json file to the request body.

How to overwrite the list of authorized senders

Create a new list of users authorized to send messages to the mailing list and save it in the permissions-list-new.json file. Use the following format:
```
{
   "role_actions": [{
         "type": "overwrite",
         "roles": [
            "mail_list_sender"
         ],
         "subjects": [{
               "type": "department",
               "id": 888,
               "org_id": 1234567
            },{
               "type": "group",
               "id": 444,
               "org_id": 1234567
            },{
               "type": "user",
               "id": 1150000062901254,
               "org_id": 1234567
            }
         ]
      }
   ]
}
```
The structure of this file is similar to the file from Step 3.1 (the one that specifies the list of authorized senders). The distinction is that the role_actions.type field specifies a different action type: overwrite for overwriting permissions instead of grant for granting them.

The overwrite action applies only to the types specified in the request.

You can overwrite authorized senders for all the type values or only for some of them. For example, if you want to overwrite only the departments authorized to send messages to the mailing list, include only the department blocks in the file. This way, other types (such as employees and groups) will remain unchanged.
Make an API request according to the instructions from Step 3.2, adding the permissions-list-new.json file to the request body.

How to authorize everyone to send messages to the mailing list address again or revoke this permission

The parameter type can also have the value anonymous, which means that any user can send messages to the mailing list. To allow everyone to send messages to this address, add a block with this type to the list of authorized senders using the overwrite action. You can leave senders with other types on the list — this won't cause any conflicts.

Create a file permissions-list-all.json with the following content:

{
   "role_actions": [{
         "type": "overwrite",
         "roles": [
            "mail_list_sender"
         ],
         "subjects": [{
               "type": "anonymous",
               "id": 0
            }
         ]
      }
   ]
}

Make an API request according to the instructions from Step 3.2, adding the permissions-list-all.json file to the request body.

To restrict the sender list again, exclude the anonymous block from the list using the revoke action:

Create a file permissions-list-del-all.json with the following content:

{
   "role_actions": [{
         "type": "revoke",
         "roles": [
            "mail_list_sender"
         ],
         "subjects": [{
               "type": "anonymous",
               "id": 0
            }
         ]
      }
   ]
}

Submit the request to the API according to the instructions from Step 3.2, adding the permissions-list-del-all.json file to the request body.

Was the article helpful?

Synonymous addresses (aliases)

Emails sent to nonexistent addresses