Создание и отправка стандартного письма

/v2/Api/Newsletters POST

Позволяет создать и отправить стандартное письмо. При этом содержимое сообщения отправляется в запросе или берется из внешнего источника, например, с FTP-сервера.

Формат запроса

Создание нового стандартного письма.

Элементы тега Data:

Элемент/атрибут	Тип	Описание
Recipients	complex	Информация о получателях рассылки. Обязательный.
Content	complex	Контент. Обязательный.
DeliverySettings	complex	Настройка отправки (дата отправки, каналы, и т.д.). Необязательный. Если пропущен, то будут использоваться значения по умолчанию.

Элементы тега Recipients:

Элемент/атрибут	Тип	Описание
SubscriberLists	array[integer]	Массив содержит ID листов, по которым будет осуществляться рассылка. Необязательный.*
SubscriberSegments	array[integer]	Массив содержит ID сегментов, по которым будет осуществляться рассылка. Необязательный.*
SeedLists	array[integer]	Массив, содержащий ID листов с тестовыми емейлами. Необязательный.*
SuppressionLists	array[integer]	Массив содержит ID стоп-листов, которые будут проверены перед отправкой.

* Должен быть обязательно указан SubscriberLists и/или SubscriberSegments и/или SeedLists. Пустой список получателей вернет ошибку.

Элементы тега Content:

Элемент/атрибут	Тип	Описание
FromName	string	Имя отправителя, которое отображается в поле From. Обязательный.
FromEmail	string	Емейл отправителя, который отображается в поле From. Обязательный.
ReplyToName	string	Имя для ответа, которое отображается в поле Reply-To. Необязательный.
ReplyToEmail	string	Емей для ответа, который отображается в поле Reply-To. Необязательный.
Subject	string	Тема письма. Обязательный.
Html	string	HTML-контент. Должен быть заключен в секцию CDATA для передачи в XML. Смотрите примеры. Необязательный.*
Plain	string	Текстовая версия сообщения. Необязательный.*
AmpHtml	string	AMP HTML-контент для письма. Данные помещаются в раздел CDATA для транспорта XML. Необязательный.
Preheader	string	Предварительный заголовок письма. Необязательный.
Header	integer	ID шаблона заголовка. Необязательный.
Footer	integer	ID шаблона футера. Необязательный.
ContentFromUrl	complex	Используется, если контент не передается в XML, а может быть загружен из внешнего источника. Необязательный.*
GoogleAnalyticsTags	complex	Теги GoogleAnalytics используются для вставки в ссылки в сообщении. Если пропущены, то не используются в ссылках.
Tags	array[string]	Список тегов для пометки сообщения. Необязательный.
Attachments	complex	Набор элементов Attachments, содержащие,например, кодированые PDF файлы и др. Необязательный.**
UrlIntegrations	complex	Список ID Url-параметров которые были созданы в настройках субаккаунта. Необязательный.
EnableClickTrack	boolean	При значении false клики в сообщениях отслеживаться не будут. По умолчанию true. Необязательный.
EnableOpenTrack	boolean	При значении false открытия сообщений отслеживаться не будут. По умолчанию true. Необязательный.

* Вы можете передать контент, используя параметры HTML и/или Plain, или загрузить из внешнего источника (например, веб-страница или ftp-сервер с zip-архивом, который содержит HTML и картинки), используя параметр ContentFromUrl. Если контент не найден ни в одном месте, то вернется ошибка.

** Вы можете использовать либо ContentFromUrl, либо Attachments.

Если вы хотите отправить картинки вместе с сообщением, то использование ContentFromUrl — единственный способ сделать это.

Элементы тега ContentFromUrl:

Элемент/атрибут	Тип	Описание
Url	string	URL-адрес импортируемого файла. Поддерживаются протоколы HTTP, HTTPS, FTP, FTPS, SFTP. Например, ftp://www.domain.com/mycreative.zip.
Username	string	Username, использующийся для аутентификации. Необязательный.
Password	string	Password, используемый для аутентификации. Необязательный.
FtpAuth	string	Метод аутентификации для защищенных FTP серверов None - FTP сервер без аутентификации (по умолчанию) ExplicitTls - Сервер с явной TLS/SSL аутентификацией ExplicitSsl - Сервер только с явной SSL аутентификацией ImplicitSsl - Сервер с неявной SSL аутентификацией
FtpUseActiveMode	boolean	При значении «true» для FTP соединения будет использован active mode.По умолчанию «false».

Элементы тега GoogleAnalyticsTags:

Элемент/атрибут	Тип	Описание
Campaign	string	Тег Google Analytics «utm_campaign». Необязательный.
Source	string	Тег Google Analytics «utm_source». Необязательный.
Content	string	Тег Google Analytics «utm_content» Необязательный.

Пропущенный тег utm_medium по умолчанию передается как «Email».

Элементы тега Attachment:

Элемент/атрибут	Тип	Описание
FileName	string	Имя файла вложения, например `infosheet.pdf.` Должно быть уникальным (2 файла не должны иметь одинаковые имена). Обязательный.
MimeType	string	Тип файла по стандарту MIME, например `"application/pdf"`. Если не указан, будет использован тип `"application/octet-stream"`. Необязательный. Тип MIME влияет на то, как различные почтовые клиенты будут обрабатывать вложения, поэтому лучше всего всегда указывать правильный тип.*
Content	string	Содержимое файла вложения. Должно быть кодировано в Base64**. Смотрите пример запроса. Обязательный.

*Типы MIME для различных типов файлов смотрите здесь: Список_MIME-типов

**Кодирование в Base64 доступно для большинства языков программирования. Для дополнительной информации смотрите Base64

Элементы тега DeliverySettings:

Элемент/атрибут	Тип	Описание
DeliveryDate	dateTime	Дата отправки сообщения. Необязательный. По умолчанию сообщение отправляется немедленно.
TimeZone	string	Часовой пояс, используемый для отправки сообщения. Необязательный. По умолчанию берется часовой пояс из настроек.
OverrideDeliveryCap	boolean	Если установлено «true», то будут проигнорированы все ограничения отправки из настроек. Необязательный. По умолчанию — «false».
ThrottlingMethod	string	Метод распределения отправки по времени. Ниже смотрите описание различных методов. Необязательное. По умолчанию «None».
ManualThrottlingTime	int	Время (в часах) для ручного распределения отправки. Обязательный, если ThrottlingMethod «Manual», и игнорируется в других случаях.
TimeOptimizationPeriod	string	Период доставки сообщения дл Оптимизации по времения (STO). Работает только если ThrotlingMethod установлен в "TimeOptimized", в противном случае игнорируется. Пример значений параметра: "24h" - 24 часа, "5d" - 5 дней.
Channels	array[complex]	Массив каналов для отправки. Необязательный. Если пропущен, то используются стандартные каналы.

Методы распределения отправки ThrottlingMethod:

Name	Behavior
None	Отправка не распределяется. Сообщения отправляются так быстро, как только возможно. Это метод по умолчанию, но он не рекомендуется для отправки больших объемов.
Auto	Автоматическое распределение. Время отправки рассчитывается автоматически исходя из настроек и количества подписчиков.
Manual	Ручное распределение. Время отправки указывается в часах.
TimeOptimized	Sending Time Optimization (STO) - письмо будет отправлено каждому подписчику в самое подходящее время, вычисленное за предыдущие 24 часа\7 дней.
TimeTravel	Время отправки будет вычисленно в зависимости от временной зоны подписичка.

Элементы тега Channel:

Элемент/атрибут	Тип	Описание
Ip	string	IP-адрес канала для отправки.
Percentage	integer	Процент емейл-адресов, который будет отправлен через этот канал.*

* Сумма процентов для всех выбранных каналов должна быть 100%, иначе вернется сообщение об ошибке. Например, два канала 30/70 или 3 канала 25/25/50. Список доступных каналов можно найти в настройках в панели ExpertSender.

Ответ

Метод возвращает ID созданного письма.

Элементы тега Data в ответе:

Элемент/атрибут	Тип	Описание
(Data element content)	int	ID созданного письма.

Примеры

Отправить простое сообщение

Запрос (не более 2Мб):

POST https://api.esv2.com/v2/Api/Newsletters HTTP/1.1 
Accept-Encoding: gzip,deflate 
Content-Type: text/xml;charset=UTF-8 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com 
Content-Length: 457 
 
 
 <ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <ApiKey>Ваш_API_ключ</ApiKey>
   <Data>
     <Recipients>
       <SubscriberLists>
         <SubscriberList>77</SubscriberList>
       </SubscriberLists>
     </Recipients>
     <Content>
       <FromEmail>test@test.com</FromEmail>
       <Subject>Привет!</Subject>
       <Plain>Привет, друг! Как ты?</Plain>
     </Content>
   </Data>
 </ApiRequest>

Ответ:

HTTP/1.1 201 Created 
Cache-Control: private 
Content-Type: text/xml; charset=utf-8 
Server: Microsoft-IIS/7.5 
X-AspNetMvc-Version: 3.0 
X-AspNet-Version: 4.0.30319 
X-Powered-By: ASP.NET 
Date: Tue, 27 Mar 2012 13:28:01 GMT 
Content-Length: 149 
 
 
 <ApiResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <Data>1498</Data>
 </ApiResponse>

Отправить сообщение с контентом, загруженным из внешнего источника и полными опциями

Запрос (не более 2Мб):

POST https://api.esv2.com/v2/Api/Newsletters HTTP/1.1 
Accept-Encoding: gzip,deflate 
Content-Type: text/xml;charset=UTF-8 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com 
Content-Length: 1727 

 <ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <ApiKey>Ваш_API_ключ</ApiKey>
   <Data>
     <Recipients>
       <SubscriberLists>
         <SubscriberList>77</SubscriberList>
       </SubscriberLists>
       <SubscriberSegments>
         <SubscriberSegment>1</SubscriberSegment>
         <SubscriberSegment>3</SubscriberSegment>
       </SubscriberSegments>
       <SeedLists>
         <SeedList>1</SeedList>
       </SeedLists>
       <SuppressionLists>
         <SuppressionList>1</SuppressionList>
       </SuppressionLists>
     </Recipients>
     <Content>
       <FromName>test</FromName>
       <FromEmail>test@test.com</FromEmail>
       <ReplyToName>test2</ReplyToName>
       <ReplyToEmail>test2@test.pl</ReplyToEmail>
       <Subject>Hello!</Subject>
       <ContentFromUrl>
         <Url>ftp://ftp.domain.com.creative.zip</Url>
         <Username>Имя пользователя</Username>
         <Password>Пароль</Password>
       </ContentFromUrl>
       <GoogleAnalyticsTags>
         <Campaign>метка UTM_campaign</Campaign>
         <Source>метка UTM_source</Source>
         <Content>метка UTM_content</Content>
       </GoogleAnalyticsTags>
       <Tags>
         <Tag>tag1</Tag>
         <Tag>tag2</Tag>
       </Tags>
     </Content>
     <DeliverySettings>
       <DeliveryDate>2012-03-23T12:00:00</DeliveryDate>
       <TimeZone>UTC</TimeZone>
       <OverrideDeliveryCap>true</OverrideDeliveryCap>
       <ThrottlingMethod>Manual</ThrottlingMethod>
       <ManualThrottlingTime>10</ManualThrottlingTime>
       <Channels>
         <Channel>
           <Ip>192.168.10.22</Ip>
           <Percentage>70</Percentage>
         </Channel>
         <Channel>
           <Ip>192.168.10.3</Ip>
           <Percentage>30</Percentage>
         </Channel>
       </Channels>
     </DeliverySettings>
   </Data>
 </ApiRequest>

Отправить сообщение с вложением

POST https://api.esv2.com/v2/Api/Newsletters HTTP/1.1 
Accept-Encoding: gzip,deflate 
Content-Type: text/xml;charset=UTF-8 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com 
Content-Length: 32566


   Ваш_API_ключ
   
     
       
         117
       
     
     
       test@test.com
       Hello!
       Hello friend, how are you?
  
        
        test.pdf
        application/pdf  JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFIvTGFu
ZyhwbC1QTCkgL1N0cnVjdFRyZWVSb290IDggMCBSL01hcmtJbmZvPDwvTWFya2VkIHRydWU+Pj4+
DQplbmRvYmoNCjIgMCBvYmoNCjw8L1R5cGUvUGFnZXMvQ291bnQgMS9LaWRzWyAzIDAgUl0gPj4N
CmVuZG9iag0KMyAwIG9iag0KPDwvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9SZXNvdXJjZXM8PC9G
...
ODlFOENBQTNGMTY5NzFBRTU+XSAvUHJldiA4MjU0MS9YUmVmU3RtIDgyMjcwPj4NCnN0YXJ0eHJl
Zg0KODMwNTcNCiUlRU9G

Часть содержания длинного вложения была заменена на "...".

Методы API - меню