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

Метод exportContacts

Экспорт данных контактов из UniSender. Возможны различные сценарии использования этого метода:

  • Резервное копирование
    Вы можете выгрузить всю базу контактов с максимально подробной информацией.
  • Синхронизация с данными вашего сервера
    Предположим, что вы всегда добавляете новых контактов сначала на свой сервер, а потом уже в UniSender. Отписаться же контакт может как через UniSender, так и вы сами можете удалить его на своём сервере. Тогда для синхронизации сначала вам надо выгрузить только email-адреса (или телефоны) контактов через exportContacts и проверить, нет ли среди них удалённых с вашего сервера. Затем с помощью importContacts вы импортируете новых, меняете данные у изменённых и удаляете тех, кто удалён на вашем сервере.

Максимальное количество экспортируемых за один вызов данных ограничено, поэтому при большом количестве контактов необходимо выгружать их по частям (не более 1000 записей за раз), используя аргументы offset и limit.

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

Синтаксис и URL для вызова метода
exportContacts ([int list_id, string array field_names, int offset, int limit, string tag, string email,
string email_status, string phone,
string phone_status])
https://api.unisender.com/ru/api/exportContacts?format=json&api_key=KEY
&list_id=134&field_names[]=email&field_names[]=email_status&tag=TAG
&email=EMAIL&email_status=EMAIL_STATUS&phone=PHONE&phone_status
=PHONE_STATUS
Аргументы
api_key * Ключ доступа к API
list_id Необязательный код экспортируемого списка. Если не указан, будут экспортированы все списки. Коды списков можно узнать с помощью метода getLists.

Внимание: если список указан, то в результат выгрузки попадут и те email-адреса, которые не включены в список, но у контактов есть телефоны, включённые в этот список.

field_names Массив названий полей, которые надо экспортировать. Если отсутствует, то экспортируются все возможные поля.
email E-mail адрес. Если этот параметр указан, то результат будет содержать только один контакт с таким e-mail адресом.
phone Номер телефона. Если этот параметр указан, то результат будет содержать только один контакт с таким номером телефона.
tag Метка. Если этот параметр указан, то при поиске будут учтены только контакты, имеющие такую метку.
email_status Статус e-mail адреса. Если этот параметр указан, то результат будет содержать только контакты с таким статусом e-mail адреса. Допустимые значения указаны в перечне системных полей ниже.
phone_status Статус телефона. Если этот параметр указан, то результат будет содержать только контакты с таким статусом телефона. Допустимые значения указаны в перечне системных полей ниже.
limit Положительное целое число — количество экспортируемых контактов. Максимально возможное значение, оно же значение по умолчанию, равно 1000.
offset Неотрицательное целое число — номер первого экспортируемого контакта. Если не задано, то по умолчанию экспорт идёт с начала и offset считается равным нулю. При экспорте больших списков рекомендуется делать несколько вызовов порциями по тысяче контактов. Смотрите также следующий аргумент limit.
Возвращаемое значение
JSON-объект со следующими полями:
field_names Массив названий полей данных. Названия системных полей не зависят от языка, названия пользовательских полей берутся из названий для подстановки.

Перечень системных полей:
tags Перечисленные через запятую метки
email E-mail адрес контакта
email_status Статус e-mail адреса. Возможные значения полей при экспорте:

  • new — новый.
  • invited — отправлено приглашение со ссылкой подтверждения подписки, ждём ответа, рассылка по такому адресу пока невозможна.
  • active — активный адрес, возможна рассылка.
  • inactive — адрес отключён через веб-интерфейс, никакие рассылки невозможны, но можно снова включить через веб-интерфейс.
  • unsubscribed — адресат отписался от всех рассылок.
  • blocked — адрес заблокирован администрацией нашего сервиса (например, по жалобе адресата), рассылка по нему невозможна. Разблокировка возможна только по просьбе самого адресата.
  • activation_requested — запрошена активация адреса у администрации UniSender, рассылка пока невозможна.
email_availability Доступность e-mail адреса по результатам последних рассылок. Отправка будет производиться только по доступным адресам.

Возможные значения:

  • available — адрес доступен
  • unreachable — адрес недоступен
  • temp_unreachable — адрес временно недоступен
  • mailbox_full — почтовый ящик переполнен
  • spam_rejected — письмо сочтено спамом сервером получателя. Через несколько дней этот статус будет снят.
  • spam_folder — письмо помещено в спам самим получателем.
email_add_time Время добавления email адреса в формате «ГГГГ-ММ-ДД чч:мм:сс» в UTC. Если адрес был добавлен в результате подписки через форму, время совпадает со временем запроса подписки.
email_request_ip IP-адрес, с которого поступил запрос подписки. Равен 0.0.0.0 для адресов, добавленных вручную или для которых адрес неизвестен.
email_confirm_time Дата и время подтверждения подписки (перехода по ссылке подтверждения из письма)в формате «ГГГГ-ММ-ДД чч:мм:сс».
email_confirm_ip IP-адрес, с которого поступил запрос подписки. Равен 0.0.0.0 для адресов, адрес которых неизвестен.
email_list_ids Перечисленные через запятую коды списков, на которые подписан email
email_subscribe_times Перечисленные через запятую дата-время подписки на список, количество и порядок дат соответствует количеству и порядку кодов списков в email_list_ids. Даты указаны в UTC, в формате «ГГГГ-ММ-ДД чч:мм:сс».
email_unsubscribed_list_ids Перечисленные через запятую коды списков, в которые email входит, но со статусом «отписан». Эти коды не входят в email_list_ids
phone Мобильный телефон контакта
phone_status Статус телефона, один из:

  • new — новый
  • active — активный телефон, возможна рассылка. При добавлении этот статус телефон получает по умолчанию.
  • inactive — номер отключён через веб-интерфейс, никакие рассылки невозможны, но можно снова включить через веб-интерфейс.
  • unsubscribed — адресат отписался от всех рассылок.
  • blocked — адресат заблокирован администрацией нашего сервиса (например, по жалобе адресата), рассылка по нему невозможна. Разблокировка возможна только по просьбе самого адресата.
phone_availability Доступность телефона по результатам последних рассылок. Отправка SMS будет производиться только по доступным телефонам. Возможные значения:

  • available — телефон доступен
  • not_allowed — отправка на этот телефон не поддерживается провайдером
  • temp_unreachable — последняя отправка не удалась
  • not_exist — телефон не существует
phone_add_time Время добавления телефона в формате «ГГГГ-ММ-ДД чч:мм:сс» в UTC
phone_request_ip IP-адрес, с которого поступил запрос подписки. Равен 0.0.0.0 для адресов, добавленных вручную или для которых адрес неизвестен.
phone_list_ids, phone_subscribe_times, phone_unsubscribed_list_ids Смысл полей совпадает с аналогичными полями для email. Обратите внимание, что для телефонов отсутствуют поля phone_confirm_ip и phone_confirm_time.

Запрос выгрузки полей email_list_ids, email_subscribe_times, email_unsubscribed_list_ids и tags создаёт дополнительную нагрузку, поэтому лучше запрашивать только нужные поля, а не запрашивать всё подряд и отфильтровывать ненужное на вашей стороне.

data Двумерный массив с данными. Каждая строка соответствует одному контакту.
 

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

{
  "result":{
    "field_names":[
      "email",
      "Имя",
      "email_status",
      "email_availability",
      "email_subscribed_lists",
      "email_subscribed_times",
      "email_add_time"
    ],
    "data":[
      [
        "test1@example.org",
        "Вася",
        "active",
        "available",
        "123,127",
        "2010-06-15 12:54:07,2010-06-15 12:54:07",
        "2010-06-15 12:34:01"
      ],
      [
        "test2@example.org",
        "Петя",
        "invited",
        "unreachable",
        "123",
        "2010-03-15 18:12:55",
        "2010-03-15 18:12:55"
      ],
      [
        "test3@example.org",
        "Коля",
        "active",
        "avaialable",
        "",
        "",
        "2010-03-15 18:12:55"
      ]
    ]
  }
}

Примеры формирования URL-запроса

https://api.unisender.com/ru/api/exportContacts?format=json&api_key=KEY 
— получить данные всех контактов (на самом деле только первых 1000, 
смотрите описание параметра limit)
https://api.unisender.com/ru/api/exportContacts?format=json&api_key=KEY&
list_id=222333&field_names[]=Name 
— получить только имена контактов на список с кодом 222333 (на самом деле только первые 1000,
смотрите описание параметра limit
https://api.unisender.com/ru/api/exportContacts?format=json&api_key=
KEY&list_id=222333 — получить данные контактов на список с кодом 
222333 (на самом деле только первых 1000, 
смотрите описание параметра limit)

Примеры на PHP

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

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

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

// Список для экспорта
$list = "420";

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

// Устанавливаем соединение
$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/exportContacts?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 {
    // Выводим полученные данные
    $number_of_fields = count($jsonObj->result->field_names);
    echo "<table border='1'>";
    echo "<tr>";
    for ($i=0;$i<$number_of_fields;$i++){
      echo "<td> " . $jsonObj->result->field_names[$i] . "</td>";
    };
    echo "</tr>";
    foreach ($jsonObj->result->data as $one) {
      echo "<tr>";
      for ($i=0;$i<$number_of_fields;$i++){
        echo "<td> " . $one[$i] . "</td>";
      };
      echo "</tr>";
    }
    echo "</table>";

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

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

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

// Список для экспорта
$list = "420";

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

// Делаем запрос на 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 {
    // Выводим полученные данные
    $number_of_fields = count($jsonObj->result->field_names);
    echo "<table border='1'>";
    echo "<tr>";
    for ($i=0;$i<$number_of_fields;$i++){
      echo "<td> " . $jsonObj->result->field_names[$i] . "</td>";
    };
    echo "</tr>";
    foreach ($jsonObj->result->data as $one) {
      echo "<tr>";
      for ($i=0;$i<$number_of_fields;$i++){
        echo "<td> " . $one[$i] . "</td>";
      };
      echo "</tr>";
    }
    echo "</table>";
  }

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