Домены¶

Список доменов¶

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

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

Название	Тип	Описание
id	Number	Идентификатор домена
name	String	Название домена
confirmed	Boolean	Показывает, подтвержден домен или нет
migration	Boolean	Показывает, включена миграция для домена или нет
mx_status	Number	MX статус
spf_status	Number	SPF статус
dkim	Object	Информация о DKIM
mxs	Object	Информация о проверке MX-записей
shared_address_book	Boolean	Флаг включения/выключения общей адресной книги домена в почте
created_at	String	Дата регистрации домена
is_blocked	Boolean	Показывает заблокирован домен или нет
user_count	Number	Количество пользователей на домене

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

Название	Тип	Описание
next_at	String	Дата следующей проверки домена
checked_at	String	Дата проверки домена
records	Array	Список текущих MX-записей
record	String	Значение MX-записи
priority	Number	Приоритет MX-записи

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

Название	Тип	Описание
status	Number	DKIM статус
subdomain	String	Поддомен, на котором находится запись
value	String	Значение записи

SPF статусы¶

Статус	Описание
-1	Среди SPF-записей нет необходимой
0	Проверка SPF-записей не проводилась
1	Среди SPF-записей есть необходимая, и она является единственной

MX статусы¶

Статус	Описание
-2	Среди найденных MX-записей присутствует необходимая, но она не является единственной
-1	Среди найденных MX-записей нет необходимой
0	Проверка MX-записей не проводилась
1	Среди найденных MX-записей есть необходимая, и она является единственной

DKIM статусы¶

status	description
-1	Нет необходимой DKIM-записи
0	Проверка DKIM-записей не проводилась
1	Есть необходимая DKIM-запись

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

Добавление домена¶

POST /domains

Поля¶

name: required: string: Имя домена

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

Ошибки¶

code	message
0	Ошибка валидации данных.
90	Ошибка добавления домена
91	Домен уже добавлен
92	Вы уже являетесь администратором этого домена.

Необходимо подтвердить владение доменом в течение недели после добавления. Все неподтвержденные домены удаляются по истечении этого срока.

Получение домена¶

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

Ошибки¶

code	message
103	Домен уже подтверждён.

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

POST /domains/{domain_id}/confirm

Поля¶

method: required: string: Выбранный метод - html, meta, dns

{
    "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. В этом случае надо повторить запрос.

Ошибки¶

code	message
101	Вы не являетесь владельцем данного домена.
102	Ошибка при подтверждении домена.
103	Домен уже подтверждён.
105	Неизвестный способ подтверждения.
106	Превышен лимит количества администрируемых доменов. Обратитесь в службу поддержки.
108	Превышен лимит синонимов для данного домена
110	Способ подтверждения не доступен

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

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

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

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

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. В этом случае надо повторить запрос.

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

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

Ошибки

code	message	description
has_other_mxs	Обнаружены лишние MX-записи	Домен имеет нужную MX-запись, но она не является единственной.
no_needed_mx	Необходимые MX-записи не найдены	Домен не имеет необходимой mx записи.

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

GET /domains/{domain_id}/settings

Ответ¶

HTTP 200 OK

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

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

PUT /domains/{domain_id}/settings

Поля¶

default_email: optional: string

В этот ящик будут приходить все письма, которые отправлены на несуществующие адреса вашего домена. Например, письмо, отправленное по ошибке на mi@moi_domen.ru, вместо me@moi_domen.ru, попадет в этот ящик.

is_agent_collaborated: optional: boolean

Флаг автоматического добавления пользователей в список контактов Агента (флаг работает, пока на домене не более 100 пользователей)

allow_password_remind: optional: boolean

Флаг разрешения восстановления пароля пользователями

allow_password_change: optional: boolean

Флаг разрешения изменения пароли в ящике

enable_web_agent: optional: boolean

Флаг включения/выключения веб-агента в почте

shared_address_book: optional: boolean

Флаг включения/выключения общей адресной книги домена в почте

theme: optional: string

Тема интерфейса в почте (default|t4000...t4016)

two_fa_preserved: optional: boolean

Запрет снятия двухфакторной аутентификации в почте

is_company: optional: boolean

Принадлежность домена к Юридическому/Физическому Лицу Значения:

true: Юридическое лицо; false: Физическое лицо; null: Не определено.

Примечание:: флаг невозможно поменять после установки

offer_accepted: optional: boolean

Согласие или не согласие с договором оферты

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

Ответ¶

HTTP 200 OK

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

Список логотипов¶

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.

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

Название	Тип	Описание
type	String	Тип логотипа
status	String	Статус логотипа
url	String	Ссылка, по которой доступен логотип

Типы логотипов¶

Тип	Размер
common	240х52
hidpi	480x104

Статусы логотипов¶

Статус	Описание
available	Логотип доступен
removing	Выполняется удаление логотипа
uploading	Выполняется загрузка логотипа

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

POST /domains/{domain_id}/logos

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

Поля¶

image: required: file: файл с изображением логотипа (допустимый размер логотипа зависит от типа логотипа), формат изображения должен быть png
type: required: string: тип логотипа

Ответ¶

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

Генерация ключей dkim¶

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

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

Название	Тип	Описание
id	Number	Идентификатор домена
name	String	Название домена
confirmed	Boolean	Показывает, подтвержден домен или нет
mx_status	Number	MX статус
spf_status	Number	SPF статус
mxs	Object	Информация о проверке MX-записей
created_at	String	Дата регистрации домена
alias_for	Number	Идентификатор домена, к которому относится алиас

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

POST /domains/{domain_id}/aliases

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

Поля¶

name: required: string: Имя алиаса

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

Ошибки¶

code	message
90	Ошибка добавления домена
91	Домен уже добавлен
108	Превышен лимит синонимов для данного домена

Получение алиаса¶

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

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