Отправить системное транзакционное сообщение подписчику

/v2/Api/SystemTransactionals/{ID} POST

Позволяет отправить заранее созданное транзакционное письмо одному подписчику. Транзакционное письмо идентифицируется по ID.

Особенность системных транзакционных сообщений в том, что они отправляются всем, даже жалобщикам и емейлам из локального черного списка. Их нужно использовать для отправки писем с восстановлением пароля, с информацией по заказу и для любых других писем, которые крайне важны для получателя.

Внутри ExpertSender транзакционное и системное транзакционное - это один и тот же тип писем. Более того, можно отправлять одно и то же письмо как системное транзакционное с одним контентом, так и простое транзакционное с другим.

Если подписчик, которому вы хотите отправить письмо, уже есть в вашем аккаунте, его данные обновятся. Если подписчика нет ни в одном листе, то вначале он добавится в особый транзакционный лист.

Системное транзакционное сообщение отправится подписчику, в любом случае, даже если он находится:

  1. В стоп-листах
  2. В удаленных
  3. В отписчиках
  4. В жалобщиках
  5. В локальном черном списке
  6. В глобальном черном списке

Формат данных

Параметры URL-адреса запроса:

ПараметрТипОписание
IDintegerID транзакционного сообщения. Обязательная часть адреса.

Пример URL: 

https://api.esv2.com/v2/Api/SystemTransactionals/123

Данные в запросе передаются для отправки системного транзакционного письма одному подписчику.

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

Элемент/атрибутТипОписание
ReturnGuidbooleanЕсли установлен в true, позволяет получить GUID (global unique identifier) отправляемого письма. Необязательное. По умолчанию false.
ReceivercomplexОпределяет подписчика, который получит транзакционное письмо.
SnippetscomplexНабор сниппетов, которые будут использоваться в теле/теме и других элементах письма. Необязательный.
AttachmentscomplexНабор вложений, которые содержат дополнительные данные (например, кодированные PDF файлы, отправленные с транзакционным письмом). Необязательный.

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

Элемент/атрибутТипОписание
IdintegerИдентификатор подписчика. Необязательный*.
EmailstringЕмейл подписчика. Необязательный*.
EmailMd5string MD5-хеш адреса подписчика. Необязательный*.
EmailSha256stringSHA256 хеш адрес подписчика. Необязательный.
FirstnamestringИмя подписчика. Необязательный.
LastnamestringФамилия подписчика. Необязательный.
TrackingCodestringИдентификатор источника подписчиков (например, конкретная форма на веб-странице). Необязательный.
NamestringПолное имя по шаблону "Имя Фамилия". Может использоваться, когда отдельные данные для имени и фамилии отсутствуют.
VendorstringИдентификатор/имя типа трафика, из которого пришел подписчик. Необязательный.
IpstringIP-адрес подписчика. Необязательный.
PropertiesstringДополнительные параметры. Необязательный. Дополнительную информацию см. в разделе "Элементы тега Property" https://manual.expertsender.ru/metody/podpischiki/dobavlenie-podpischika-v-list
BccstringEmail, на который отправляется скрытая копия сообщения. Необязательный.

*Для идентификации подписчика необходимо указать одно из полей Id/Email/EmailMd5. Если указан Email/EmailMd5, то подписчик с этим емейлом или хешем должен существовать в базе данных ExpertSender. Если указано несколько полей, то ID всегда будет иметь приоритет.

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

Элемент/атрибутТипОписание
NamestringИмя Сниппета*.
ValuestringЗначение Сниппета**.

* Имя сниппета связывается с тегом, который можно будет использовать в тексте сообщения, его теме и других полях сообщения.
Пример: если имя сниппета «mySnippet», то его значение будет подставлено в сообщение на место тега
*[tr_mySnippet]*.

** Сниппеты могут содержать HTML-теги (если используется секция CDATA, смотрите пример запроса) и теги персонализации (например, *[subscriber_firstname]*). Динамический контент не будет работать внутри сниппетов.

Элементы тега 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

Попытка отправки неактивного или удаленного сообщения вернет ошибку. Если указанный подписчик отписан от всех листов или находится в глобальном черном списке, тоже вернется ошибка.

Ответ

По умолчанию возвращается пустой формат ответа с кодом "201 - Created". Однако, если указан флаг ReturnGuid можно получть XML ответ с GUID отправленного транзакционного письма.

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

Элемент/атрибутТипОписание
Содержимое элемента DatastringGUID (global unique identifier) письма

Примеры

Запрос с использованием двух сниппетов, подписчик определяется по емейлу: 

POST https://api.esv2.com/v2/Api/SystemTransactionals/123 HTTP/1.1 
Accept-Encoding: gzip,deflate 
Content-Type: application/xml;charset=UTF-8 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: localapi 
Content-Length: 585 
 <ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <ApiKey>Ваш_API-ключ</ApiKey>
     <Data>
         <Receiver>
             <Email>patrick@mydomain.com</Email>
         </Receiver>
         <Snippets>
             <Snippet>
                 <Name>helloMessage</Name>
                 <Value><![CDATA[ <b>Hello Patrick!</b> ]]></Value>
             </Snippet>
             <Snippet>
                 <Name>pointsNumber</Name>
                 <Value>2076</Value>
             </Snippet>
         </Snippets>
     </Data>
 </ApiRequest>

Запрос без использования сниппетов, подписчик определяется по ID: 

POST https://api.esv2.com/v2/Api/SystemTransactionals/1593 HTTP/1.1
Accept-Encoding: gzip,deflate 
Content-Type: application/xml;charset=UTF-8 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: localapi 
Content-Length: 241 
 
 
 <ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <ApiKey>Ваш_API-ключ1</ApiKey>
    <Data>
        <Receiver>
           <Id>12345</Id>
        </Receiver>
    </Data>
 </ApiRequest>

Запрос с вложением 

POST  http://api.esv2.com/v2/Api/SystemTransactionals/2449 HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/xml;charset=UTF-8
Content-Length: 113056
Host: api.esv2.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

<ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <ApiKey>Ваш_API-ключ</ApiKey>
   <Data>
      <Receiver>
         <Email>patrick@mydomain.com</Email>
      </Receiver>
      <Attachments>
        <Attachment>
        <FileName>test.pdf</FileName>
        <MimeType>application/pdf</MimeType>
        <Content>JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFIvTGFu
ZyhwbC1QTCkgL1N0cnVjdFRyZWVSb290IDggMCBSL01hcmtJbmZvPDwvTWFya2VkIHRydWU+Pj4+
DQplbmRvYmoNCjIgMCBvYmoNCjw8L1R5cGUvUGFnZXMvQ291bnQgMS9LaWRzWyAzIDAgUl0gPj4N
CmVuZG9iag0KMyAwIG9iag0KPDwvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9SZXNvdXJjZXM8PC9G
...
ODlFOENBQTNGMTY5NzFBRTU+XSAvUHJldiA4MjU0MS9YUmVmU3RtIDgyMjcwPj4NCnN0YXJ0eHJl
Zg0KODMwNTcNCiUlRU9G</Content>
      </Attachment>
    </Attachments>
  </Data>
</ApiRequest>

В примере фрагмент длинного вложения был заменен на "...".

Запрос c использованием ReturnGuid 

POST https://api.esv2.com/v2/Api/SystemTransactionals/2449 HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/xml;charset=UTF-8
Content-Length: 317
Host: api.esv2.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

<ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <ApiKey>Ваш_API-ключ</ApiKey>
     <Data>
         <ReturnGuid>true</ReturnGuid>
         <Receiver>
             <Email>patrick@mydomain.com</Email>
         </Receiver>
    </Data>
 </ApiRequest>

Ответ "ОК" (без GUID): 

HTTP/1.1 201 Created 
Cache-Control: private 
Server: Microsoft-IIS/7.5 
X-AspNetMvc-Version: 2.0 
X-AspNet-Version: 2.0.50727 
Set-Cookie: TIMEZONE=Central European Standard Time; path=/ 
X-Powered-By: ASP.NET 
Date: Fri, 08 Jul 2011 11:34:53 GMT 
Content-Length: 0

Пример с GUID 

HTTP/1.1 201 Created
Cache-Control: private
Content-Type: text/xml; charset=utf-8
Server: Microsoft-IIS/7.5
X-AspNetMvc-Version: 5.2
X-AspNet-Version: 4.0.30319
Set-Cookie: TEMP_DATA=72940603-7e6e-4e32-8dcf-85b547297551; path=/
X-Powered-By: ASP.NET
Date: Wed, 28 Jan 2015 16:30:11 GMT
Content-Length: 181

<ApiResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Data>c3a4bda9-07be-4d48-af20-df51293ec78f</Data>
</ApiResponse>

Ошибки:

Ответ, если транзакционное сообщение деактивировано или удалено: 

HTTP/1.1 400 Bad Request 
Cache-Control: private 
Content-Type: text/xml; charset=utf-8 
Server: Microsoft-IIS/7.5 
X-AspNetMvc-Version: 2.0 
X-AspNet-Version: 2.0.50727 
Set-Cookie: TIMEZONE=Central European Standard Time; path=/ 
X-Powered-By: ASP.NET 
Date: Fri, 08 Jul 2011 11:37:19 GMT 
Content-Length: 274 
 <ApiResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <ErrorMessage>
     <Code>400</Code>
     <Message>Transactional message is inactive or was deleted.</Message>
   </ErrorMessage>
 </ApiResponse>

Ответ, если подписчик находится в глобальном черном списке: 

HTTP/1.1 400 Bad Request 
Cache-Control: private 
Content-Type: text/xml; charset=utf-8 
Server: Microsoft-IIS/7.5 
X-AspNetMvc-Version: 2.0 
X-AspNet-Version: 2.0.50727 
Set-Cookie: TIMEZONE=Central European Standard Time; path=/ 
X-Powered-By: ASP.NET 
Date: Fri, 08 Jul 2011 11:37:19 GMT 
Content-Length: 274 
 <ApiResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <ErrorMessage>
     <Code>400</Code>
     <Message>Subscriber is blacklisted.</Message>
   </ErrorMessage>
 </ApiResponse>

Ответ, если письмо не существует:

HTTP/1.1 404 Not Found
Cache-Control: private
Content-Type: text/xml; charset=utf-8
Date: Wed, 13 Mar 2019 09:56:29 GMT
Content-Length: 244
 <ApiResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <ErrorMessage>
     <Code>404</Code>
     <Message>Resource with specified ID not found.</Message>
   </ErrorMessage>
 </ApiResponse>

Ответ, если email содержит русскую букву:

HTTP/1.1 400 Bad Request
Cache-Control: private
Content-Type: text/xml; charset=utf-8
Date: Wed, 13 Mar 2019 10:04:02 GMT
Content-Length: 254
 <ApiResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <ErrorMessage>
     <Code>400</Code>
     <Message>testemail: Subscriber email is invalid.</Message>
   </ErrorMessage>
 </ApiResponse>