API¶

Сервис «Mail.Ru для Бизнеса» предоставляет почту для вашей компании. Для пользования некоторыми возможностями данного сервиса доступно API по адресу https://biz.mail.ru/api/v1/. Для доступа к методам API используется протокол HTTPS. Все ответы API имеют JSON-формат.

Все таймстампы возвращаются в формате ISO 8601, в UTC:

YYYY-MM-DDTHH:MM:SSZ

Для регистрации клиента API, а также в случае возникновения вопросов и предложений следует обратиться в службу поддержки.

Параметры¶

Некоторые параметры запросов, такие как идентификатор домена, идентификатор пользователя, передаются как часть адреса:

https://biz.mail.ru/api/v1/domain/{domain_id}/users/{user_id}

Остальные параметры передаются в зависимости от типа запроса либо в теле запроса, либо в строке запроса. Для GET-запросов параметры методов передаются в строке запроса.

curl "https://biz.mail.ru/api/v1/test?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830&parameter1=value1&parameter2=value2"

GET /api/v1/test?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830&parameter1=value1&parameter2=value2
Host: biz.mail.ru

Для остальных типов запросов параметры методов передаются в теле запроса. Содержимое тела запроса в этом случае определяется типом указанным в заголовке Content-Type запроса:

application/x-www-form-urlencoded

curl -X POST  "https://biz.mail.ru/api/v1/test?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830" -d "parameter1=value1&parameter2=value2"

POST /api/v1/test?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830
Host: biz.mail.ru
Content-Type: application/x-www-form-urlencoded

parameter1=value1&parameter2=value2

application/json

curl -X POST  'https://biz.mail.ru/api/v1/test?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830' -d '{"parameter1": "value1", "parameter2": "value2"}' -H 'Content-Type: application/json'

POST /api/v1/test?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830
Host: biz.mail.ru
Content-Type: application/x-www-form-urlencoded

{"parameter1": "value1", "parameter2": "value2"}

multipart/form-data

curl -X POST  "https://biz.mail.ru/api/v1/test?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830" -F "parameter1=value1" -F "parameter2=value2"

POST /api/v1/test?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830'
Host: biz.mail.ru
Content-Type: multipart/form-data; boundary=------------------------------7b1bfd973086

------------------------------7b1bfd973086
Content-Disposition: form-data; name="parameter1"

value1
------------------------------7b1bfd973086
Content-Disposition: form-data; name="parameter2"

value2
------------------------------7b1bfd973086--

Постраничная навигация¶

Результаты некоторых запросов, возвращающих список однотипных элементов, например, список пользователей на домене, выдаются постранично. Атрибут offset показывает смещение выдаваемых элементов в результирующем списке, а атрибут limit - количество выдаваемых элементов на странице, причем limit по умолчанию равен 25 и может принимать максимальное значение, равное 100.

GET /domains/1/users?limit=25&offset=25

В ответе на запрос возвращается словарь, содержащий следующие поля:

paging, которое содержит поля:
- previous – url предыдущей страницы
- next – url следующей страницы
- results_count – общее количество объектов на всех страницах
data – контейнер для данных

При выдаче элементов 1-ой страницы отсутствует поле previous, а последней - поле next соответственно. В случае, когда результирующий список элементов помещается на 1 страницу, словарь paging будет содержать только поле results_count.

{
  "paging": {
    "previous": "https://biz.mail.ru/api/domains/1/users?limit=25&offset=0",
    "results_count": 26
  },
  "data": [
    {
      "id": 14423,
      "username": "alex",
      "email": "alex@test.com",
      "nick": null,
      "firstname": "Алексей",
      "lastname": "Пупкин",
      "groups": [
        {
          "id": 3241,
          "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"
    }
  ]
}

Авторизация¶

Авторизация клиентов API выполняется на основе протокола авторизации OAuth 2.0. В каждом запросе помимо параметров вызываемого метода следует передавать access token. Процедуры получения и обновления access token описаны в главе «OAuth 2.0 Авторизация».

Примеры¶

GET-запрос

curl "https://biz.mail.ru/api/v1/domains?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830"

GET /api/v1/domains?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830
Host: biz.mail.ru

POST-запрос

curl -X POST "https://biz.mail.ru/api/v1/domains?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830" -d "name=domain.net"

POST /api/v1/domains?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830
Host: biz.mail.ru
Content-Type: application/x-www-form-urlencoded

name=domain.net

PUT-запрос

curl -X PUT "https://biz.mail.ru/api/v1/domains/1/users/2341?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830" -d "lastname=Kotikov"

PUT /api/v1/domains?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830
Host: biz.mail.ru
Content-Type: application/x-www-form-urlencoded

lastname=Kotikov

access token можно передавать как часть строки запроса (см. выше) или включать его в заголовок Authorization: Bearer.

Пример¶

curl "https://biz.mail.ru/api/v1/domains" -H "Authorization: Bearer 5c918ed51f38749782b8b2c3ad41a265e560661137363830"

GET /api/v1/domains
Authorization: Bearer 5c918ed51f38749782b8b2c3ad41a265e560661137363830
Host: biz.mail.ru

Ошибки клиента¶

В случае ошибок клиента возвращается ответ с HTTP-кодом 400.

Ответ¶

HTTP 400 BAD REQUEST

{
  "code": 0,
  "message": "Ошибка валидации данных.",
  "data":  {
    "name": ["Недопустимое имя домена"]
  }
}

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

Название	Тип	Описание
message	String	Текст описания ошибки.
code	Number	Уникальный код ошибки.
data	String	Дополнительная информация об ошибке. Может отсутствовать.

Общие ошибки¶

code	message
0	Ошибка валидации данных
1	Домен не подтвержден
2	В данный момент Вы не можете воспользоваться выбранной услугой

Для неавторизованных пользователей отдается ответ с HTTP-кодом 403.

HTTP 403 FORBIDDEN

{
  "message": "Authentication credentials were not provided."
}

В случае превышения лимита запросов к какому-либо из методов отдается ответ с HTTP-кодом 429.

Действующие ограничения¶

Любые запросы с одного IP-адреса (не более 200 запросов в минуту)
Запросы на добавление домена (не более 50 запросов в минуту)