Пользователи

Список пользователей

GET /domains/{domain_id}/users

Параметры фильтрации (строки запроса)

cloud: optional: string
Фильтрует список пользователей, оставляя только тех, которые есть в облаке. Может принимать только одно значение - “true”. Используется для частного случая ТОЛЬКО в связке с no_limit=true. В остальных случаях не работает.
no_limit: optional: string
Отключает пагинацию для списка пользователей. Принимает только одно значение - “true” Используется для частного случая ТОЛЬКО в связке с cloud=true. В остальных случаях не работает.

Ответ

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
    }
  ]
}

Список пользователей разбивается на страницы. Механизм постраничной навигации описан в разделе Постраничная навигация.

Описание полей

Название Тип Описание
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 Дата создания пользователя
status String Статус пользователя
status_at String Дата изменения статуса пользователя
contact Object Контакт адресной книги, прикреплённый к пользователю см. Добавление контакта адресной книги
glasha_enabled Boolean Включение для пользователя функционала “Ассистента” (доступно для доменов с флагом mail-permissions)

Статусы

Значение Описание
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
Пароль
password_type: optional: string
Тип пароля
firstname: optional: string
Имя пользователя
lastname: optional: string
Фамилия пользователя
{
  "username": "alex",
  "password": "password",
  "firstname": "Алексей",
  "lastname": "Пупкин"
}

Поля firstname и lastname нельзя передавать по-отдельности. При указании значения хотя бы одного из этих полей, указание второго поля является обязательным.

Ответ

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 Нельзя восстанавливать терминированных пользователей

Типы паролей

Значение Описание
text Пароль в открытом виде (по умолчанию)
md5 MD5-хеш пароля

Добавление контакта адресной книги

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

POST /domains/{domain_id}/users

{
  "username": "alex",
  "password": "password",
  "firstname": "Алексей",
  "lastname": "Пупкин",
  "contact": {
    "first_name": "Алексей",
    "last_name": "Пупкин (работа)",
    "phones": [
      {
        "phone": "+79123456789",
        "type": "work"
      }
    ]
  }
}

Ответ:

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
Новый пароль пользователя
password_type: optional: string
Тип пароля
status: optional: string
Статус пользователя. Разрешенные значения: active, blocked, soft-blocked
{
  "firstname": "Алексей",
  "lastname": "Пупкин",
  "password": "mysecretpassword"
}

Редактирование полей firstname и lastname не может производиться по-отдельности. При указании значения хотя бы одного из этих полей, указание второго поля является обязательным.

Ответ

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 Невозможно отредактировать пользователя.

Редактирование контакта адресной книги

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

PUT/PATCH /domains/{domain_id}/users/{user_id}

{
  "firstname": "Лёша",
  "contact": {
    "first_name": "Лёша",
    "middle_name": "Витальевич",
  }
}

Ответ:

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}

Ответ

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}

Ответ

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, то письма, отправленные на любой из этих адресов, придут на основной адрес.

Ответ

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
Алиас
{
  "alias": "alexey@test.com"
}

Ответ

HTTP 204 NO CONTENT

Ошибки

code message
400 Описание ошибки валидации

Добавление алиаса

POST /domains/{domain_id}/users/{user_id}/aliases

Для каждого пользователя может быть добавлено не более 5 алиасов.

Поля

username: required: string
Имя почтового ящика
{
  "username": "alexey"
}

Ответ

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}

Ответ

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}

Ответ

HTTP 204 NO CONTENT