Skip to content

Update transactional message

Allows to update any active or inactive transactional message. Any information that won’t be given in this request, won’t be updated.

Request data format

Request URL parameters:

Element/attributeTypeNotes
IDintegerTransactional message ID. Required as a part of address (not inside request body). See example below.

Example URL (HTTP method: PUT):

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

Data part of request for updating transactional message.

Data element children:

Element/attributeTypeNotes
ContentcomplexContent information that should be updated in transactional message. Optional.
SuppressionListsarray[integer]Array of SuppressionList elements containing IDs od suppression lists that will be checked during shipment. Optional.*
Channelsarray[complex]Array of Channel elements describing delivery channels. Optional. If omitted, standard (unit) channel settings will be used to deliver the transactional.**
StatusstringStatus of transactional message. Valid values: Active, Inactive. Optional. If omitted, status won’t be changed.

* Adding any lists to this element will replace previous suppression lists in this message. If SuppressionLists array will be given without any elements inside, all suppression lists will be removed from the message.
** Adding any channel to this element will replace previous channels in this message. If Channels array will be given without any elements inside, all channels will be removed from the message.

Content element children:

Element/attributeTypeNotes
FromNamestringString put into “From:” header. Optional.
FromEmailstringEmail put into “From:” header. Optional.
ReplyToNamestringString put into “Reply-To:” header. Optional.
ReplyToEmailstringEmail put into “Reply-To:” header. Optional.
SubjectstringTransactional’s subject. Optional.
HtmlstringHTML content of transactional. The data should be enclosed in CDATA section for XML transport. See examples. Optional.*
PlainstringPlain text content of transactional. Optional.*
AmpHtmlstringAMP HTML content of transactional. The data should be enclosed in CDATA section for XML transport. See examples. Optional.*
Preheaderstring Transactional preheader. Optional.
HeaderintegerID of header template to use. Optional.
FooterintegerID of footer template to use. Optional.
ContentFromUrlcomplexUsed if content is not inside XML request but has to be downloaded from external source. Optional.*
GoogleAnalyticsTagscomplexGoogle Analytics tags used to decorate links inside transactional’s content. Optional. If omitted, Google Analytics will be disabled for created transactional.
Tagsarray[string]List of tags used to mark the transactional for convenience reasons. Optional.
AttachmentscomplexCollection of “Attachment” elements, containing additional attachment data (e.g. encoded PDF files sent with the transactional). Optional.**
UrlIntegrationscomplexList of IDs of URL integrations that were created in Business unit settings. Optional.
EnableClickTrackbooleanIf set to “false”, clicks won’t be tracked. By default set to “true”. Optional. 
EnableOpenTrackbooleanIf set to “false”, opens won’t be tracked. By default set to “true”. Optional.

* You may either put content of transactional inside using Html, Plain and/or AmpHtml elements or specify that content is to be downloaded from external source (such as webpage or FTP server as zipped file with HTML and images) using ContentFromUrl element. If content was not found in either place, an error message will be returned. If there are more than one Html, Plain and/or AmpHtml files only the last file will be the content of message.If you would like to send AMP Html you should provide Html and/or Plain as a fallback version of email.

AMP Html content must contain all needed elements (see examples) and all links must be secure links (like https://)

** It is not possible to have both ContentFromUrl and Attachments elements at the same time.

Note: If you wish to send inline images within your transactional, using ContentFromUrl method is the only way to do it.

ContentFromUrl element children:

Element/attributeTypeNotes
UrlstringURL address of imported file. Supported protocols are HTTP, HTTPS, FTP, FTPS and SFTP. E.g. ftp://www.domain.com/mycreative.zip
UsernamestringUsername used for authentication. Optional.
PasswordstringPassword used for authentication. Optional.
FtpAuthstringAuthentication method for secure FTP servers. Optional. Valid values are:
None – FTP server does not support secure authentication (default)
ExplicitTls – Explicit TLS/SSL authentication
ExplicitSsl – Explicit SSL only authentication
ImplicitSsl – Implicit SSL authentication
FtpUseActiveModebooleanIf set to “true”, active mode will be used for FTP connections. Default value is “false” – passive connection mode will be used.

GoogleAnalyticsTags element children:

Element/attributeTypeNotes
CampaignstringGoogle Analytics tag “utm_campaign”. Optional.
SourcestringGoogle Analytics tag “utm_source”. Optional.
ContentstringGoogle Analytics tag “utm_content”. Optional.

Note: The remaining tag, “utm_medium” is by default specified as “Email”.

Attachment element children:

Element/attributeTypeNotes
FileNamestringAttachment filename. E.g. “infosheet.pdf”. Should be unique (no 2 attachments should have the same filename). Required.
MimeTypestringFile 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.*
ContentstringAttachment 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

UrlIntegrations element children:

Element/attributeTypeNotes
IdintId number of existing, not deleted integration. Required.

Channel element children:

Element/attributeTypeNotes
IpstringDelivery channel IP address.
PercentageintegerPortion (%) of emails that will be sent using this delivery channel.*

* The sum of percentage for all selected channels must be 100% or an error message will occur. Example configuration could be 2 channels with 30/70 ratio or 3 channels with 25/25/50 ratio. A list of available channels can be found in unit settings, in ExpertSender panel.

Response

By default, response is empty and HTTP code “204 – No Content” is returned.

Examples

Updating a transactional message

Request:

PUT https://api.esv2.com/v2/Api/TransactionalsUpdate 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>test_api_key</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>

Response:

HTTP/1.1 204 No Content 
Content-Type: text/xml; charset=utf-8 
Date: Tue, 27 Mar 2012 13:28:01 GMT 
Content-Length: 0

Updating transactional with content downloaded from external source and full options

Request:

PUT https://api.esv2.com/v2/Api/TransactionalsUpdate 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>test_api_key</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>

Adding attachment to transactional

Request

PUT https://api.esv2.com/v2/Api/TransactionalsUpdate 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>test_api_key1</ApiKey>
   <Data>
     <Content>
       <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>

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

Updating transactional message with AMP Html content

Request:

PUT https://api.esv2.com/v2/Api/TransactionalsUpdate 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>test_api_key</ApiKey>
    <Data>
        <SuppressionLists>
            <SuppressionList>77</SuppressionList>
        </SuppressionLists>
        <Content>
            <AmpHtml><![CDATA[
                <!doctype html>
                <html amp4email>
                <head>
                   <meta charset="utf-8">
                   <script async src="https://cdn.ampproject.org/v0.js"></script>
                   <style amp4email-boilerplate>body{visibility:hidden}</style>
                </head>
                <body>
                   Hello, AMP world.

                   Please use AMP markup if there is such like "amp-img" instead of "img"

                   <amp-img src="https://sites.google.com/site/expertsenderapiv2/_/rsrc/1530873497175/config/Es-                     API.png.1530873496983.png"
                       alt="Welcome"
                       width="906"
                       height="132">
                   </amp-img>
                </body>
                </html>
                ]]></AmpHtml>
         </Content>
    </Data>
</ApiRequest>
Privacy policy