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

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

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",
  "domain_name": "domain.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