Send system transactional messages - ExpertSender Help Center

Transactionals collection allows sending previously created transactional message to a single subscriber, using HTTP POST method. Transactional message is identified by required ID parameter.

If subscriber you want to send a message to is already present on a subscriber list (subscribers have unique emails and unique phone numbers), he is updated. If subscriber is not present he is firstly created.

When sending system transactional message checking against blacklists will be skipped.

Request data format

Request URL parameters:

Element/attribute	Type	Notes
ID	integer	Transactional message ID. Required as a part of address (not GET parameter). See example below.

Example URL:

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

Data part of request for sending system transactional message to a single subscriber.

Data element children:

Element/attribute	Type	Notes
ReturnGuid	boolean	If set to true, the request will return XML with GUID (globally unique identifier) of sent transactional message. Optional, defaults to false.
Receiver	complex	Describes subscriber that will receive the transactional message.
Snippets	complex	Collection of “Snippet” elements, describing HTML snippets that should be inserted in message body/subject etc. Optional.
Attachments	complex	Collection of “Attachment” elements, containing additional attachment data (e.g. encoded PDF files sent with the transactional message). Optional.

Receiver element children:

Element/attribute	Type	Notes
Id	integer	Subscriber’s identifier. Optional.*
Email	string	Subscriber’s email. Optional.*
EmailMd5	string	MD5 hash of subscriber’s email. Optional.*
EmailSha256	string	SHA256 hash of subscriber’s email. Optional.*
Firstname	string	Subscriber’s firstname. Optional.
Lastname	string	Subscriber’s lastname. Optional.
TrackingCode	string	Identifier of source of subscriber (e.g. particular webform on a webpage). Optional.
Name	string	Full name. Can be used when separate data for firstname and lastname is not available. It will be matched against following template: “Firstname Lastname”.
Vendor	string	Identifier/name of traffic vendor the subscriber came from. Optional.
Ip	string	IP address of subscriber. Optional.
Properties	string	Collection of custom subscriber properties (Property elements). Optional. See “Property element children” section at ADD SUBSCRIBER for details
Bcc	string	Email address/-es which will receive a hidden copy of each message. Optional.**

* Note: One of Id/Email/EmailMd5/EmailSha256 fields must be specified to identify the subscriber. If Email/EmailMd5/EmailSha256 is specified, subscriber with this email, its MD5 or SHA256 hash must exist in the database. If more fields are specified, Id always takes precedence.
** Note: It is also possible to use personalization tags and multiple email addresses separated with ‘;’. Each email address provided will double the volume of this message. Dynamic content is not available for Bcc element.

Snippet element children:

Element/attribute	Type	Notes
Name	string	Snippet name.*
Value	string	Snippet value.**

* Note: Snippet name corresponds with tags that can be used in message content, subject and other message fields.
Example: If snippet’s name is mySnippet, its value will be inserted where *[tr_mySnippet]* tags have been used.
** Note: Snippets can contain HTML tags (if enclosed in CDATA section – see example requests) and personalization tags (e.g.
*[subscriber_firstname]*). Dynamic Content does NOT work inside snippets.

Attachment element children:

Element/attribute	Type	Notes
FileName	string	Attachment filename. E.g. “`infosheet.pdf`“. Should be unique (no 2 attachments should have the same filename). Required.
MimeType	string	File type according to MIME standards. E.g. “`application/pdf`“. If omitted, default MIME type will be used: “`application/octet-stream`“. Optional. MIME type can affect how email attachments are treated in different email clients, so it is advisable to always specify the correct type.*
Content	string	Attachment file content. Must be Base64 encoded.** See example requests. Required.

* Note: For list of MIME types for different files, see: http://en.wikipedia.org/wiki/Internet_media_type
** Note: Binary to Base64 encoding is available in most programming languages. For more information about Base64 encoding, see: http://en.wikipedia.org/wiki/Base64

Warning: Trying to send a system transactional message that is inactive or deleted will trigger an error.

Response

By default, response is empty and HTTP code “201 – Created” is returned. However, you can specify ReturnGuid flag in request and receive an XML response containing GUID of sent transactional message.

Response Data element:

Element/attribute	Type	Notes
(Data element content)	string	GUID (globally unique identifier) of sent transactional message.

Examples

Request with two snippets, subscriber identified by email:

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: api.esv2.com 
Content-Length: 585 

<ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <ApiKey>test_api_key1</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>

Request with no snippets, subscriber identified by 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: api.esv2.com 
Content-Length: 241 

<ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <ApiKey>test_api_key1</ApiKey>
  <Data>
    <Receiver>
      <Id>12345</Id>
    </Receiver>
  </Data>
</ApiRequest>

Request with attachment:

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>test_api_key1</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>

Note: Part of long attachment content was cut and “…” was inserted.

Request with ReturnGuid option:

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>test_api_key1</ApiKey>
     <Data>
         <ReturnGuid>true</ReturnGuid>
         <Receiver>
           <Email>patrick@mydomain.com</Email>
         </Receiver>
    </Data>
 </ApiRequest>

OK Response (no 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

OK Response (with 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>