/v2/Api/Newsletters POST

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

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

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

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

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

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

Элемент/атрибутТипОписание
SubscriberListsarray[integer]Массив содержит ID листов, по которым будет осуществляться рассылка. Необязательный.*
SubscriberSegmentsarray[integer]Массив содержит ID сегментов, по которым будет осуществляться рассылка. Необязательный.*
SeedListsarray[integer]Массив, содержащий ID листов с тестовыми емейлами. Необязательный.*
SuppressionListsarray[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 Текстовая версия сообщения. Необязательный.*
Header integer ID шаблона заголовка. Необязательный.
Footer integer ID шаблона футера. Необязательный.
ContentFromUrl complex Используется, если контент не передается в XML, а может быть загружен из внешнего источника. Необязательный.*
GoogleAnalyticsTags complex Теги GoogleAnalytics используются для вставки в ссылки в сообщении. Если пропущены, то не используются в ссылках.
Tags array[string] Список тегов для пометки сообщения. Необязательный.
Attachments complex Набор элементов Attachments, содержащие,например, кодированые PDF файлы и др. Необязательный.**
UrlIntegrationscomplexСписок ID Url-параметров которые были созданы в настройках субаккаунта. Необязательный.
EnableClickTrackbooleanПри значении false клики в сообщениях отслеживаться не будут. По умолчанию true. Необязательный.
EnableOpenTrackbooleanПри значении false открытия сообщений отслеживаться не будут. По умолчанию true. Необязательный.

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

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

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

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

Элемент/атрибутТипОписание
UrlstringURL-адрес импортируемого файла. Поддерживаются протоколы HTTP, HTTPS, FTP, FTPS, SFTP. Например, ftp://www.domain.com/mycreative.zip.
UsernamestringUsername, использующийся для аутентификации. Необязательный.
PasswordstringPassword, используемый для аутентификации. Необязательный.
FtpAuthstringМетод аутентификации для защищенных FTP серверов

  • None - FTP сервер без аутентификации (по умолчанию)
  • ExplicitTls - Сервер с явной TLS/SSL аутентификацией
  • ExplicitSsl - Сервер только с явной SSL аутентификацией
  • ImplicitSsl - Сервер с неявной SSL аутентификацией
FtpUseActiveModebooleanПри значении «true» для FTP соединения будет использован active mode.По умолчанию «false».

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

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

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

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

Элемент/атрибутТипОписание
FileNamestringИмя файла вложения, например infosheet.pdf. Должно быть уникальным (2 файла не должны иметь одинаковые имена). Обязательный.
MimeTypestringТип файла по стандарту MIME, например "application/pdf". Если не указан, будет использован тип "application/octet-stream". Необязательный.

Тип MIME влияет на то, как различные почтовые клиенты будут обрабатывать вложения, поэтому лучше всего всегда указывать правильный тип.*
ContentstringСодержимое файла вложения. Должно быть кодировано в Base64**. Смотрите пример запроса. Обязательный.

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

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

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

Элемент/атрибутТипОписание
DeliveryDatedateTimeДата отправки сообщения. Необязательный. По умолчанию сообщение отправляется немедленно.
TimeZonestringЧасовой пояс, используемый для отправки сообщения. Необязательный. По умолчанию берется часовой пояс из настроек.
OverrideDeliveryCapbooleanЕсли установлено «true», то будут проигнорированы все ограничения отправки из настроек. Необязательный. По умолчанию — «false».
ThrottlingMethodstringМетод распределения отправки по времени. Ниже смотрите описание различных методов. Необязательное. По умолчанию «None».
ManualThrottlingTimeintВремя (в часах) для ручного распределения отправки. Обязательный, если ThrottlingMethod «Manual», и игнорируется в других случаях.
TimeOptimizationPeriodstringПериод доставки сообщения дл Оптимизации по времения (STO). Работает только если ThrotlingMethod установлен в "TimeOptimized", в противном случае игнорируется. Пример значений параметра: "24h" - 24 часа, "5d" - 5 дней.
Channelsarray[complex]Массив каналов для отправки. Необязательный. Если пропущен, то используются стандартные каналы.

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

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

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

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

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

Ответ

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

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

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

Примеры

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

Запрос (не более 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
      
    
     
   
 

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