Метод createCampaign

Запланировать или начать немедленно рассылку e-mail или SMS-сообщения. Одно и то же сообщение можно отправлять несколько раз, но моменты отправки не должны быть ближе, чем на час друг к другу.

Этот метод используется для отправки уже созданных сообщений. Для предварительного создания сообщений надо использовать методы createEmailMessage и createSmsMessage

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

Синтаксис и URL для вызова метода

createCampaign (int message_id [, datetime start_time, string timezone,

 bool track_read, bool track_links, 

string contacts, string contacts_url, bool track_ga, 

stringga_medium, string ga_source, string ga_campaign, string ga_content,

 string ga_term], int payment_limit, string payment_currency)

https://api.unisender.com/ru/api/createCampaign?format=json&api_key=KEY&message_id=ID&start_time=TIME&timezone=

ZONE&track_read=X&track_links=Y&contacts=LIST&payment_limit

=100&payment_currency=rub

Аргументы
api_key * Ключ доступа к API
message_id * Код сообщения, которое надо отправить. Передавать надо код, возвращённый методом createEmailMessage или createSmsMessage.
start_time Дата и время запуска рассылки в формате «ГГГГ-ММ-ДД чч:мм». Если аргумент не задан, то рассылка начинается немедленно. Используется часовой пояс, указанный в настройках личного кабинета пользователя. Для явного указания часового пояса используйте аргумент «timezone». Для дополнительной защиты от ошибок нельзя запланировать две рассылки одного и того же сообщения в пределах одного часа.
timezone Часовой пояс, в котором задано время в аргументе «start_time». Если не указан, то используется часовой пояс из настроек Личного Кабинета. Можно явно указать часовой пояс, но пока поддерживается только один вариант: «UTC».
track_read Принимаемое значение – 0 или 1 – отслеживать ли факт прочтения e-mail сообщения. По умолчанию 0 (не отслеживать). Если 1, то в e-mail будет добавлена ссылка на небольшую картинку, отслеживающую обращение. Аргумент track_read игнорируется для SMS-сообщений.
track_links Принимаемое значение – 0 или 1 – отслеживать ли переходы по ссылкам в e-mail сообщениях, по умолчанию 0 (не отслеживать). Если 1, то все внешние ссылки будут заменяться на специальные, позволяющие отследить факт перехода, а затем переправить пользователя на нужную страницу. Аргумент track_links игнорируется для SMS-сообщений.
contacts Перечисленные через запятую email-адреса (или телефоны для sms-сообщений), которыми нужно ограничиться при отправке сообщения. Если этот аргумент отсутствует, то отправка будет осуществлена по всем контактам списка, для которого составлено сообщение (возможно, с учётом сегментации по меткам). Если аргумент contacts присутствует, то во внимание будут приняты только те контакты, которые входят в список, а остальные будут проигнорированы. 

Если адресов (телефонов) слишком много для передачи в параметре contacts, вместо него можно использовать параметр contacts_url. Нельзя одновременно задавать оба параметра.
contacts_url Вместо параметра contacts, содержащего собственно email-адреса или телефоны, можно задать в данном параметре URL файла, откуда будут прочитаны адреса (телефоны). URL должен начинаться с "http://", "https://" или "ftp://". Файл должен содержать по одному контакту в строке, без запятых-разделителей; строки должны разделяться символом "\n" или "\r\n" (формат Mac - только "\r" - не поддерживается). 

Задавать одновременно параметры contacts и contacts_url нельзя.  
Файл можно удалять после того, как рассылка перейдёт в состояние 'scheduled'. Узнать статус рассылки можно с помощью метода getCampaignStatus.
track_ga Принимаемое значение – 0 или 1 – включить ли для данной рассылки интеграцию с Google Analytics/Яндекс.Метрика. Действует только явно указанные значения, параметры пользования по умолчанию не применяются. По умолчанию 0 (не включена).
payment_limit, payment_currency Параметр, позволяющие ограничить бюджет рассылки до заданной в payment_limit суммы в валюте payment_currency. Если параметр payment_limit не задан или равен 0, то он не будет учитываться. Если сумма на счету пользователя меньше, чем указанный бюджет, то это приведет к выводу ошибки. Если параметр payment_currency не передается, система будет использовать валюту, установленную в профиле пользователя. Если будет указан неподдерживаемый код валюты, будет возвращена ошибка. Допустимые коды валют: USD. Параметр может быть задан в верхнем, или нижнем регистре.
ga_medium, ga_source, ga_campaign, ga_content, ga_term Параметры интеграции с Google Analytics/Яндекс.Метрика (действуют, если track_ga=1). Действует только явно указанные значения, параметры пользования по умолчанию не применяются. См. полное описание параметров.
Возвращаемое значение
JSON-объект с полями:
campaign_id Уникальный код рассылки – целое положительное 31-битное число
status Строковый статус рассылки, один из:
  • scheduled - рассылка поставлена очередь и будет отправлена, как только наступит время.
  • waits_censor - рассылка ожидает проверки администратором.
count Количество email-адресов (или телефонов в случае SMS-сообщения), на которые будет отправлена рассылка. 
period_messages Количество сообщений, отправленных за счёт включённых в период. Для SMS-сообщений всегда равно 0. 
prepaid_messages Количество сообщений, отправленных за счёт ранее купленных. Для SMS-сообщений всегда равно 0. 
pay_sum Сумма за отправку писем. 
currency Трёхбуквенный международный код валюты, в которой посчитана сумма за отправку писем (USD). 

Если были ошибки или предупреждения, они возвращаются в полях error/warnings в соответствии с описанием. Например, ошибка может произойти в случае нехватки денег или при попытке запланировать «автоматическое» сообщение (у которого уже был задан график отправки с помощью аргументов series_day и series_time при вызове метода. Специальный код ошибки campaign_already_exists означает, что это письмо уже было запланировано к отправке в пределах часа от указанного времени и вероятно, Вы повторно пытаетесь отправить то же самое письмо. Пример ответа:

{"result":{"campaign_id":932188,"status":"scheduled","count":134}}
      

Технические ограничения

Время выполнения запроса пропорционально количеству контактов, таймаут для рассылок до 50,000 адресов составляет 30 секунд, при большем количестве увеличивается.

Ограничение в Post запросе равно 32 mb. Вы можете его увеличить используя сжатие. Подробно о сжатии запросов можно узнать перейдя по ссылке

В случае неполучения ответа по истечении таймаута рекомендуется максимум два раза попытаться повторить запрос. Если повторный запрос заканчивается сообщением об ошибке с кодом 'campaign_already_exists' – значит, одна из предыдущих попыток всё-таки сработала, хотя и с запозданием. Если же повторные попытки опять приводят к таймауту – нужно обращаться в техподдержку.

 

Примеры на PHP

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

Пример с использованием POST-запроса
// Ваш ключ доступа к API (из Личного Кабинета)
$api_key = "xxxxxxxxxxxxxxx";

// Параметры для отправки сообщения
$email_id = "361988";

// Запланируем отправку на определённое время
// (закомментируйте, чтобы отправить немедленно)
// $email_starttime = urlencode("2012-12-20 14:40");

// Параметры сбора статистики
// Если 1, собираем, если 0 - нет
$email_stats_links = "1";
$email_stats_read = "1";

// Создаём POST-запрос
$POST = array (
  'api_key' => $api_key,
  'message_id' => $email_id,
  'start_time' => $email_starttime,
  'track_read' => $email_stats_read,
  'track_links' => $email_stats_links
);

// Устанавливаем соединение
$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/createCampaign?format=json');
$result = curl_exec($ch);

echo $result;

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 "Success. Newsletter delivery status is " . $jsonObj->result->status;

  }
} else {
  // Ошибка соединения с API-сервером
  echo "API access error";
}
Пример с использованием GET-запроса
// Ваш ключ доступа к API (из Личного Кабинета)
$api_key = "xxxxxxxxxxxxxxxxx";

// Параметры для отправки сообщения
$email_id = "361988";

// Запланируем отправку на определённое время
// (закомментируйте, чтобы отправить немедленно)
$email_starttime = urlencode("2012-12-20 14:40");

// Параметры сбора статистики
// Если 1, собираем, если 0 - нет
$email_stats_links = "1";
$email_stats_read = "1";

// Создаём GET-запрос
$api_url = "https://api.unisender.com/ru/api/createCampaign?format=json".
           "&api_key=$api_key&message_id=$email_id".
           "&start_time=$email_starttime&track_read=$email_stats_read".
           "&track_links=$email_stats_links";

// Делаем запрос на 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 "Success. Newsletter delivery status is " . $jsonObj->result->status;
  }

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