Документация API

Для пользования некоторыми возможностями платформы VK WorkSpacе доступен API по адресу https://biz.mail.ru/api/v1/. Для доступа к методам API используется протокол HTTPS. Все ответы API имеют формат JSON.

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

 
YYYY-MM-DDTHH:MM:SSZ

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

 
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=value2Host: 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=5c918ed51f38749782b8b2c3ad41a265e560661137363830Host: biz.mail.ruContent-Type: application/x-www-form-urlencodedparameter1=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=5c918ed51f38749782b8b2c3ad41a265e560661137363830Host: biz.mail.ruContent-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.ruContent-Type: multipart/form-data; boundary=------------------------------7b1bfd973086------------------------------7b1bfd973086Content-Disposition: form-data; name="parameter1"value1------------------------------7b1bfd973086Content-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 – контейнер для данных.

При выдаче элементов первой страницы отсутствует поле previous, а последней — поле next соответственно. В случае когда результирующий список элементов помещается на одну страницу, словарь 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=5c918ed51f38749782b8b2c3ad41a265e560661137363830Host: 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=5c918ed51f38749782b8b2c3ad41a265e560661137363830Host: biz.mail.ruContent-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=5c918ed51f38749782b8b2c3ad41a265e560661137363830Host: biz.mail.ruContent-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/domainsAuthorization: Bearer 5c918ed51f38749782b8b2c3ad41a265e560661137363830Host: biz.mail.ru

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

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

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

 
HTTP 403 FORBIDDEN{  "message": "Authentication credentials were not provided."}

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

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

Авторизация пользователя начинается с того, что происходит перенаправление пользователя на https://o2.mail.ru/login для получения кода авторизации. После чего авторизационный код (либо описание ошибки) возвращается веб-серверу приложения в строке запроса на указанный redirect_uri. После получения авторизационного кода приложение может обменять его на токен доступа access_token и токен для обновления токена доступа refresh_token.

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

• client_id: J34ZMt9oJv3jnx4KuSf2E5RQTxKmNbR5

• client_secret: dJyVVMrC2cPftztWdXHjukt2SY97SZMT

• redirect_uri: https://localhost

Список запросов:

1. Получение кода авторизации
2. Получение токена
3. Обновление токена
4. Информация о пользователе по токену

Описание ошибок авторизации: раздел 5. Ошибки авторизации.

 
GET https://o2.mail.ru/login

 
GET /login?client_id=test_client_id&response_type=code&scope=biz.api%20userinfo&redirect_uri=http://domain.net/&state=some_state HTTP/1.1Host: o2.mail.ruContent-Type: text/html

Если пользователь успешно прошел авторизацию:

В случае успешного прохождения авторизации пользователь будет перенаправлен на адрес следующего вида:

 
{redirect_uri}?state={state}&code={authorization_code}

Пример

 
http://domain.net/?state=some_state&code=b42019a80b7d76b388b504cc4366e98425fcbd3e37363830

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

 
{redirect_uri}?error=access_denied&state={state}

Пример

 
http://domain.net/?error=access_denied&state=some_state

Поля

Если ошибка при получении кода авторизации:

См. раздел Ошибки авторизации.

 
POST https://o2.mail.ru/token

Необходимо указать значения параметров client_id и client_secret в параметрах запроса или в заголовке Authorization (Базовая HTTP-авторизация).

 
curl -X POST "https://o2.mail.ru/token" -d "grant_type=authorization_code&code=b42019a80b7d76b388b504cc4366e98425fcbd3e37363830&redirect_uri=http://domain.net/" -u test_client_id:test_client_secretPOST /token HTTP/1.1Host: o2.mail.ruAuthorization: Basic dGVzdF9jbGllbnRfaWQ6dGVzdF9jbGllbnRfc2VjcmV0Content-Type: application/x-www-form-urlencodedgrant_type=authorization_code&code=b42019a80b7d76b388b504cc4366e98425fcbd3e37363830&redirect_uri=http://domain.net/

Если токен успешно получен:

 
HTTP 200 OK { "expires_in": 3600, "access_token": "6c3c7dcebeba73ba878439237b8cdc302031313737363830",     "refresh_token": "b42019a80b7d76b388b504cc4366e98425fcbd3e37363830"   }

Если ошибка при получении токена:

См. раздел Ошибки авторизации.

 
POST https://o2.mail.ru/token

 
curl -X POST "https://o2.mail.ru/token" -d "client_id=test_client_id&grant_type=refresh_token&refresh_token=b42019a80b7d76b388b504cc4366e98425fcbd3e37363830"POST /token HTTP/1.1Host: o2.mail.ruContent-Type: application/x-www-form-urlencodedclient_id=test_client_id&grant_type=refresh_token&refresh_token=b42019a80b7d76b388b504cc4366e98425fcbd3e37363830

Если токен успешно обновлён:

Поля:

Пример:

 
HTTP 200 OK      {     "expires_in": 3600,     "access_token": "4ab90dfebeb475d6aff3702120e6fa4125fcbd3e37363830"   }

Если ошибка при обновлении токена:

См. раздел Ошибки авторизации.

При возращении ошибки token not found необходимо вновь запросить refresh_token.

 
GET https://o2.mail.ru/userinfo

Запрос работает только для токенов, у которых есть scope userinfo.

 
curl "https://o2.mail.ru/userinfo?access_token=8e41b7a475aa7691aeead06ef0db28f989fbab0c37363830"GET /userinfo?access_token=8e41b7a475aa7691aeead06ef0db28f989fbab0c37363830 HTTP/1.1Host: o2.mail.ru

 
HTTP 200 OK{    "gender": "m",    "name": "Алексей Иванов",    "locale": "ru_RU",    "first_name": "Алексей",    "last_name": "Иванов"    "email": "alex@ivanov.ru"}

• В случае неправильного заголовка авторизации возвращается HTTP-статус 401;
• При возникновении внутренней ошибки сервера возвращается HTTP-статус 500;
• В остальных случаях — HTTP-статус 200.

Ответ имеет JSON-формат.

 
HTTP 200 OK{  "error": "invalid request",  "error_code": 2,  "error_description": "Client has issued malformed or illegal request"}

Список запросов:

1. Список доменов

2. Добавление домена

3. Получение домена

4. Варианты подтверждения домена

5. Подтверждение домена

6. Получение результата подтверждения домена

7. Удаление домена

8. Запрос проверки MX-записей

9. Получение результата проверки MX-записей

10. Получение настроек домена

11. Редактирование настроек домена

12. Список логотипов

13. Добавление логотипа

14. Удаление логотипов

15. Генерация ключей DKIM

16. Список алиасов

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

18. Получение алиаса

19. Удаление алиаса

 
GET /domains

 
HTTP 200 OK[  {    "id": 3112,    "name": "test.com",    "confirmed": true,    "migration": false,    "mx_status": -1,    "spf_status": -1,    "shared_address_book": true,    "dkim": {      "status": 0,      "subdomain": "mail._domainkey.test.com",      "value": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDDCXo2/9Yiap0jzdauCeCsAMsuYftQB7oCCE1FIDDMmwoq5hp8HK7KPA+u9Riwmj9zYBAMCBCQckP0wN9Oxs4WUteW1rFLt/6OmNh5b0QrV2M4jy7MLxneu7oqX+dKAKqNZKlH+FReQOoGmaPqadToBeRucif8f1+f8s2YCagzRwIDAQAB"    },    "mxs": {      "records": [        {          "priority": 20,          "record": "alt1.aspmx.l.test.com."        },        {          "priority": 50,          "record": "alt4.aspmx.l.test.com."        },        {          "priority": 40,          "record": "alt3.aspmx.l.test.com."        },        {          "priority": 10,          "record": "aspmx.l.test.com."        },        {          "priority": 30,          "record": "alt2.aspmx.l.test.com."        }      ],      "next_at": "2013-01-15T07:17:34Z",      "checked_at": "2013-01-15T07:17:34Z"    },    "created_at": "2013-01-04T17:29:49Z",    "is_blocked": false,    "user_count": 10,    "is_deleted": false,    "is_blocked": false,    "features": [        "contacts-enabled"    ],    "is_type_confirmed": false,    "domain_version": 2,    "confirmed_at": null,    "confirmation_type": "html",    "contacts": {        "name": "Фамилия",        "email": "test@test.ru",        "phone": "81234567890"    }    "block_reason": null,    "is_trial": false,  }]

Информация о проверке MX-записей:

Информация о DKIM:

Статусы SPF:

Статусы MX:

Cтатусы DKIM:

Поле dkim присутствует только у подтвержденных доменов в случае, если ключи были ранее сгенерированы.

 
POST /domains

 
{  "name": "test.com"}

 
HTTP 201 CREATED{  "id": 3112,  "name": "test.com",  "confirmed": false,  "mx_status": 0,  "spf_status": 0,  "shared_address_book": true,  "mxs": {},  "created_at": "2013-01-04T16:33:07.022Z",  "user_count": 0}

 
GET /domains/{domain_id}

 
HTTP 200 OK{  "id": 1,  "name": "test.com",  "confirmed": true,  "migration": false,  "mx_status": -1,  "spf_status": -1,  "shared_address_book": true,  "dkim": {    "status": 0,    "subdomain": "mail._domainkey.test.com",    "value": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDDCXo2/9Yiap0jzdauCeCsAMsuYftQB7oCCE1FIDDMmwoq5hp8HK7KPA+u9Riwmj9zYBAMCBCQckP0wN9Oxs4WUteW1rFLt/6OmNh5b0QrV2M4jy7MLxneu7oqX+dKAKqNZKlH+FReQOoGmaPqadToBeRucif8f1+f8s2YCagzRwIDAQAB"  },  "mxs": {    "records": [      {        "priority": 20,        "record": "alt1.aspmx.l.test.com."      },      {        "priority": 50,        "record": "alt4.aspmx.l.test.com."      },      {        "priority": 40,        "record": "alt3.aspmx.l.test.com."      },      {        "priority": 10,        "record": "aspmx.l.test.com."      },      {        "priority": 30,        "record": "alt2.aspmx.l.test.com."      }    ],    "next_at": "2013-01-15T07:17:34Z",    "checked_at": "2013-01-15T07:17:34Z"  },  "created_at": "2013-01-04T16:33:07.022Z",  "user_count": 10}

 
GET /domains/{domain_id}/confirm

 
HTTP 200 OK{  "html": {    "url": "http://test.com/mailru-domainrk3scrKVBkXxAnH8.html",    "content": "mailru-domain: rk3scrKVBkXxAnH8",    "filename": "mailru-domainrk3scrKVBkXxAnH8.html"  },  "meta": {    "tag": "<meta name=\"mailru-domain\" content=\"rk3scrKVBkXxAnH8\" />"  },  "dns": {    "record": "mailru-domain: rk3scrKVBkXxAnH8"  },  "registrar": "godaddy"}

 
POST /domains/{domain_id}/confirm

 
{    "method": "html"}

• Запрос на подтверждение домена успешно поставлен в очередь, и получен соответствующий task_id.

 
HTTP 201 CREATED{  "status": "pending",  "message": "Выполняется проверка",  "task_id": "eafbccae-061b-4b85-ad4c-1a39b5e6a812"}

• Запрос на подтверждение домена уже был ранее поставлен в очередь, возвращается task_id этого запроса.

 
HTTP 200 CREATED{  "status": "pending",  "message": "Выполняется проверка",  "task_id": "eafbccae-061b-4b85-ad4c-1a39b5e6a812"}

Возможна ситуация, когда не возвращается task_id. В этом случае надо повторить запрос.

 
GET /domains/{domain_id}/confirm/{task_id}

• Выполняется проверка домена

 
HTTP 200 OK{  "status": "pending",  "message": "Выполняется проверка"}

• Не удалось выполнить подтверждение домена

 
HTTP 200 OK{  "status": "failed",  "message": "Доменное имя не найдено.",  "domain": {    "id": 1,    "name": "test.com",    "confirmed": false,    "migration": false,    "mx_status": 0,    "spf_status": 0,    "mxs": {},    "created_at": "2013-01-04T17:29:49Z",    "user_count": 0  }}

• Домен успешно подтвержден

 
HTTP 200 OK{  "status": "success",  "message": "Домен подтвержден",  "domain": {    "id": 1,    "name": "test.com",    "confirmed": true,    "migration": false,    "mx_status": 0,    "spf_status": 0,    "shared_address_book": true,    "mxs": {      "records": [],      "next_at": "2013-01-15T07:17:34Z",      "checked_at": "2013-01-15T07:17:34Z"    },    "created_at": "2013-01-04T17:29:49Z",    "user_count": 0  }}

 
DELETE /domains/{domain_id}

 
HTTP 204 NO CONTENT

 
HTTP 409 CONFLICT

Домен находится в процессе удаления.

 
POST /domains/{domain_id}/mx

Запрос на подтверждение домена успешно поставлен в очередь, и получен соответствующий task_id:

 
HTTP 201 CREATED    {    "status": "pending",    "message": "Выполняется проверка",    "task_id": "eafbccae-061b-4b85-ad4c-1a39b5e6a812"  }

Запрос на подтверждение домена уже был ранее поставлен в очередь, возвращается task_id этого запроса:

 
HTTP 200 OK    {    "status": "pending",    "message": "Выполняется проверка",    "task_id": "eafbccae-061b-4b85-ad4c-1a39b5e6a812"  }

Возможна ситуация когда не возвращается task_id. В этом случае надо повторить запрос.

 
GET /domains/{domain_id}/mx/{task_id}

Если проверка MX-записей прошла успешно:

 
HTTP 200 OK    {    "status": "success",    "domain": {      "id": 1,      "name": "test.com",      "confirmed": true,      "mx_status": 0,      "spf_status": 0,      "mxs": {        "records": [          {            "priority": 10,            "record": "emx.mail.ru."          }        ],        "next_at": "2013-01-15T07:17:34Z",        "checked_at": "2013-01-15T07:17:34Z"      },      "created_at": "2013-01-04T17:29:49Z",      "user_count": 10    }  }

Если при проверке MX-записей произошла ошибка:

 
HTTP 200 OK    {    "status": "failed",    "message": "Обнаружены проблемы с MX-записями",    "code": "no_needed_mx",    "domain": {      "id": 1,      "name": "test.com",      "confirmed": true,      "mx_status": -1,      "spf_status": 0,      "mxs": {        "records": [          {            "priority": 20,            "record": "alt1.aspmx.l.test.com."          },          {            "priority": 50,            "record": "alt4.aspmx.l.test.com."          },          {            "priority": 40,            "record": "alt3.aspmx.l.test.com."          },          {            "priority": 10,            "record": "aspmx.l.test.com."          },          {            "priority": 30,            "record": "alt2.aspmx.l.test.com."          }        ],        "next_at": "2013-01-15T07:17:34Z",        "checked_at": "2013-01-15T07:17:34Z"      },      "created_at": "2013-01-04T17:29:49Z",      "user_count": 10    }  }

Ошибки

 
GET /domains/{domain_id}/settings

 
HTTP 200 OK{  "default_email": "support@test.com",  "is_agent_collaborated": false,  "user_limit": 5000,  "allow_password_remind": true,  "allow_password_change": true,  "enable_web_agent": true,  "shared_address_book": true,  "theme": "default",  "two_fa_preserved": true,  "is_company": false,  "offer_accepted": true,  "enable_auto_recharge": false,  "is_trial": false,  "partner": "Megafon",  "is_partner": true}

 
PUT /domains/{domain_id}/settings

 
{  "default_email": "support@test.com",  "is_agent_collaborated": false,  "allow_password_remind": true,  "allow_password_change": false,  "enable_web_agent": true,  "shared_address_book": true,  "theme": "t4016",  "two_fa_preserved": true,  "is_company": false,  "enable_auto_recharge": true}

 
HTTP 200 OK{  "default_email": "support@test.com",  "is_agent_collaborated": false,  "user_limit": 5000,  "allow_password_remind": true,  "allow_password_change": false,  "enable_web_agent": false,  "shared_address_book": true,  "theme": "t4016",  "two_fa_preserved": true,  "is_company": false,  "offer_accepted": true,  "enable_auto_recharge": false,  "is_trial": false,  "partner": "Megafon"}

 
GET /domains/{domain_id}/logos

Чтобы получить возможность пользоваться данным методом API, необходимо обратиться в службу поддержки.

 
HTTP 200 OK[  {    "type": "hidpi",    "status": "available",    "url": "https://biz.mail.ru/portal_logo/alex.ru/logo_hidpi.png"  },  {    "type": "common",    "status": "available",    "url": "https://biz.mail.ru/portal_logo/alex.ru/logo.png"  }]

Если статусы всех логотипов домена равны available, то возвращается ответ с HTTP-статусом 200, иначе — 202.

 
POST /domains/{domain_id}/logos

Чтобы получить возможность пользоваться данным методом API, необходимо обратиться в службу поддержки.

 
HTTP 202 ACCEPTED{  "type": "hidpi",  "status": "uploading",  "url": "https://biz.mail.ru/portal_logo/alex.ru/logo_hidpi.png"}

 
DELETE /domains/{domain_id}/logos

Чтобы получить возможность пользоваться данным методом API, необходимо обратиться в службу поддержки.

 
HTTP 202 ACCEPTED[  {    "type": "hidpi",    "status": "removing",    "url": "https://biz.mail.ru/portal_logo/alex.ru/logo_hidpi.png"  }]

 
POST /domains/{domain_id}/dkim

 
{  "id": 1,  "name": "test.com",  "confirmed": true,  "migration": false,  "mx_status": -1,  "spf_status": -1,  "dkim": {    "status": 0,    "subdomain": "mail._domainkey.test.com",    "value": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDDCXo2/9Yiap0jzdauCeCsAMsuYftQB7oCCE1FIDDMmwoq5hp8HK7KPA+u9Riwmj9zYBAMCBCQckP0wN9Oxs4WUteW1rFLt/6OmNh5b0QrV2M4jy7MLxneu7oqX+dKAKqNZKlH+FReQOoGmaPqadToBeRucif8f1+f8s2YCagzRwIDAQAB"  },  "mxs": {...},  "created_at": "2013-01-04T16:33:07.022Z",  "user_count": 10}

Если ключи были успешно сгенерированы, возвращается HTTP-статус 201. Если ключи были сгенерированы ранее, возвращается HTTP-татус 200.

 
GET /domains/{domain_id}/aliases

У одного домена может быть несколько доменов-алиасов. Например, если у домена test.com есть подтвержденный домен-алиас test.ru, и на основном домене test.com есть пользователь alex@test.com, то письма, отправленные на ящик alex@test.ru, придут в основной ящик alex@test.com. Данная возможность позволяет не терять письма даже в том случае, если ваши клиенты или партнеры, перепутают доменную зону (напишут на test.ru вместо test.com). Письмо придет в соответствующий ящик, расположенный на основном домене.

 
HTTP 200 OK[  {    "id": 74121,    "name": "alias.com",    "confirmed": true,    "mx_status": -1,    "spf_status": -1,    "mxs": {      "records": [        {          "priority": 20,          "record": "alt1.aspmx.l.test.com."        }      ],      "next_at": "2013-01-15T07:17:34Z",      "checked_at": "2013-01-15T07:17:34Z"    },    "created_at": "2013-01-04T17:29:59Z",    "alias_for": 3112  }]

 
POST /domains/{domain_id}/aliases

После того как алиас добавлен, его необходимо подтвердить. Подтверждение алиасов выполняется аналогично подтверждению обычных доменов. Для каждого домена может быть добавлено не более 5 подтвержденных доменов-алиасов.

 
{  "name": "alias.com"}

 
HTTP 201 CREATED{  "id": 74121,  "name": "alias.com",  "confirmed": false,  "mx_status": 0,  "spf_status": 0,  "mxs": {},  "created_at": "2013-01-04T17:29:59Z",  "alias_for": 3112}

 
GET /domains/{domain_id}/aliases/{alias_id}

 
HTTP 200 OK{  "id": 74121,  "name": "alias.com",  "confirmed": true,  "mx_status": -1,  "spf_status": -1,  "mxs": {    "records": [      {        "priority": 20,        "record": "alt1.aspmx.l.test.com."      }    ],    "next_at": "2013-01-15T07:17:34Z",    "checked_at": "2013-01-15T07:17:34Z"  },  "created_at": "2013-01-04T17:29:59Z",  "alias_for": 3112}

 
DELETE /domains/{domain_id}/aliases/{alias_id}

 
HTTP 204 NO CONTENT

 
HTTP 409 CONFLICT

Домен находится в процессе удаления.

Список запросов:

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

2. Добавление пользователя

3. Редактирование пользователя

4. Получение пользователя

5. Удаление пользователя

6. Список алиасов

7. Валидация алиаса

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

9. Получение алиаса

10. Удаление алиаса

 
GET /domains/{domain_id}/users

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

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

 
POST /domains/{domain_id}/users

 
{  "username": "alex",  "password": "password",  "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"}

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

 
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": "Алексей",  "lastname": "Пупкин",  "password": "mysecretpassword"}

 
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}

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

 
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}

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

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

Валидация на:

• Такой алиас для данного пользователя уже существует
• Максимальное / минимальное количество символов в алиасе
• Содержание и порядок спецсимволов
• На домене существует алиас с таким именем

 
{  "alias": "alexey",  "domain_name": "domain.com"}

 
HTTP 204 NO CONTENT

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

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

 
{  "username": "alexey"}

 
HTTP 201 CREATED{  "id": 653,  "username": "alexey",  "email": "alexey@test.com",  "created_at": "2013-11-22T14:31:39Z"}

 
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

Список запросов:

1. Список групп

2. Добавление группы

3. Получение группы

4. Редактирование групп

5. Удаление группы

6. Список пользователей группы

7. Добавление пользователя в группу

8. Удаление пользователя из группы

 
GET /domains/{domain_id}/groups

 
HTTP 200 OK[  {    "id": 12383,    "name": "programmers",    "created_at": "2013-01-04T16:33:07Z",    "user_count": 10,    "reply": false  }]

 
POST /domains/{domain_id}/groups

 
{  "name": "programmers"}

 
HTTP 201 CREATED{  "id": 12383,  "name": "programmers",  "created_at": "2013-01-04T16:33:07Z",  "user_count": 0,  "reply": true}

 
GET /domains/{domain_id}/groups/{group_id}

 
HTTP 200 OK{  "id": 12383,  "name": "programmers",  "created_at": "2013-01-04T16:33:07Z",  "user_count": 10,  "reply": false}

 
PUT /domains/{domain_id}/groups/{group_id}

 
{  "reply": false}

 
HTTP 200 OK{  "id": 65072,  "name": "news",  "created_at": "2013-01-04T16:33:07.022Z",  "user_count": 10,  "reply": false}

 
DELETE /domains/{domain_id}/groups/{group_id}

 
HTTP 204 NO CONTENT

 
GET /domains/{domain_id}/groups/{group_id}/users

 
HTTP 200 OK{  "paging": {...},  "data": [    {      "id": 3617,      "username": "alex",      "email": "alex@test.com",      "added_at":  "2013-01-04T16:33:07Z"    }  ]}

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

 
POST /domains/{domain_id}/groups/{group_id}/users

 
{  "id": 3617}

 
HTTP 201 CREATED{  "id": 3617,  "username": "alex",  "email": "alex@test.com",  "added_at": "2013-01-04T16:33:07Z"}

 
DELETE /domains/{domain_id}/groups/{group_id}/users/{user_id}

 
HTTP 204 NO CONTENT

Миграция позволяет настроить перенос и последующую сборку писем со старого почтового сервера. Для сборки писем необходимо включить миграцию для домена и сборщик писем для каждого пользователя.

Список запросов:

1. Состояние миграции

2. Включение миграции

3. Редактирование миграции

4. Выключение миграции

5. Список сборщиков

6. Получение сборщика

7. Включение сборщика

8. Редактирование сборщика

9. Выключение сборщика

 
GET /domains/{domain_id}/migration

 
HTTP 200 OK{  "server": "imap.mail.ru",  "port": 993,  "proto": 1,  "use_ssl": true,  "is_active": true}

 
POST /domains/{domain_id}/migration

 
{  "server": "imap.mail.ru",  "port": 993,  "proto": 1,  "use_ssl": true}

 
HTTP 201 CREATED{  "server": "imap.mail.ru",  "port": 993,  "proto": 1,  "use_ssl": true,  "is_active": true}

 
PUT /domains/{domain_id}/migration

 
{  "server": "imap.mail.ru",  "port": 993,  "use_ssl": true}

 
HTTP 200 OK{  "server": "imap.mail.ru",  "port": 993,  "proto": 1,  "use_ssl": true,  "is_active": true}

При редактировании миграции нельзя изменить протокол. Если есть необходимость в его измении, то нужно выключить текущую миграцию и включить уже с новыми настройками.

 
DELETE /domains/{domain_id}/migration

 
HTTP 204 NO CONTENT

 
GET /domains/{domain_id}/collectors

 
HTTP 200 OK{  "paging": {...},  "data": [    {      "id": 1,      "status": 1,      "email": "user@domain.ru"      "firstname": "Ivan",      "lastname": "Ivanov",      "last_error": ""    }  ]}

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

 
GET /domains/{domain_id}/collectors/{user_id}

 
HTTP 200 OK{  "id": 1,  "status": 1,  "email": "user@domain.ru"  "firstname": "Ivan",  "lastname": "Ivanov",  "last_error": ""}

 
POST /domains/{domain_id}/collectors/{user_id}

 
{  "username": "user@old-mail.ru",  "passwd": "password"}

 
HTTP 201 CREATED{  "status": 7,  "message": "В очереди"}

Для включения сборщика требуется большое количество времени. Поэтому в ответ на запрос возвращается статус 7 (в очереди). После его получения необходимо отправлять запросы на получение сборщика с переодичностью раз в 10 секунд до тех пор, пока не будет получен другой статус.

 
PUT /domains/{domain_id}/collectors/{user_id}

 
{  "username": "user@old-mail.ru",  "passwd": "password"}

 
HTTP 200 OK{  "status": 7,  "message": "В очереди"}

Для редактирования сборщика требуется большое количество времени. Поэтому в ответ на запрос возвращается статус 7 (в очереди). После его получения необходимо отправлять запросы на получение сборщика с переодичностью раз в 10 секунд до тех пор, пока не будет получен другой статус.

 
DELETE /domains/{domain_id}/collectors/{user_id}

 
HTTP 204 NO CONTENT

Список запросов:

1. Список контактов

2. Добавление контакта

3. Редактирование контакта

4. Полное редактирование контакта

5. Получение контакта

6. Удаление контакта

7. Контакты домена

8. Добавление и изменение контакта

 
GET /domains/{domain_id}/contacts/

• ?search=<querystring> — поиск по полям email, first_name, last_name, middle_name
• ?status_not=<querystring> — исключение из выборки контактов с определенным статусом

 
HTTP 200 OK{  "paging": {...},  "data": [    {      "id": 321,      "sid": "a1986b78e78e482bbe78e8ce5d7f85ec",      "email": "alex@test.com",      "first_name": "Алексей",      "last_name": "Пупкин",      "middle_name": "Витальевич",      "emails": [        "a.pupkin@corp.test.com",        "a.pupkin@gmail.com"      ]      "phones": [        {          "phone": "+79123456789",          "type": "work"        }      ]    }  ]}

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

 
POST /domains/{domain_id}/contacts/

 
{  "email": "alex@test.com",  "first_name": "Алексей",  "last_name": "Пупкин"}

 
HTTP 201 CREATED{  "sid": "a1986b78e78e482bbe78e8ce5d7f85ec",  "email": "alex@test.com",  "first_name": "Алексей",  "last_name": "Пупкин"}

 
PATCH /domains/{domain_id}/contacts/{contact_sid}/

 
{  "first_name": "Алексей",  "last_name": "Пупкин",}

 
HTTP 200 OK{  "sid": "a1986b78e78e482bbe78e8ce5d7f85ec",  "email": "alex@test.com",  "first_name": "Алексей",  "last_name": "Пупкин",}

 
PUT /domains/{domain_id}/contacts/{contact_sid}/

 
{    "emails": ["a.pupkin@corp.test.com"],    "phones": [        {          "phone": "+79123456789",          "type": "work"        }    ],    "first_name": "Алексей",    "last_name": "Пупкин",    "middle_name": "Витальевич",    "sid": "a1986b78e78e482bbe78e8ce5d7f85ec",    "email": "alex@test.com",}

 
HTTP 200 OK{  "sid": "a1986b78e78e482bbe78e8ce5d7f85ec",  "email": "alex@test.com",  "first_name": "Алексей",  "last_name": "Пупкин",  "middle_name": "Витальевич",  "emails": [    "a.pupkin@corp.test.com",    "a.pupkin@gmail.com"  ]  "phones": [    {      "phone": "+79123456789",      "type": "work"    }  ]}

 
GET /domains/{domain_id}/contacts/{contact_sid}/

 
HTTP 200 OK{  "sid": "a1986b78e78e482bbe78e8ce5d7f85ec",  "email": "alex@test.com",  "first_name": "Алексей",  "last_name": "Пупкин",  "middle_name": "Витальевич",  "emails": [    "a.pupkin@corp.test.com",    "a.pupkin@gmail.com"  ]  "phones": [    {      "phone": "+79123456789",      "type": "work"    }  ]}

 
DELETE /domains/{domain_id}/contacts/{contact_id}/

 
HTTP 204 OK{  "id": 1231,  "sid": "a1986b78e78e482bbe78e8ce5d7f85ec",  "email": "alex@test.com",  "first_name": "Алексей",  "last_name": "Пупкин",}

 
GET /domains/{domain_id}/contacts/company/

 
HTTP 200 OK{  "name": "Фамилия",  "email": "test1@test.ru",  "phone": "81234567890",  "accounting_email": null,  "position": null}

 
POST /domains/{domain_id}/contacts/company/

 
{  "name": "ФИО",  "email": "test@test.ru",  "phone": "81234567890",  "accounting_email": "acc.test@test.ru",  "position": "Должность"}

 
HTTP 201 CREATED{  "name": "ФИО",  "email": "test@test.ru",  "phone": "81234567890",  "accounting_email": "acc.test@test.ru",  "position": "Должность"}

Список запросов:

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

2. Добавление пользователя

3. Получение пользователя

4. Обновление данных пользователя

5. Удаление пользователя

 
GET /domains/{domain_id}/teambox/users/

 
HTTP 200 OK[  {    "blocked": false,    "email": "user1@some.ru",    "quota": 5368709120,  },  {    "blocked": false,    "email": "user2@some.ru",    "quota": 5368709120  }]

 
POST /domains/{domain_id}/teambox/users/

 
{  "email": "user3@some.ru",  "quota": 3221225472}

 
HTTP 201 CREATED{  "blocked": true,  "email": "user3@some.ru",  "quota": 3221225472}

 
GET /domains/{domain_id}/teambox/users/{user_id}/

 
HTTP 200 OK{  "blocked": false,  "email": "user1@some.ru",  "quota": 5368709120,}

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

Можно обновить оба или одно из полей.

 
{  "blocked": true,  "quota": 3221225472}

 
HTTP 200 OK{  "blocked": true,  "email": "user1@some.ru",  "quota": 3221225472}

 
DELETE /domains/{domain_id}/teambox/users/{user_id}/

 
HTTP 204 NO CONTENT