меню
Generic selectors
Exact matches only
Search in title
Search in content
Search in posts
Search in pages

Метод checkEmail

Метод позволяет проверить статус доставки email-сообщений, отправленных методом sendEmail.

Для ускорения работы метода sendEmail статусы доставки хранятся ограниченное время – только один месяц.

Принцип использования

Синтаксис и URL для вызова метода
checkEmail (string email_id)
https://api.unisender.com/ru/api/checkEmail?format=json&api_key=KEY&email_id=ID1,ID2,ID3
Аргументы Описание
api_key * Ключ доступа к API
email_id * Код сообщения, возвращённый методом sendEmail. Возможно указание до 500 кодов email через запятую.
Возвращаемое значение
JSON-объект с массивом statuses, каждый из элементов которого — объект с двумя полями: поле «id» с кодом сообщения и поле «status» со статусом этого сообщения.
Если был запрошен один код сообщения, то в целях обратной совместимости на одном уровне с массивом statuses присутствует ещё и одиночное поле status, значение которого совпадает со значением поля status первого (и единственного в этом случае) элемента массива statuses.
Возможные значения поля status описаны ниже. В будущем вероятно появление новых значений, но будет соблюдаться принцип: если статус начинается с err_ – значит, доставка не удалась. Если с ok_ – то доставка ещё идёт или удачно завершена. Исключение – статус ‘not_sent’.
Поскольку мы не сохраняем полный текст всех писем, отправляемых через API sendEmail, для некоторых результатов отправки вам может понадобиться переотправить письмо. В частности, это результат err_lost.
not_sent Сообщение еще не было обработано.
ok_sent Сообщение было отправлено, промежуточный статус до получения ответа о доставке/недоставке.
ok_delivered Сообщение доставлено. Может измениться на ‘ok_read’, ‘ok_link_visited’, ‘ok_unsubscribed’ или ‘ok_spam_folder’.
ok_read Сообщение доставлено и зарегистрировано его прочтение. Может измениться на ‘ok_link_visited’, ‘ok_unsubscribed’ или ‘ok_spam_folder’.
ok_fbl Сообщение доставлено, но помещено в папку «спам» получателем. К сожалению, редкие почтовые службы сообщают такую информацию, поэтому таких статусов обычно немного.
ok_link_visited Сообщение доставлено, прочитано и выполнен переход по одной из ссылок. Может измениться на ‘ok_unsubscribed’ или ‘ok_spam_folder’.
ok_unsubscribed Сообщение доставлено и прочитано, но пользователь отписался по ссылке в письме. Статус окончательный.
err_blacklisted Сообщение отвергнуто из-за блеклистинга. Будет переотправлено.
err_will_retry Одна или несколько попыток доставки оказались неудачными, но попытки продолжаются. Статус неокончательный.
err_resend Фактически эквивалентен err_will_retry, с некоторыми несущественными внутренними особенностями.
err_internal Внутренний сбой. Необходима переотправка письма. Статус окончательный.
err_user_unknown Адрес не существует, доставка не удалась. Статус окончательный.
err_user_inactive Адрес когда-то существовал, но сейчас отключен. Доставка не удалась. Статус окончательный.
err_mailbox_discarded Почтовый ящик получателя удален. Статус окончательный
err_mailbox_full Почтовый ящик получателя переполнен. Статус окончательный.
err_no_dns Нет записи или некорректная запись в DNS.
err_no_smtp Запись в DNS есть, но smtp сервер отсутствует.
err_domain_inactive Домен не принимает почту или не существует. Статус окончательный.
err_destination_misconfigured Домен не принимает почту из-за неверной настройки на стороне получателя, причем ответ сервера содержит информацию об устранимой причине (например, используется неработающий блеклист и т. п.)
err_spam_rejected Письмо отклонено сервером как спам.
err_too_large Письмо превышает допустимый размер по данным сервера получателя. Также причиной может быть отклонение письма сервером получателя из-за непринимаемого типа вложения. Например, .exe.
err_giveup В этот статус переводятся сообщения из статусов err_will_retry, err_resend после истечения срока повторных попыток.
err_spam_removed Отправка отменена из-за блокировки рассылки как спама. Статус неокончательный, может быть изменён на not_sent, delayed или err_spam_may_retry после переговоров с почтовой службой получателя.
err_spam_may_retry Эквивалент err_spam_rejected, но вы можете переотправить сообщение путём генерации нового такого же письма.
ok_spam_folder Письмо доставлено, но сервер получателя поместил его в папку «Спам». Статус окончательный.
err_delivery_failed Доставка не удалась по иным причинам. Статус окончательный.
err_will_retry Одна или несколько попыток доставки оказались неудачными, но попытки продолжаются. Статус неокончательный.
err_skip_letter Отправка отменена, так как email адрес недоступен (кроме случаев err_unsubscribed и err_not_allowed).
err_spam_skipped Отправка отменена из-за блокировки рассылки как спама. Результат неокончательный, может быть изменён на not_sent, delayed или err_spam_may_retry после переговоров с почтовой службой получателя.
err_unsubscribed Отправка не выполнялась, т.к. адрес, по которому пытались отправить письмо, ранее отписался. Вы можете пометить этот адрес как отписавшийся и в своей базе данных и больше не отправлять на него. Статус окончательный.
err_src_invalid Неправильный адрес отправителя. Используется, если «невалидность email-а отправителя» обнаружилась не на стадии приёма задания и проверки параметров, а на более поздней стадии, когда осуществляется детальная проверка того, что нужно отправить. Статус окончательный.
err_dest_invalid Неправильный адрес получателя. Используется, если «невалидность email-а получателя» обнаружилась не на стадии приёма задания и проверки параметров, а на более поздней стадии, когда осуществляется подробная проверка того, что нужно отправить. Статус окончательный.
err_not_allowed Отправка отменена, так как сотрудники технической поддержки заблокировали рассылку или же из-за заблокированного адреса получателя или блокировки вашего аккаунта. Статус окончательный.
err_over_quota Отправка отменена, из-за нехватки средств на счету или из-за превышений по тарифу.
err_not_available Адрес, по которому вы пытались отправить письмо, не является доступным (т.е. ранее отправки на него приводили к ответу от сервера вида  «адрес не существует» или «блокировка по спаму») Доступность адреса теоретически может быть восстановлена через несколько дней или недель, поэтому можно его не вычёркивать полностью из списка потенциальных адресатов. Статус окончательный.
err_unreachable Отправка отменена, так как адрес недоступен, но, в отличие от статуса err_not_available, доступность адресу возвращена не будет. Статус окончательный.
err_lost Письмо не было отправлено из-за несогласованности его частей (например, в теле письма передается ссылка на изображение во вложениях, но само изображение во вложениях не передано), или было утеряно из-за сбоя на нашей стороне. Отправитель должен переотправить письмо самостоятельно, т.к. оригинал не сохранился. Статус окончательный.
skip_dup_unreachable Адрес недоступен, отправка не удалась. Статус окончательный.
skip_dup_temp_unreachable Адрес временно недоступен. Отправка не удалась. Статус окончательный.
skip_dup_mailbox_full Почтовый ящик получателя переполнен. Статус окончательный.
Пример возвращаемого значения:

{
  "result": {
    "statuses": [
      {
        "id": "8219732882",
        "status": "not_sent"
      },
      {
        "id": "8269722886",
        "status": "ok_delivered"
      },
      {
        "id": "8219722800",
        "status": "err_unsubscribed"
      }
    ]
  },
  "failed_email_id": [
    {
      "23": "email_id does not exist"
    },
    {
      "573405639": "passed email_id doesn't match passed api_key"
    }
  ]
}

Примеры на PHP

Мы настоятельно рекомендуем использовать POST-запросы, так как это более безопасный метод передачи данных, нежели GET. Используйте SSL-соединение с UniSender. Подробнее о методах соединения здесь.

Пример с использованием POST-запроса

// Ваш ключ доступа к API (из Личного Кабинета)
$api_key = "xxxxxxxxxxxxxx";

// Перечислим несколько id через запятую
$email_id = "2387465634,782932646,25723123";

// Создаём POST-запрос
$POST = array (
  'api_key' => $api_key,
  'email_id' => $email_id
);

// Устанавливаем соединение
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $POST);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_URL, 
            'https://api.unisender.com/ru/api/checkEmail?format=json');
$result = curl_exec($ch);

if ($result) {
  // Раскодируем ответ API-сервера
  $jsonObj = json_decode($result);

  if(null===$jsonObj) {
    // Ошибка в полученном ответе
    echo "Invalid JSON";

  }
  elseif(!empty($jsonObj->error)) {
    // Ошибка получения статуса сообщения
    echo "An error occured: " . $jsonObj->error . "(code: " . $jsonObj->code . ")";

  } else {
    // Статусы доставки сообщения получены
    echo "E-mail delivery statuses: " . print_r($jsonObj->result->statuses, true);

  }
} else {
  // Ошибка соединения с API-сервером
  echo "API access error";
}

Пример с использованием GET-запроса

// Ваш ключ доступа к API (из Личного Кабинета)
$api_key = "xxxxxxxxxxxxxxxxxxx";

// Перечислим несколько id через запятую
$email_id = urlencode("2387465634,782932646,25723123");

// Создаём GET-запрос
$api_url = "https://api.unisender.com/ru/api/checkEmail?format=json".
           "&api_key=$api_key&email_id=$email_id";

// Делаем запрос на API-сервер
$result = file_get_contents($api_url);

if ($result) {
  // Раскодируем ответ API-сервера
  $jsonObj = json_decode($result);

  if(null===$jsonObj) {
    // Ошибка в полученном ответе
    echo "Invalid JSON";

  }
  elseif(!empty($jsonObj->error)) {
    // Ошибка получения статуса сообщения
    echo "An error occured: " . $jsonObj->error . "(code: " . $jsonObj->code . ")";

  } else {
    // Статусы доставки сообщения получены
    echo "E-mail message delivery statuses: " . print_r($jsonObj->result->statuses, true);
  }

} else {
  // Ошибка соединения с API-сервером
  echo "API access error";
}