/v2/Api/TransactionalsCreate POST

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


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

Создание нового транзакционного сообщения.

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

Элемент/атрибутТипОписание
ContentcomplexСодержание сообщения. Обязательный.
SuppressionListsarray[integer]Содержит ID стоп-листов, которые будут проверены перед отправкой. Необязательный.
Channelsarray[complex]Содержит каналы для отправки. Необязательный. Если не указан, то используются стандартные каналы.
StatusstringСтатус транзакционного письма. Может принимать значения: Active, Inactive. Необязательный. По умолчанию, для новых сообщений используются значение Active.

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

Элемент/атрибутТипОписание
FromNamestringИмя отправителя. Отображается в поле From. Обязательный.
FromEmailstringЕмейл отправителя. Отображается в поле From. Обязательный.
ReplyToNamestringИмя, которое отображается в поле Reply-To. Необязательный.
ReplyToEmailstringЕмейл, который отображается в поле Reply-To. Необязательный.
SubjectstringТема письма. Обязательный.
HtmlstringHtml-контент. Должен быть заключен в секцию CDATA для передачи в XML. Смотрите примеры. Необязательный.*
PlainstringТекстовый контент сообщения. Необязательный.*
HeaderintegerID шаблона заголовка. Необязательный.
FooterintegerID шаблона футера. Необязательный.
ContentFromUrlcomplexИспользуется, если содержание сообщения не передается в XML, а находится на внешнем источнике. Необязательный.*
GoogleAnalyticsTagscomplexТеги Google Analytics. Используются для вставки в ссылки в сообщении. Необязательный. Если не указаны, то не используется.
Tagsarray[string]Список тегов для сообщения. Необязательный.
AttachmentscomplexНабор элементов 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, SFTP и FTPS. Например, 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 для различных типов файлов смотрите здесь: http://ru.wikipedia.org/wiki/Список_MIME-типов

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

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

Элемент/атрибутТипОписание
IdintID номер существующего, не удаленного параметра. Обязательный.

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

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

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


Ответ

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

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

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

Примеры


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

Запрос:

POST https://api.esv2.com/v2/Api/TransactionalsCreate 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>
     <Content>
       <FromName>test</FromName>
       <FromEmail>test@test.com</FromEmail>
       <Subject>Hello!</Subject>
       <Html><![CDATA[Helloworld!<br/>${Snippet('name')}<br/>${Snippet('age')}<br/>]]></Html>
   </Content>
   <Status>Active</Status>
   </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>
</pre>


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

Запрос:

POST https://api.esv2.com/v2/Api/TransactionalsCreate 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>
     <SuppressionLists>
       <SuppressionList>77</SuppressionList>
     </SuppressionLists>
     <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</Username>
         <Password>password</Password>
     	<FtpAuth>ExplicitTls</FtpAuth>
       </ContentFromUrl>
       <GoogleAnalyticsTags>
         <Campaign>testcampaign</Campaign>
         <Source>testsource</Source>
         <Content>testcontent</Content>
       </GoogleAnalyticsTags>
       <UrlIntegrations>
         <UrlIntegration>
   		 <Id>30</Id>
   	  </UrlIntegration>
   	  <UrlIntegration>
   		  <Id>32</Id>
   	  </UrlIntegration>
       </UrlIntegrations>
       <Tags>
         <Tag>tag1</Tag>
         <Tag>tag2</Tag>
       </Tags>
       <EnableClickTrack>true</EnableClickTrack>
       <EnableOpenTrack>true</EnableOpenTrack>
     </Content>
     <Channels>
       <Channel>
         <Ip>192.168.10.22</Ip>
         <Percentage>30</Percentage>
       </Channel>
       <Channel>
         <Ip>192.168.10.3</Ip>
         <Percentage>70</Percentage>
       </Channel>
     </Channels>
     <Status>Active</Status>
   </Data>
 </ApiRequest>

Отправка транзакционного сообщения с вложениями

POST https://api.esv2.com/v2/Api/TransactionalsCreate 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

<ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <ApiKey>Ваш_API_ключ</ApiKey>
   <Data>
     <Content>
       <FromName>test</FromName>
       <FromEmail>test@test.com</FromEmail>
       <Subject>Hello!</Subject>
       <Plain>Hello friend, how are you?</Plain>
       <Attachments>
        <Attachment>
        <FileName>test.pdf</FileName>
        <MimeType>application/pdf</MimeType>  <Content>JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFIvTGFu
ZyhwbC1QTCkgL1N0cnVjdFRyZWVSb290IDggMCBSL01hcmtJbmZvPDwvTWFya2VkIHRydWU+Pj4+
DQplbmRvYmoNCjIgMCBvYmoNCjw8L1R5cGUvUGFnZXMvQ291bnQgMS9LaWRzWyAzIDAgUl0gPj4N
CmVuZG9iag0KMyAwIG9iag0KPDwvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9SZXNvdXJjZXM8PC9G
...
ODlFOENBQTNGMTY5NzFBRTU+XSAvUHJldiA4MjU0MS9YUmVmU3RtIDgyMjcwPj4NCnN0YXJ0eHJl
Zg0KODMwNTcNCiUlRU9G</Content>
      </Attachment>
    </Attachments>
     </Content>
   </Data>
 </ApiRequest>

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