Запланировать или начать немедленно рассылку e-mail или SMS-сообщения. Одно и то же сообщение можно отправлять несколько раз, но моменты отправки не должны быть ближе, чем на час друг к другу.
Этот метод используется для отправки уже созданных сообщений. Для предварительного создания сообщений надо использовать методы createEmailMessage и createSmsMessage.
Для метода существует лимит на количество запросов от одного API-ключа или IP-адреса — 100 запросов/60 секунд.
Принцип использования
| Синтаксис и 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 | Дата и время запуска рассылки в формате «ГГГГ-ММ-ДД чч:мм», которые не превышают 100 дней от текущей даты. Если аргумент не задан, то рассылка начинается немедленно. Используется часовой пояс, указанный в настройках личного кабинета пользователя. Для явного указания часового пояса используйте аргумент «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" или "rn" (формат 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 | Строковый статус рассылки, один из:
|
| count | Количество email-адресов (или телефонов в случае SMS-сообщения), на которые будет отправлена рассылка. Будет удаленно, возвращает всегда 0. |
Если были ошибки или предупреждения, они возвращаются в полях error/warnings в соответствии с описанием. Например, ошибка может произойти в случае нехватки денег. Специальный код ошибки campaign_already_exists означает, что это письмо уже было запланировано к отправке в пределах часа от указанного времени и вероятно, Вы повторно пытаетесь отправить то же самое письмо. Пример ответа:
{"result":{"campaign_id":932188,"status":"scheduled","count":0}}
|
|
Технические ограничения
Время выполнения запроса пропорционально количеству контактов, таймаут для рассылок до 50,000 адресов составляет 30 секунд, при большем количестве увеличивается.
Ограничение в Post запросе равно 32 mb. Вы можете его увеличить используя сжатие. Подробно о сжатии запросов можно узнать перейдя по ссылке
В случае неполучения ответа по истечении таймаута рекомендуется максимум два раза попытаться повторить запрос. Если повторный запрос заканчивается сообщением об ошибке с кодом 'campaign_already_exists' – значит, одна из предыдущих попыток всё-таки сработала, хотя и с запозданием. Если же повторные попытки опять приводят к таймауту – нужно обращаться в техподдержку.
