.. meta:: :description: API документация, сервис “Mail.Ru для Бизнеса”, как подключать почту mail.ru для домена через их API .. _API: === 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¶meter1=value1¶meter2=value2" GET /api/v1/test?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830¶meter1=value1¶meter2=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¶meter2=value2" POST /api/v1/test?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830 Host: biz.mail.ru Content-Type: application/x-www-form-urlencoded parameter1=value1¶meter2=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-- .. _Pagination: Постраничная навигация ====================== Результаты некоторых запросов, возвращающих список однотипных элементов, например, список пользователей на домене, выдаются постранично. Атрибут ``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``. .. code-block:: javascript { "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. Ответ ----- .. code-block:: javascript HTTP 400 BAD REQUEST { "code": 0, "message": "Ошибка валидации данных.", "data": { "name": ["Недопустимое имя домена"] } } Описание полей -------------- +----------+--------+-----------------------------------------------------------+ | Название | Тип | Описание | +==========+========+===========================================================+ | message | String | Текст описания ошибки. | +----------+--------+-----------------------------------------------------------+ | code | Number | Уникальный код ошибки. | +----------+--------+-----------------------------------------------------------+ | data | String | Дополнительная информация об ошибке. Может отсутствовать. | +----------+--------+-----------------------------------------------------------+ Общие ошибки ------------ +------+----------------------------------------------------+ | code | message | +======+====================================================+ | 0 | Ошибка валидации данных | +------+----------------------------------------------------+ | 1 | Домен не подтвержден | +------+----------------------------------------------------+ | 2 | В данный момент Вы не можете воспользоваться | | | выбранной услугой | +------+----------------------------------------------------+ Для неавторизованных пользователей отдается ответ с HTTP-кодом 403. .. code-block:: javascript HTTP 403 FORBIDDEN { "message": "Authentication credentials were not provided." } В случае превышения лимита запросов к какому-либо из методов отдается ответ с HTTP-кодом 429. Действующие ограничения ======================= - Любые запросы с одного IP-адреса (не более 200 запросов в минуту) - Запросы на добавление домена (не более 50 запросов в минуту) .. - Отправка приглашения администраторам (не более 10 писем в час) .. - Запрос на добавление номера телефона (не более 10 запросов в минуту) .. - Запрос на добавление номера с одного IP-адреса (не более 10 запросов в сутки) .. - Запрос на добавление номера телефона с одинаковыми первыми 5-ю цифрами (не более 10 запросов в сутки) .. - Запрос на отправку SMS (не более 3 SMS в час)