.. meta:: :description: Пользователи документация ============ Пользователи ============ Список пользователей ==================== :: GET /domains/{domain_id}/users Параметры фильтрации (строки запроса) -------------- cloud: optional: string Фильтрует список пользователей, оставляя только тех, которые есть в облаке. Может принимать только одно значение - "true". Используется для частного случая ТОЛЬКО в связке с no_limit=true. В остальных случаях не работает. no_limit: optional: string Отключает пагинацию для списка пользователей. Принимает только одно значение - "true" Используется для частного случая ТОЛЬКО в связке с cloud=true. В остальных случаях не работает. Ответ ----- .. code-block:: javascript HTTP 200 OK { "paging": {...}, "data": [ { "id": 414, "username": "alex", "email": "alex@test.com", "nick": null, "firstname": "Алексей", "lastname": "Пупкин", "is_spammer": False, "groups": [ { "id": 563, "name": "programmers" } ], "avatars": { "90x90": "//filin.mail.ru/pic?width=90&height=90&email=alex@test.com" }, "created_at": "2013-01-09T12:03:28Z", "status": "active", "status_at": "2013-01-09T12:03:28Z", "contact": null } ] } Список пользователей разбивается на страницы. Механизм постраничной навигации описан в разделе :ref:`Pagination`. Описание полей -------------- +------------------------------+---------+---------------------------------------------------------+ | Название | Тип | Описание | +==============================+=========+=========================================================+ | id | Number | Идентификатор пользователя | +------------------------------+---------+---------------------------------------------------------+ | username | String | Логин пользователя | +------------------------------+---------+---------------------------------------------------------+ | email | String | Email пользователя | +------------------------------+---------+---------------------------------------------------------+ | nick | String | Ник пользователя | +------------------------------+---------+---------------------------------------------------------+ | firstname | String | Имя пользователя | +------------------------------+---------+---------------------------------------------------------+ | lastname | String | Фамилия пользователя | +------------------------------+---------+---------------------------------------------------------+ | is_spammer | Boolean | Показывает, является пользователь спамером или нет | +------------------------------+---------+---------------------------------------------------------+ | groups | Array | Список групп, в которых состоит пользователь. Каждый | | | | элемент списка содержит идентификатор (id) и имя (name) | | | | группы. | +------------------------------+---------+---------------------------------------------------------+ | avatars | Object | Словарь, содержащий информацию об аватарах | | | | пользователя. Ключ - размер аватара, значение - его | | | | местонахождение. | +------------------------------+---------+---------------------------------------------------------+ | created_at | String | Дата создания пользователя | +------------------------------+---------+---------------------------------------------------------+ | :ref:`status` | String | Статус пользователя | +------------------------------+---------+---------------------------------------------------------+ | status_at | String | Дата изменения статуса пользователя | +------------------------------+---------+---------------------------------------------------------+ | contact | Object | Контакт адресной книги, прикреплённый к пользователю | | | | см. :ref:`Add_contact` | +------------------------------+---------+---------------------------------------------------------+ | glasha_enabled | Boolean | Включение для пользователя функционала "Ассистента" | | | | (доступно для доменов с флагом mail-permissions) | +------------------------------+---------+---------------------------------------------------------+ .. _User_statuses: Статусы ------- +--------------+----------------------------------------------------------------------+ | Значение | Описание | +==============+======================================================================+ | active | Пользователь является активным | +--------------+----------------------------------------------------------------------+ | blocked | Пользователь заблокирован | +--------------+----------------------------------------------------------------------+ | soft-blocked | "Мягкая" блокировка пользователя. Блокируется авторизация, при | | | попытке пройти авторизацию пользователь будет перенаправлен на | | | страницу https://account.mail.ru/errors/login/blocked?project=biz. | | | Входящие письма продолжают поступать в почтовый ящик. | +--------------+----------------------------------------------------------------------+ | purging | Пользователь помечен для удаления. Удаление можно отменить. | +--------------+----------------------------------------------------------------------+ | deleted | Пользователь находится в стадии удаления. Любые действия над | | | пользователем, за исключением получения информации о нём, запрещены. | +--------------+----------------------------------------------------------------------+ Добавление пользователя ======================= :: POST /domains/{domain_id}/users Поля ---- username: required: string Имя почтового ящика password: required: string Пароль :ref:`password_type`: optional: string Тип пароля firstname: optional: string Имя пользователя lastname: optional: string Фамилия пользователя .. code-block:: javascript { "username": "alex", "password": "password", "firstname": "Алексей", "lastname": "Пупкин" } Поля firstname и lastname нельзя передавать по-отдельности. При указании значения хотя бы одного из этих полей, указание второго поля является обязательным. Ответ ----- .. code-block:: javascript HTTP 201 CREATED { "id": 341, "username": "alex", "email": "alex@test.com", "nick": null, "firstname": "Алексей", "lastname": "Пупкин", "is_spammer": False, "groups": [], "avatars": { "90x90": "//filin.mail.ru/pic?width=90&height=90&email=alex@test.com" }, "created_at": "2013-01-09T12:03:28Z", "status": "active", "status_at": "2013-01-09T12:03:28Z" } Ошибки ------ +------+----------------------------------------------------+ | code | message | +======+====================================================+ | 140 | Невозможно создать пользователя. | +------+----------------------------------------------------+ | 141 | Администратор с неподтверждённым номером | | | телефона может добавить не более 5 пользователей. | +------+----------------------------------------------------+ | 142 | Превышен лимит количества пользователей на домене. | | | Обратитесь в службу поддержки. | +------+----------------------------------------------------+ | 192 | Нельзя восстанавливать терминированных | | | пользователей | +------+----------------------------------------------------+ .. _Password_types: Типы паролей ------------ +----------+--------------------------------------------+ | Значение | Описание | +==========+============================================+ | text | Пароль в открытом виде (по умолчанию) | +----------+--------------------------------------------+ | md5 | MD5-хеш пароля | +----------+--------------------------------------------+ .. _Add_contact: Добавление контакта адресной книги ----------------------------------- При создании и редактировании пользователя можно одним запросом создать соответствующий ему контакт адресной книги. Основная статья: :ref:`Contacts` . .. code-block:: javascript POST /domains/{domain_id}/users { "username": "alex", "password": "password", "firstname": "Алексей", "lastname": "Пупкин", "contact": { "first_name": "Алексей", "last_name": "Пупкин (работа)", "phones": [ { "phone": "+79123456789", "type": "work" } ] } } Ответ: .. code-block:: javascript HTTP 201 CREATED { "id": 341, "username": "alex", "email": "alex@test.com", "nick": null, "firstname": "Алексей", "lastname": "Пупкин", "is_spammer": False, "groups": [], "avatars": { "90x90": "//filin.mail.ru/pic?width=90&height=90&email=alex@test.com" }, "created_at": "2013-01-09T12:03:28Z", "status": "active", "status_at": "2013-01-09T12:03:28Z", "contact": { "sid": "a1986b78e78e482bbe78e8ce5d7f85ec", "email": "alex@test.com", "first_name": "Алексей", "last_name": "Пупкин (работа)", "phones": [ { "phone": "+79123456789", "type": "work" } ] } } Редактирование пользователя =========================== :: PUT /domains/{domain_id}/users/{user_id} :: PATCH /domains/{domain_id}/users/{user_id} Параметры --------- firstname: optional: string Имя пользователя. Может быть пустым lastname: optional: string Фамилия пользователя. Может быть пустым password: optional: string Новый пароль пользователя :ref:`password_type`: optional: string Тип пароля :ref:`status`: optional: string Статус пользователя. Разрешенные значения: active, blocked, soft-blocked .. code-block:: javascript { "firstname": "Алексей", "lastname": "Пупкин", "password": "mysecretpassword" } Редактирование полей firstname и lastname не может производиться по-отдельности. При указании значения хотя бы одного из этих полей, указание второго поля является обязательным. Ответ ----- .. code-block:: javascript HTTP 200 OK { "id": 4124, "username": "alex", "email": "alex@test.com", "nick": null, "firstname": "Алексей", "lastname": "Пупкин", "is_spammer": False, "groups": [], "avatars": { "90x90": "//filin.mail.ru/pic?width=90&height=90&email=alex@test.com" }, "created_at": "2013-01-09T12:03:28Z", "status": "active", "status_at": "2013-08-11T14:52:23Z", "contact": null } Ошибки ------ +------+----------------------------------------------------+ | code | message | +======+====================================================+ | 145 | Невозможно сменить пароль пользователя. | +------+----------------------------------------------------+ | 147 | Невозможно отредактировать пользователя. | +------+----------------------------------------------------+ Редактирование контакта адресной книги --------------------------------------- При создании и редактировании пользователя можно одним запросом создать соответствующий ему контакт адресной книги. Основная статья: :ref:`Contacts` . .. code-block:: javascript PUT/PATCH /domains/{domain_id}/users/{user_id} { "firstname": "Лёша", "contact": { "first_name": "Лёша", "middle_name": "Витальевич", } } Ответ: .. code-block:: javascript HTTP 200 OK { "id": 4124, "username": "alex", "email": "alex@test.com", "nick": null, "firstname": "Лёша", "lastname": "Пупкин", "is_spammer": False, "groups": [], "avatars": { "90x90": "//filin.mail.ru/pic?width=90&height=90&email=alex@test.com" }, "created_at": "2013-01-09T12:03:28Z", "status": "active", "status_at": "2013-08-11T14:52:23Z", "contact": { "sid": "a1986b78e78e482bbe78e8ce5d7f85ec", "email": "alex@test.com", "first_name": "Лёша", "last_name": "Пупкин (работа)", "middle_name": "Витальевич", "phones": [ { "phone": "+79123456789", "type": "work" } ] } } Получение пользователя ====================== :: GET /domains/{domain_id}/users/{user_id} Ответ ----- .. code-block:: javascript HTTP 200 OK { "id": 4123, "username": "alex", "email": "alex@test.com", "nick": null, "firstname": "Алексей", "lastname": "Пупкин", "is_spammer": False, "groups": [ { "id": 1341, "name": "programmers" } ], "avatars": { "90x90": "//filin.mail.ru/pic?width=90&height=90&email=alex@test.com" }, "created_at": "2013-01-09T12:03:28Z", "status": "active", "status_at": "2013-01-09T12:03:28Z", "contact": null } Удаление пользователя ===================== :: DELETE /domains/{domain_id}/users/{user_id} Ответ ----- .. code-block:: javascript HTTP 200 OK { "id": 1231, "username": "alex", "email": "alex@test.com", "nick": null, "firstname": "Алексей", "lastname": "Пупкин", "is_spammer": False, "groups": [], "avatars": { "90x90": "//filin.mail.ru/pic?width=90&height=90&email=alex@test.com" }, "created_at": "2013-01-09T12:03:28Z", "status": "deleted", "status_at": "2013-01-12T11:00:45Z", "contact": null } Ошибки ------ +------+---------------------------------------------------+ | code | message | +======+===================================================+ | 134 | Невозможно удалить ящик по умолчанию. | | | Смените его в Настройках. | +------+---------------------------------------------------+ | 135 | Невозможно удалить ящик администратора домена. | +------+---------------------------------------------------+ Список алиасов ============== :: GET /domains/{domain_id}/users/{user_id}/aliases У одного пользователя может быть несколько адресов-алиасов. Например, если у пользователя alex@test.com есть алиас alexey@test.com, то письма, отправленные на любой из этих адресов, придут на основной адрес. Ответ ----- .. code-block:: javascript HTTP 200 OK [ { "id": 653, "username": "alexey", "email": "alexey@test.com", "created_at": "2013-11-22T14:31:39Z" } ] Описание полей -------------- +------------+---------+---------------------------------------------------------+ | Название | Тип | Описание | +============+=========+=========================================================+ | id | Number | Идентификатор алиаса | +------------+---------+---------------------------------------------------------+ | username | String | Имя алиаса | +------------+---------+---------------------------------------------------------+ | email | String | Email алиаса | +------------+---------+---------------------------------------------------------+ | created_at | String | Дата создания алиаса | +------------+---------+---------------------------------------------------------+ Валидация алиаса ================= :: POST /domains/{domain_id}/users/{user_id}/aliases/validate Валидация на: * Такой алиас для данного пользователя уже существует * Максимальное / минимальное количество символов в алиасе * Содержание и порядок спецсимволов * На домене существует алиас с таким именем Поля ---- alias: required: string Алиас .. code-block:: javascript { "alias": "alexey@test.com" } Ответ ----- .. code-block:: javascript HTTP 204 NO CONTENT Ошибки ------ +------+---------------------------------------------------+ | code | message | +======+===================================================+ | 400 | Описание ошибки валидации | +------+---------------------------------------------------+ Добавление алиаса ================= :: POST /domains/{domain_id}/users/{user_id}/aliases Для каждого пользователя может быть добавлено не более 5 алиасов. Поля ---- username: required: string Имя почтового ящика .. code-block:: javascript { "username": "alexey" } Ответ ----- .. code-block:: javascript HTTP 201 CREATED { "id": 653, "username": "alexey", "email": "alexey@test.com", "created_at": "2013-11-22T14:31:39Z" } Ошибки ------ +------+---------------------------------------------------+ | code | message | +======+===================================================+ | 143 | Превышен лимит алиасов для этого пользователя | +------+---------------------------------------------------+ | 144 | Невозможно добавить синоним пользователя | +------+---------------------------------------------------+ Получение алиаса ================ :: GET /domains/{domain_id}/users/{user_id}/aliases/{alias_id} Ответ ----- .. code-block:: javascript HTTP 200 OK { "id": 653, "username": "alexey", "email": "alexey@test.com", "created_at": "2013-11-22T14:31:39Z" } Удаление алиаса =============== :: DELETE /domains/{domain_id}/users/{user_id}/aliases/{alias_id} Ответ ----- .. code-block:: javascript HTTP 204 NO CONTENT