# Mailganer API: Подписчики

> Раздел документации REST API Mailganer. Общие правила (авторизация, лимиты): https://documentation.mailganer.com/llms.txt

- Базовый адрес: `https://mailganer.com`, формат JSON.
- Авторизация: ключ в заголовке `Authorization: CodeRequest <api_key>`. Исключения: методы `/api/v1/` принимают ключ в теле запроса в поле `api_key`, у постбека свои правила (раздел "Постбек").
- Ключ API: личный кабинет, раздел https://mailganer.com/app/profile/settings/api/
- Лимит: 500 запросов в минуту, при превышении ответ 429.
- Некоторые методы отдают данные страницами по 25 записей: поля `count`, `next`, `previous`, `results`.
- Отправка писем по SMTP описана отдельно, со своей авторизацией: https://documentation.samotpravil.ru/
- Python: официальная библиотека `pip install mailganer`.

### Подписчики

Управление подписчиками (добавление, обновление, отписка, валидация)

#### Получение информации о подписчиках (по имейлу и фильтрам)

`GET https://mailganer.com/api/v2/emails/` · operationId: `getSubscribers`

Возвращает информацию о подписчике(ах) с фильтрацией по query-параметрам.

**Эндпоинт:** `GET https://mailganer.com/api/v2/emails/`  
**Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}`

##### Query-параметры
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
| `email` | string | нет | Имейл, о котором нужна информация; оставьте пустым, чтобы получить по всем подписчикам |
| `source` | int | нет | ID списка; оставьте пустым, чтобы получить по всем спискам |
| `start_date` | string | нет | Фильтр по дате создания подписчика (формат `YYYY-MM-DD`) |
| `end_date` | string | нет | Фильтр по дате создания подписчика (формат `YYYY-MM-DD`) |
| `updated_at_start` | string | нет | Фильтр по дате изменения подписчика (формат `YYYY-MM-DD`) |
| `updated_at_end` | string | нет | Фильтр по дате изменения подписчика (формат `YYYY-MM-DD`) |
| `last_activity_days` | int | нет | Передайте `1`, чтобы дополнительно вернуть в ответе поле активности подписчика |

##### Пример curl
```bash
curl --location --request GET 'https://mailganer.com/api/v2/emails/?email=test@example.com&source=51488' \
--header 'Authorization: CodeRequest {{api_key}}'
```

##### Примечания
- При фильтрации по имейлу `count` всегда равен `1`.
- Если параметры дат не указаны — возвращаются все подписчики.
- Активностью считается последнее открытие рассылки или триггерного письма.
- Поле активности рассчитывается только если передан `last_activity_days=1`.
- Ответ постраничный: поля `next` / `previous` / `count` / `results`.

**Ответы:** `200` Email найден, `400` Ошибка (400) — неверный source

Пример ответа `200`:

```json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 115986334,
      "mg_hash": "ae2f6611598633414be10fe73380863cb59afe7b8",
      "email": "vlad.tochonii@mailganer.ru",
      "source": 57229,
      "email_status": "active",
      "corrected_email": null,
      "name": "",
      "patronymic": "",
      "surname": "",
      "gender": 0,
      "birthday": null,
      "phone": null,
      "city": "",
      "country": "",
      "is_valid": true,
      "doi_is_delivery": true,
      "doi_is_open": false,
      "doi_is_click": false,
      "user_vars": {
        "nps": "ok",
        "test_date": 1667520000
      },
      "bunce_log": null
    }
  ]
}
```

#### Добавление подписчика (одного или массово)

`POST https://mailganer.com/api/v2/emails/` · operationId: `createSubscriber`

Добавляет нового подписчика в указанный список (или списки).

**Эндпоинт:** `POST https://mailganer.com/api/v2/emails/`  
**Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}`  
**Content-Type:** `application/json`

##### Обязательные поля
| Поле | Тип | Описание |
|---|---|---|
| `email` | string | Имейл подписчика |
| `source` | int / array / `"all"` | ID списка. `"all"` — во все списки; можно передать массив ID |

##### Необязательные поля
| Поле | Тип | Описание |
|---|---|---|
| `phone` | string | Телефон |
| `name`, `surname`, `patronymic` | string | ФИО |
| `gender` | int | 1 — мужской, 2 — женский |
| `birthday` | string | Дата рождения, формат `dd.mm.yyyy` |
| `city` | string | Город |
| `add_tag` / `delete_tag` | string / array | Добавить / удалить метку (≤ 140 символов) |
| `add_category` / `delete_category` | string | Добавить / удалить категорию (≤ 250 символов) |
| `user_vars` | object | Пользовательские переменные (`null` в значении — удалить его) |
| `not_doi` / `need_activate` | bool | Управление DOI (требует активации поддержкой) |

##### Пример curl
```bash
curl --location --request POST 'https://mailganer.com/api/v2/emails/' \
--header 'Authorization: CodeRequest {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "test@example.com",
    "source": 49767
}'
```

##### Примечания
- Лимит: **500 запросов/мин**, иначе `429`.
- Ошибка `400` «We have already sent a subscription confirmation email…» — повторное DOI-письмо доступно через 1 час.
- Рекомендуется **v3** ([`/api/v3/emails/`](#operation/createSubscribersV3)) — детальный ответ с массивами `successful` / `failed`.

##### Массовое добавление

До 50 подписчиков за один запрос: тело — JSON-массив тех же объектов.
На странице «Попробовать» пример выбирается в списке примеров тела.

###### Тело запроса

Массив объектов; поля каждого объекта:

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `email` | string | да | Имейл подписчика |
| `source` | int / array / `"all"` | да | ID списка; можно передать несколько или `"all"` — во все списки |
| `phone` | string | нет | Телефон |
| `name` | string | нет | Имя |
| `surname` | string | нет | Фамилия |
| `patronymic` | string | нет | Отчество |
| `gender` | int | нет | 1 — мужской, 2 — женский |
| `birthday` | string | нет | Дата рождения, формат `dd.mm.yyyy` |
| `city` | string | нет | Город |
| `add_tag` | string / array | нет | Добавить метку (≤ 140 символов) |
| `delete_tag` | string | нет | Удалить метку |
| `user_vars` | object | нет | Пользовательские переменные |
| `not_doi` | bool | нет | Отменить отправку письма подтверждения |
| `need_activate` | bool | нет | Отправить письмо подтверждения |
| `add_category` | string | нет | Добавить категорию подписки (≤ 250 символов) |
| `delete_category` | string | нет | Удалить категорию подписки |

###### Пример curl

```bash
curl --location --request POST 'https://mailganer.com/api/v2/emails/' \
--header 'Authorization: CodeRequest {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '[
   {"email": "test1@example.com", "source": 51488, "name": "Федор"},
   {"email": "test2@example.com", "source": 51488, "name": "Пётр"}
]'
```

###### Примечания

- Максимум **50** имейлов за запрос.
- Атомарность: если хотя бы в одном имейле есть ошибка, **ни один** имейл из пакета не будет добавлен.
- В ответе по каждому имейлу возвращаются `id`, `mg_hash`, `in_base` (был ли уже в базе) и `email_status`.
- Повторная отправка DOI-письма возможна через 1 час.
- При `HTTP 503` необходимо повторить запрос с задержкой.

**Ответы:** `201` Success, `400` Error, `401` Error - Недопустимый токен

Пример ответа `201`:

```json
{
  "id": 143788300,
  "mg_hash": "0aa106143788300b392b80ecf023c57d75cc70272",
  "email": "test@example.com",
  "source": 60958,
  "email_status": "fixed",
  "corrected_email": null,
  "name": "Федор",
  "patronymic": "Федорович",
  "surname": "Федоров",
  "gender": 1,
  "birthday": "01.01.1988",
  "phone": "+79123456789",
  "city": null,
  "country": null,
  "is_valid": false,
  "doi_is_delivery": false,
  "doi_is_open": false,
  "doi_is_click": false,
  "user_vars": null,
  "bunce_log": "Global stop list email hash: 554d1a357108862d8de2356531c004a3baf9403"
}
```

#### Получение информации о подписчике по mg_hash

`GET https://mailganer.com/api/v2/emails/{email_hash}/` · operationId: `getSubscriberByHash`

Возвращает информацию о конкретном подписчике по хэшу имейла (`mg_hash`) в URL.

**Эндпоинт:** `GET https://mailganer.com/api/v2/emails/:email_hash/`  
**Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}`

Подписчик определяется по path-переменной `email_hash` (значение `mg_hash`). Query-параметры не требуются.

##### Пример curl
```bash
curl --location --request GET 'https://mailganer.com/api/v2/emails/ae2f6611598633414be10fe73380863cb59afe7b8/' \
--header 'Authorization: CodeRequest {{api_key}}'
```

##### Примечания
- Возвращается тот же формат объекта подписчика, что и в способе 1 (поля `id`, `mg_hash`, `email`, `source`, `email_status`, `user_vars`, `tags`, `categories`, `created`, `modified` и др.).
- Если подписчик по хэшу не найден — вернётся ошибка «Не найдено.».

**Ответы:** `200` Успех (200)

Пример ответа `200`:

```json
{
  "id": 321456817,
  "mg_hash": "54ede83211718173f544604ebe5ad1867543b348185",
  "email": "test@gmail.com",
  "source": 104363,
  "email_status": "active",
  "corrected_email": null,
  "name": "",
  "patronymic": "",
  "surname": "",
  "gender": 0,
  "birthday": null,
  "phone": null,
  "city": null,
  "country": null,
  "is_valid": false,
  "doi_is_delivery": false,
  "doi_is_open": false,
  "doi_is_click": false,
  "user_vars": {
    "date_glob": null,
    "glob": 66432
  },
  "bunce_log": null,
  "tags": [],
  "categories": [],
  "created": "2026-03-03T16:06:29.724362",
  "modified": "2026-03-03T16:06:29.740263"
}
```

#### Обновление информации о подписчике по mg_hash

`PATCH https://mailganer.com/api/v2/emails/{email_hash}/` · operationId: `updateSubscriberByHash`

Обновляет информацию о подписчике, идентифицируя его по хэшу имейла (`mg_hash`) в URL.

**Эндпоинт:** `PATCH https://mailganer.com/api/v2/emails/:email_hash/`  
**Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}`  
**Content-Type:** `application/json`

Подписчик определяется по `mg_hash` в пути (path-переменная `email_hash`), поэтому передавать `email` и `source` в теле не требуется — в теле указываются только обновляемые поля.

##### Тело запроса
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
| `phone` | string | нет | Телефон |
| `name` | string | нет | Имя |
| `surname` | string | нет | Фамилия |
| `patronymic` | string | нет | Отчество |
| `gender` | int | нет | 1 — мужской, 2 — женский |
| `birthday` | string | нет | Дата рождения, формат `dd.mm.yyyy` |
| `city` | string | нет | Город |
| `add_tag` | string / array | нет | Добавить метку |
| `delete_tag` | string | нет | Удалить метку |
| `user_vars` | object | нет | Пользовательские переменные (передайте `null` в значении, чтобы удалить переменную) |
| `not_doi` | bool | нет | Отменить отправку письма подтверждения |
| `need_activate` | bool | нет | Отправить письмо подтверждения |
| `add_category` | string | нет | Добавить категорию подписки |
| `delete_category` | string | нет | Удалить категорию подписки |

##### Пример curl
```bash
curl --location --request PATCH 'https://mailganer.com/api/v2/emails/a05ad557332370764cd4f267a251f3b13289bcff/' \
--header 'Authorization: CodeRequest {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "birthday": "02.01.1990"
}'
```

##### Примечания
- Переменные (`user_vars`) обновляются только если явно переданы в запросе.
- Чтобы удалить значение пользовательской переменной, передайте `null` — работает для всех типов переменных.
- Альтернативные способы обновления: эндпоинт `/api/v2/emails/update/` (передача `email` + `source` в теле) или массовое обновление `/api/v2/emails/mass/`.

**Ответы:** `200` Успех (200), `400` Ошибка (400)

Пример ответа `200`:

```json
{
  "id": 45763880,
  "mg_hash": "53158545763880e054b31ecbad2cf3265d4001d1"
}
```

#### Обновление информации о подписчике по имейлу

`PATCH https://mailganer.com/api/v2/emails/update/` · operationId: `updateSubscriber`

Обновляет информацию о подписчике, идентифицируя его по паре `email` + `source` в теле запроса.

**Эндпоинт:** `PATCH https://mailganer.com/api/v2/emails/update/`  
**Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}`  
**Content-Type:** `application/json`

##### Тело запроса
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
| `email` | string | да | Имейл подписчика |
| `source` | int / array / `"all"` | да | ID списка; можно передать несколько `[49767,50145]` или `"all"` |
| `phone` | string | нет | Телефон |
| `name` | string | нет | Имя |
| `surname` | string | нет | Фамилия |
| `patronymic` | string | нет | Отчество |
| `gender` | int | нет | 1 — мужской, 2 — женский |
| `birthday` | string | нет | Дата рождения, формат `dd.mm.yyyy` |
| `city` | string | нет | Город |
| `add_tag` | string / array | нет | Добавить метку |
| `delete_tag` | string | нет | Удалить метку |
| `user_vars` | object | нет | Пользовательские переменные (передайте `null` в значении, чтобы удалить переменную) |
| `not_doi` | bool | нет | Отменить отправку письма подтверждения |
| `need_activate` | bool | нет | Отправить письмо подтверждения |
| `add_category` | string | нет | Добавить категорию подписки |
| `delete_category` | string | нет | Удалить категорию подписки |

##### Пример curl
```bash
curl --location --request PATCH 'https://mailganer.com/api/v2/emails/update/' \
--header 'Authorization: CodeRequest {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "test@example.com",
    "source": "51488",
    "birthday": "05.01.1990"
}'
```

##### Примечания
- Переменные (`user_vars`) обновляются только если явно переданы в запросе; значение `null` удаляет переменную (для всех типов).
- Альтернативные способы: передача `mg_hash` в URL (`/api/v2/emails/:email_hash/`) или массовое обновление `/api/v2/emails/mass/`.

**Ответы:** `200` Успех (200), `400` Ошибка (400)

Пример ответа `200`:

```json
{
  "id": 45763880,
  "mg_hash": "53158545763880e054b31ecbad2cf3265d4001d1"
}
```

#### Отписка подписчика по mg_hash

`POST https://mailganer.com/api/v2/emails/{email_hash}/unsubscribe/` · operationId: `unsubscribeSubscriberByHash`

Отписывает подписчика, идентифицируя его по хэшу имейла (`mg_hash`) в URL. Это рабочий способ отписки.

**Эндпоинт:** `POST https://mailganer.com/api/v2/emails/:email_hash/unsubscribe/`  
**Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}`

Подписчик определяется по path-переменной `email_hash` (значение `mg_hash`). Тело запроса не требуется.

##### Пример curl
```bash
curl --location --request POST 'https://mailganer.com/api/v2/emails/a05ad557332370764cd4f267a251f3b13289bcff/unsubscribe/' \
--header 'Authorization: CodeRequest {{api_key}}'
```

##### Примечания
- Успешный ответ: `{"email_status": "unsubscribe"}` — статус подписки меняется на «Отписался».
- Если подписчик по хэшу не найден — вернётся ошибка `{"status": "error", "error": "Не найдено."}`.

**Ответы:** `200` Успех (200), `404` Ошибка (404)

Пример ответа `200`:

```json
{
  "email_status": "unsubscribe"
}
```

#### Отписка подписчика по имейлу

`POST https://mailganer.com/api/v2/emails/unsubscribe/` · operationId: `unsubscribeSubscriber`

Отписывает подписчика, идентифицируя его по паре `email` + `source` в теле запроса.

**Эндпоинт:** `POST https://mailganer.com/api/v2/emails/unsubscribe/`  
**Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}`  
**Content-Type:** `application/json`

##### Тело запроса
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
| `email` | string | да | Имейл подписчика |
| `source` | int / array / `"all"` | да | ID списка; можно передать несколько или `"all"` |

##### Пример curl
```bash
curl --location --request POST 'https://mailganer.com/api/v2/emails/unsubscribe/' \
--header 'Authorization: CodeRequest {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "test@example.com",
    "source": "51488"
}'
```

##### Примечания
- Успешный ответ: `{"email_status": "unsubscribe"}` — статус подписки меняется на «Отписался».
- Если подписчик не найден — вернётся ошибка `{"status": "error", "error": "Не найдено."}`.

**Ответы:** `200` Успех (200), `404` Ошибка (404)

Пример ответа `200`:

```json
{
  "email_status": "unsubscribe"
}
```

#### Валидация подписчика

`POST https://mailganer.com/api/v2/emails/validate/` · operationId: `validateSubscriber`

Проверяет валидность имейла. Валидация тарифицируется отдельно.

**Эндпоинт:** `POST https://mailganer.com/api/v2/emails/validate/`  
**Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}`  
**Content-Type:** `application/json`

##### Тело запроса
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
| `email` | string | ✔ | Имейл |
| `source` | int | ✔ | ID списка |

##### Пример curl
```bash
curl --location --request POST 'https://mailganer.com/api/v2/emails/validate/' \
--header 'Authorization: CodeRequest {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "test@example.com",
    "source": 49767
}'
```

##### Примечания
- При слишком частых запросах по одному имейлу — ошибка «Email to many add method».
- В ответе `is_valid` показывает результат проверки; `corrected_email` — исправленный имейл (если было исправление).

**Ответы:** `200` Успех (200)

Пример ответа `200`:

```json
{
  "id": 305384342,
  "mg_hash": "b9827434aeaa159e4c3a723a4a3e91d",
  "email": "test@internet.ru",
  "source": 93455916,
  "email_status": "wait_activated",
  "corrected_email": "test@internet.ru",
  "name": "",
  "patronymic": "",
  "surname": "",
  "gender": 0,
  "birthday": null,
  "phone": null,
  "city": null,
  "country": null,
  "is_valid": true,
  "doi_is_delivery": false,
  "doi_is_open": false,
  "doi_is_click": false,
  "user_vars": {},
  "bunce_log": null,
  "tags": [],
  "categories": [],
  "created": "2025-10-23T17:19:02.635703"
}
```

#### Массовое обновление подписчиков

`PATCH https://mailganer.com/api/v2/emails/mass/` · operationId: `updateSubscribersBulk`

Обновляет до 50 подписчиков за один запрос. Тело — JSON-массив объектов. Операция атомарна.

**Эндпоинт:** `PATCH https://mailganer.com/api/v2/emails/mass/`  
**Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}`  
**Content-Type:** `application/json`

##### Тело запроса
Массив объектов; поля каждого объекта:
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
| `email` | string | да | Имейл подписчика |
| `source` | int / array / `"all"` | да | ID списка (узнать ID: https://mailganer.com/app/settings/); можно передать несколько или `"all"` |
| `phone` | string | нет | Телефон |
| `name` | string | нет | Имя |
| `surname` | string | нет | Фамилия |
| `patronymic` | string | нет | Отчество |
| `gender` | int | нет | 1 — мужской, 2 — женский |
| `birthday` | string | нет | Дата рождения, формат `dd.mm.yyyy` |
| `city` | string | нет | Город |
| `add_tag` | string / array | нет | Добавить метку |
| `delete_tag` | string | нет | Удалить метку |
| `user_vars` | object | нет | Пользовательские переменные; чтобы удалить значение переменной — передайте `null` |
| `not_doi` | bool | нет | Отменяет отправку письма подтверждения; имейл добавляется в статусе «Активен» |
| `need_activate` | bool | нет | Отправляет письмо подтверждения, даже если имейл в статусе «Запрошено подтверждение» |
| `add_category` | string | нет | Добавить категорию подписки |
| `delete_category` | string | нет | Удалить категорию подписки |
| `email_status` | string | нет | Изменить статус. Значение `unsubscribe` меняет статус подписчика с «Активен» на «Отписался» |

##### Пример curl
```bash
curl --location --request PATCH 'https://mailganer.com/api/v2/emails/mass/' \
--header 'Authorization: CodeRequest {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "email": "test@example.com",
        "source": 49767,
        "name": "Федор",
        "surname": "Федоров"
    }
]'
```

##### Примечания
- Максимум **50** имейлов за запрос.
- Атомарность: если хотя бы в одном имейле есть ошибка, **ни один** имейл из пакета не будет обновлён.
- `source` принимает: одиночный ID, массив ID или `"all"` (все списки).
- В ответе по каждому имейлу возвращаются `id` и `mg_hash`.

**Ответы:** `200` Успех (200), `400` Ошибка (400)

Пример ответа `200`:

```json
[
  {
    "id": 45764030,
    "mg_hash": "100330457640309ee63894dced455d110aebcb2b"
  },
  {
    "id": 45764025,
    "mg_hash": "e031e245764025457cb340b96fd670419cf95bb2"
  }
]
```

#### Массовое добавление подписчиков (v3)

`POST https://mailganer.com/api/v3/emails/` · operationId: `createSubscribersV3`

Добавляет подписчиков пачкой и возвращает подробный ответ: по каждой записи видно, добавилась она или нет и почему.

**Эндпоинт:** `POST https://mailganer.com/api/v3/emails/`  
**Авторизация:** заголовок `Authorization: CodeRequest {{api_key}}`  
**Content-Type:** `application/json`

Тело запроса — массив объектов подписчиков. Одиночный объект без массива метод тоже принимает.

##### Лимиты

- Не больше 2000 запросов в минуту на аккаунт, при превышении вернётся `429`.
- Жёсткого ограничения на размер пачки нет, но разумный размер — до нескольких сотен записей: ответ содержит полную карточку каждого добавленного подписчика.

##### Особенности

- Пустая строка в необязательном поле равнозначна тому, что поле не передано: сохранённое значение не затирается. Незнакомые ключи игнорируются.
- Если в `source` передан массив или `"all"`, подписчик создаётся в каждом списке, но в ответе придёт одна запись — по последнему обработанному списку.
- Даты в переменных: dd.mm.yyyy, dd-mm-yyyy, yyyy.mm.dd, yyyy-mm-dd; дата-время — те же форматы плюс ЧЧ:ММ или ЧЧ:ММ:СС. Минимальный год 1900. Логические переменные принимают да/true/yes и нет/false/no в любом регистре.
- Повторная отправка того же имейла в тот же список ошибкой не считается: подписчик обновляется и приходит в `successful`.

##### Ответ

Ответ всегда содержит три массива: `successful` (добавлены), `failed` (не добавлены, в `errors` причина по каждому параметру), `warnings` (добавлены, но часть данных не записалась — чаще всего переменная не заведена в списке).

| Код | Когда |
|---|---|
| `201` | Все записи добавлены, ошибок и предупреждений нет |
| `207` | Часть записей не добавлена (непустой `failed`) или есть предупреждения (непустой `warnings`) |
| `401` | Ключ API не передан или неверен, тело ответа пустое |
| `429` | Превышен лимит 2000 запросов в минуту |
| `503` | Сервис временно не смог обработать запрос, повторите через небольшую паузу |

##### Предупреждения по переменным

| Когда возникает | Текст |
|---|---|
| Переменной нет в списке | Переменная "имя" не найдена и была пропущена. |
| В целочисленную переменную передано не целое число | Значение "..." не является целым числом и было пропущено. |
| В числовую переменную передано не число | Значение "..." не является числом и было пропущено. |
| Некорректная дата или год меньше 1900 | Значение "..." не является корректной датой и было пропущено. |
| Некорректная дата-время | Значение "..." не является корректной датой/временем и было пропущено. |
| Логическое значение не из списка да/true/yes/нет/false/no | Значение "..." не является логическим значением и было пропущено. |
| Строка не является корректным JSON (JSON-переменная) | Значение "..." не является корректным JSON и было пропущено. |
| В значении найден html, а html не включён | В значении переменной "имя" обнаружен html-код; значение не записано. |

##### Возможные ошибки

- `400` We have already sent a subscription confirmation email to this email. Resending is possible in 1 hour. — слишком много запросов на реактивацию имейла, повтор через час.
- Email to many add method — при частых запросах второй запрос на тот же имейл не дождался обработки первого.

##### Пример curl

```bash
curl --location --request POST 'https://mailganer.com/api/v3/emails/' \
--header 'Authorization: CodeRequest {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '[
    {"email": "test1@example.com", "source": 49767},
    {"email": "test2@example.com", "source": 49767}
]'
```

**Ответы:** `201` Все записи добавлены, `207` Часть записей не добавлена или есть предупреждения, `401` Ключ API не передан или неверен, тело пустое, `429` Превышен лимит 2000 запросов в минуту, `503` Сервис временно недоступен, повторите запрос позже

Пример ответа `201`:

```json
{
  "successful": [
    {
      "id": 48744043,
      "mg_hash": "6b36dc48744043ec34ab9613c7f165b3e60f54f4",
      "email": "test1@example.com",
      "source": 49767,
      "email_status": "wait_activated",
      "corrected_email": "test1@example.com",
      "name": "Федор",
      "patronymic": "Федорович",
      "surname": "Федоров",
      "gender": 1,
      "birthday": "01.01.1988",
      "phone": "79123456789",
      "city": null,
      "country": null,
      "is_valid": false,
      "doi_is_delivery": false,
      "doi_is_open": false,
      "doi_is_click": false,
      "user_vars": {},
      "bunce_log": null,
      "tags": [
        "клиент"
      ],
      "categories": [
        "новости"
      ],
      "created": "2026-07-28T12:59:39.399936",
      "modified": "2026-07-28T12:59:39.459810"
    }
  ],
  "failed": [],
  "warnings": []
}
```