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

POST https://mailganer.com/api/v3/emails/
Метод добавляет подписчиков пачкой и возвращает детализированный ответ: по каждой записи отдельно видно, добавилась она или нет и почему. Это поведение по умолчанию — включать его через поддержку не нужно.

Авторизация — заголовком Authorization: CodeRequest <ключ API>, как и в остальных методах (см. «Авторизация»). Тело запроса — массив объектов в JSON. Одиночный объект без массива метод тоже принимает.

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

Список параметров запроса (json)

Пустая строка в необязательном поле равнозначна тому, что поле не передано, — сохранённое значение не затирается. Незнакомые ключи игнорируются.

Если в source передан массив или "all", подписчик создаётся в каждом списке, но в ответе придёт одна запись — по последнему обработанному списку.

Пример запроса (json)

[
    {
        "email": "test1@example.com",
        "source": 49767,
        "name": "Федор",
        "patronymic": "Федорович",
        "surname": "Федоров",
        "gender": 1,
        "birthday": "01.01.1988",
        "phone": "+79123456789",
        "add_tag": "клиент",
        "add_category": "новости",
        "user_vars": {
            "text": "Текст",
            "integer": 12,
            "float": 12.5,
            "date": "01.01.1971",
            "dateTime": "01.01.1971 11:00:00",
            "boolean": true,
            "goods": [
                {"name": "Apple iPhone X", "price": 54000},
                {"name": "Samsung Galaxy S21", "price": 64000}
            ]
        }
    },
    {
        "email": "test2@example.com",
        "source": [49767, 50145]
    }
]
Ответ всегда содержит три массива:


Код ответа зависит от результата:

Список параметров ответа: элемент массива successful (json)

Список параметров ответа: элемент массива failed (json)

Список параметров ответа: элемент массива warnings (json)

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

Даты в переменных принимаются в форматах dd.mm.yyyy, dd-mm-yyyy, yyyy.mm.dd, yyyy-mm-dd; дата-время — те же форматы плюс ЧЧ:ММ или ЧЧ:ММ:СС. Минимальный год — 1900. Логические переменные принимают да/true/yes и нет/false/no в любом регистре.

Можно передать массив до 50 имейлов.
Доступ к API включает поддержка. Если у аккаунта доступ не открыт, метод вернёт 403.
Если хотя бы в одном имейле будет ошибка, то ни один имейл из пакета не добавится.

Возможные значения статусов подписчика

Пример ответа: все записи добавлены (201)

{
    "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": []
}

Пример ответа: часть записей не добавлена (207)

{
    "successful": [
        {
            "id": 48744045,
            "mg_hash": "07f361487440459e09f923bf5d29b1fdf65bdd1d",
            "email": "test1@example.com",
            "source": 49767,
            "email_status": "wait_activated",
            "corrected_email": "test1@example.com",
            "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": {},
            "bunce_log": null,
            "tags": [],
            "categories": [],
            "created": "2026-07-28T13:00:00.098209",
            "modified": "2026-07-28T13:00:00.148395"
        }
    ],
    "failed": [
        {
            "email": "not-an-email",
            "errors": {
                "email": ["Введите корректный адрес электронной почты. Указан невалидный not-an-email"]
            }
        },
        {
            "email": "test3@example.com",
            "errors": {
                "source": ["Not found site (source=[99999999]) or site blocked"]
            }
        },
        {
            "email": "test4@example.com",
            "errors": {
                "source": ["Это поле обязательно."]
            }
        }
    ],
    "warnings": []
}

Пример ответа: подписчик добавлен, но переменная не применилась (207)

{
    "successful": [
        {
            "id": 48744046,
            "mg_hash": "6dacb748744046a1c59895f50b5c533586f38088",
            "email": "test1@example.com",
            "source": 49767,
            "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": {},
            "bunce_log": null,
            "tags": [],
            "categories": [],
            "created": "2026-07-28T13:00:00.415978",
            "modified": "2026-07-28T13:00:00.450651"
        }
    ],
    "failed": [],
    "warnings": [
        {
            "email": "test1@example.com",
            "errors": [
                {
                    "message": "Переменная \"my_var\" не найдена и была пропущена.",
                    "var_name": "my_var",
                    "value": "test"
                }
            ]
        }
    ]
}

Пример curl

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

Как обрабатывать ответ

  1. Проверьте код ответа. 201 — всё добавлено, разбирать нечего.
  2. При 207 пройдите по failed: в errors лежит причина по каждому параметру. Такие записи не добавлены — их нужно исправить и отправить повторно.
  3. Просмотрите warnings: эти подписчики добавлены, но часть данных не записалась. Чаще всего причина — переменная не заведена в списке, куда добавляется подписчик.
  4. Повторная отправка того же имейла в тот же список ошибкой не считается: подписчик один, запись обновляется, в ответе он придёт в successful.