{"id":3591,"date":"2023-08-29T20:04:05","date_gmt":"2023-08-29T19:04:05","guid":{"rendered":"https:\/\/help.expertsender.com\/?post_type=es&p=3591"},"modified":"2024-03-19T13:21:55","modified_gmt":"2024-03-19T12:21:55","slug":"send-system-transactional-messages","status":"publish","type":"es","link":"https:\/\/help.expertsender.com\/pl\/emp\/api\/methods\/email-messages\/send-system-transactional-messages\/","title":{"rendered":"Send system transactional messages"},"content":{"rendered":"\n

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

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.<\/p>\n\n\n\n

When sending system transactional message checking against blacklists will be skipped.<\/p>\n\n\n\n

<\/a><\/a>Request data format<\/strong><\/h3>\n\n\n\n

Request URL parameters:<\/p>\n\n\n\n

Element\/attribute<\/th>Type<\/th>Notes<\/th><\/tr><\/thead>
ID<\/td>integer<\/td>Transactional message ID. Required as a part of address (not GET parameter). See example below.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

Example URL:<\/p>\n\n\n\n

<\/path><\/path><\/svg><\/span>
https:\/\/api.esv2.com\/v2\/Api\/SystemTransactionals\/123<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
Data part of request for sending system transactional message to a single subscriber.<\/p>\n\n\n\n
Data element children:<\/p>\n\n\n\n
Element\/attribute<\/th>Type<\/th>Notes<\/th><\/tr><\/thead>
ReturnGuid<\/td>boolean<\/td>If set to true, the request will return XML with GUID (globally unique identifier<\/a>) of sent transactional message. Optional, defaults to false.<\/td><\/tr>
Receiver<\/td>complex<\/td>Describes subscriber that will receive the transactional message.<\/td><\/tr>
Snippets<\/td>complex<\/td>Collection of “Snippet” elements, describing HTML snippets that should be inserted in message body\/subject etc. Optional.<\/td><\/tr>
Attachments<\/td>complex<\/td>Collection of “Attachment” elements, containing additional attachment data (e.g. encoded PDF files sent with the transactional message). Optional. <\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Receiver element children:<\/p>\n\n\n\n
Element\/attribute<\/th>Type<\/th>Notes<\/th><\/tr><\/thead>
Id<\/td>integer<\/td>Subscriber’s identifier. Optional.*<\/td><\/tr>
Email<\/td>string<\/td>Subscriber’s email. Optional.*<\/td><\/tr>
EmailMd5<\/td>string<\/td>MD5 hash of subscriber’s email. Optional.*<\/td><\/tr>
EmailSha256<\/td>string<\/td>SHA256 hash of subscriber’s email. Optional.*<\/td><\/tr>
Firstname<\/td>string<\/td>Subscriber\u2019s firstname. Optional.<\/td><\/tr>
Lastname<\/td>string<\/td>Subscriber\u2019s lastname. Optional.<\/td><\/tr>
TrackingCode<\/td>string<\/td>Identifier of source of subscriber (e.g. particular webform on a webpage). Optional.<\/td><\/tr>
Name<\/td>string<\/td>Full name. Can be used when separate data for firstname and lastname is not available. It will be matched against following template: \u201cFirstname Lastname\u201d.<\/td><\/tr>
Vendor<\/td>string<\/td>Identifier\/name of traffic vendor the subscriber came from. Optional.<\/td><\/tr>
Ip<\/td>string<\/td>IP address of subscriber. Optional.<\/td><\/tr>
Properties<\/td>string<\/td>Collection of custom subscriber properties (Property elements). Optional. See “Property element children” section at ADD SUBSCRIBER<\/a> for details<\/td><\/tr>
Bcc<\/td>string<\/td>Email address\/-es which will receive a hidden copy of each message. Optional.**<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
* 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.<\/p>\n\n\n\n
Snippet element children:<\/p>\n\n\n\n
Element\/attribute<\/th>Type<\/th>Notes<\/th><\/tr><\/thead>
Name<\/td>string<\/td>Snippet name.*<\/td><\/tr>
Value<\/td>string<\/td>Snippet value.**<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
* Note: Snippet name corresponds with tags that can be used in message content, subject and other message fields.
Example: If snippet\u2019s 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 \u2013 see example requests) and personalization tags (e.g.
*[subscriber_firstname]*). Dynamic Content does NOT work inside snippets.<\/p>\n\n\n\n
Attachment element children:<\/p>\n\n\n\n
Element\/attribute<\/th>Type<\/th>Notes<\/th><\/tr><\/thead>
FileName<\/td>string<\/td>Attachment filename. E.g. “infosheet.pdf<\/code>“. Should be unique (no 2 attachments should have the same filename). Required.<\/td><\/tr>
MimeType<\/td>string<\/td>File type according to MIME standards. E.g. “application\/pdf<\/code>“. If omitted, default MIME type will be used: “application\/octet-stream<\/code>“. Optional.

MIME type can affect how email attachments are treated in different email clients, so it is advisable to always specify the correct type.*<\/td><\/tr>
Content<\/td>string<\/td>Attachment file content. Must be Base64 encoded.** See example requests. Required.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
* Note: For list of MIME types for different files, see: http:\/\/en.wikipedia.org\/wiki\/Internet_media_type<\/a>
** Note: Binary to Base64 encoding is available in most programming languages. For more information about Base64 encoding, see: http:\/\/en.wikipedia.org\/wiki\/Base64<\/p>\n\n\n\n
Warning: Trying to send a system transactional message that is inactive or deleted will trigger an error.<\/p>\n\n\n\n
<\/a><\/a>Response<\/strong><\/h3>\n\n\n\n
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.<\/p>\n\n\n\n
Response Data element:<\/p>\n\n\n\n
Element\/attribute<\/th>Type<\/th>Notes<\/th><\/tr><\/thead>
(Data element content)<\/td>string<\/td>GUID (globally unique identifier<\/a>) of sent transactional message.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Examples<\/strong><\/h3>\n\n\n\n
Request with two snippets, subscriber identified by email:<\/p>\n\n\n\n
<\/path><\/path><\/svg><\/span>
POST https:\/\/api.esv2.com\/v2\/Api\/SystemTransactionals\/123 HTTP\/1.1 <\/span><\/span>\nAccept-Encoding: gzip,deflate <\/span><\/span>\nContent-Type: application\/xml;charset=UTF-8 <\/span><\/span>\nUser-Agent: Jakarta Commons-HttpClient\/3.1 <\/span><\/span>\nHost: api.esv2.com <\/span><\/span>\nContent-Length: 585 <\/span><\/span>\n<\/span>\n<<\/span>ApiRequest<\/span> <\/span>xmlns<\/span>:<\/span>xsi<\/span>=<\/span>"<\/span>http:\/\/www.w3.org\/2001\/XMLSchema-instance<\/span>"<\/span> <\/span>xmlns<\/span>:<\/span>xs<\/span>=<\/span>"<\/span>http:\/\/www.w3.org\/2001\/XMLSchema<\/span>"<\/span>><\/span><\/span>\n  <\/span><<\/span>ApiKey<\/span>><\/span>test_api_key1<\/span><\/<\/span>ApiKey<\/span>><\/span><\/span>\n  <\/span><<\/span>Data<\/span>><\/span><\/span>\n    <\/span><<\/span>Receiver<\/span>><\/span><\/span>\n      <\/span><<\/span>Email<\/span>><\/span>patrick@mydomain.com<\/span><\/<\/span>Email<\/span>><\/span><\/span>\n    <\/span><\/<\/span>Receiver<\/span>><\/span><\/span>\n    <\/span><<\/span>Snippets<\/span>><\/span><\/span>\n      <\/span><<\/span>Snippet<\/span>><\/span><\/span>\n        <\/span><<\/span>Name<\/span>><\/span>helloMessage<\/span><\/<\/span>Name<\/span>><\/span><\/span>\n        <\/span><<\/span>Value<\/span>><\/span><![CDATA[<\/span> <b>Hello Patrick!<-b> <\/span>]]><\/span><\/<\/span>Value<\/span>><\/span><\/span>\n      <\/span><\/<\/span>Snippet<\/span>><\/span><\/span>\n      <\/span><<\/span>Snippet<\/span>><\/span><\/span>\n        <\/span><<\/span>Name<\/span>><\/span>pointsNumber<\/span><\/<\/span>Name<\/span>><\/span><\/span>\n        <\/span><<\/span>Value<\/span>><\/span>2076<\/span><\/<\/span>Value<\/span>><\/span><\/span>\n      <\/span><\/<\/span>Snippet<\/span>><\/span><\/span>\n    <\/span><\/<\/span>Snippets<\/span>><\/span><\/span>\n  <\/span><\/<\/span>Data<\/span>><\/span><\/span>\n<\/<\/span>ApiRequest<\/span>><\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
Request with no snippets, subscriber identified by ID:<\/p>\n\n\n\n
<\/path><\/path><\/svg><\/span>
POST https:\/\/api.esv2.com\/v2\/Api\/SystemTransactionals\/1593 HTTP\/1.1 <\/span><\/span>\nAccept-Encoding: gzip,deflate <\/span><\/span>\nContent-Type: application\/xml;charset=UTF-8 <\/span><\/span>\nUser-Agent: Jakarta Commons-HttpClient\/3.1 <\/span><\/span>\nHost: api.esv2.com <\/span><\/span>\nContent-Length: 241 <\/span><\/span>\n<\/span>\n<<\/span>ApiRequest<\/span> <\/span>xmlns<\/span>:<\/span>xsi<\/span>=<\/span>"<\/span>http:\/\/www.w3.org\/2001\/XMLSchema-instance<\/span>"<\/span> <\/span>xmlns<\/span>:<\/span>xs<\/span>=<\/span>"<\/span>http:\/\/www.w3.org\/2001\/XMLSchema<\/span>"<\/span>><\/span><\/span>\n  <\/span><<\/span>ApiKey<\/span>><\/span>test_api_key1<\/span><\/<\/span>ApiKey<\/span>><\/span><\/span>\n  <\/span><<\/span>Data<\/span>><\/span><\/span>\n    <\/span><<\/span>Receiver<\/span>><\/span><\/span>\n      <\/span><<\/span>Id<\/span>><\/span>12345<\/span><\/<\/span>Id<\/span>><\/span><\/span>\n    <\/span><\/<\/span>Receiver<\/span>><\/span><\/span>\n  <\/span><\/<\/span>Data<\/span>><\/span><\/span>\n<\/<\/span>ApiRequest<\/span>><\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
Request with attachment:<\/p>\n\n\n\n
<\/path><\/path><\/svg><\/span>
POST http:\/\/api.esv2.com\/v2\/Api\/SystemTransactionals\/2449 HTTP\/1.1<\/span><\/span>\nAccept-Encoding: gzip,deflate<\/span><\/span>\nContent-Type: application\/xml;charset=UTF-8<\/span><\/span>\nContent-Length: 113056<\/span><\/span>\nHost: api.esv2.com<\/span><\/span>\nConnection: Keep-Alive<\/span><\/span>\nUser-Agent: Apache-HttpClient\/4.1.1 (java 1.5)<\/span><\/span>\n<\/span>\n<<\/span>ApiRequest<\/span> <\/span>xmlns<\/span>:<\/span>xsi<\/span>=<\/span>"<\/span>http:\/\/www.w3.org\/2001\/XMLSchema-instance<\/span>"<\/span> <\/span>xmlns<\/span>:<\/span>xs<\/span>=<\/span>"<\/span>http:\/\/www.w3.org\/2001\/XMLSchema<\/span>"<\/span>><\/span><\/span>\n   <\/span><<\/span>ApiKey<\/span>><\/span>test_api_key1<\/span><\/<\/span>ApiKey<\/span>><\/span><\/span>\n   <\/span><<\/span>Data<\/span>><\/span><\/span>\n      <\/span><<\/span>Receiver<\/span>><\/span><\/span>\n         <\/span><<\/span>Email<\/span>><\/span>patrick@mydomain.com<\/span><\/<\/span>Email<\/span>><\/span><\/span>\n      <\/span><\/<\/span>Receiver<\/span>><\/span><\/span>\n      <\/span><<\/span>Attachments<\/span>><\/span><\/span>\n        <\/span><<\/span>Attachment<\/span>><\/span><\/span>\n          <\/span><<\/span>FileName<\/span>><\/span>test.pdf<\/span><\/<\/span>FileName<\/span>><\/span><\/span>\n          <\/span><<\/span>MimeType<\/span>><\/span>application\/pdf<\/span><\/<\/span>MimeType<\/span>><\/span><\/span>\n<<\/span>Content<\/span>><\/span>JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFIvTGFu<\/span><\/span>\nZyhwbC1QTCkgL1N0cnVjdFRyZWVSb290IDggMCBSL01hcmtJbmZvPDwvTWFya2VkIHRydWU+Pj4+<\/span><\/span>\nDQplbmRvYmoNCjIgMCBvYmoNCjw8L1R5cGUvUGFnZXMvQ291bnQgMS9LaWRzWyAzIDAgUl0gPj4N<\/span><\/span>\nCmVuZG9iag0KMyAwIG9iag0KPDwvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9SZXNvdXJjZXM8PC9G<\/span><\/span>\n...<\/span><\/span>\nODlFOENBQTNGMTY5NzFBRTU+XSAvUHJldiA4MjU0MS9YUmVmU3RtIDgyMjcwPj4NCnN0YXJ0eHJl<\/span><\/span>\nZg0KODMwNTcNCiUlRU9G<\/span><\/<\/span>Content<\/span>><\/span><\/span>\n      <\/span><\/<\/span>Attachment<\/span>><\/span><\/span>\n    <\/span><\/<\/span>Attachments<\/span>><\/span><\/span>\n  <\/span><\/<\/span>Data<\/span>><\/span><\/span>\n<\/<\/span>ApiRequest<\/span>><\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
Note: Part of long attachment content was cut and “…” was inserted.<\/p>\n\n\n\n
Request with ReturnGuid option:<\/p>\n\n\n\n
<\/path><\/path><\/svg><\/span>
POST https:\/\/api.esv2.com\/v2\/Api\/SystemTransactionals\/2449 HTTP\/1.1<\/span><\/span>\nAccept-Encoding: gzip,deflate<\/span><\/span>\nContent-Type: application\/xml;charset=UTF-8<\/span><\/span>\nContent-Length: 317<\/span><\/span>\nHost: api.esv2.com<\/span><\/span>\nConnection: Keep-Alive<\/span><\/span>\nUser-Agent: Apache-HttpClient\/4.1.1 (java 1.5)<\/span><\/span>\n<\/span>\n<<\/span>ApiRequest<\/span> <\/span>xmlns<\/span>:<\/span>xsi<\/span>=<\/span>"<\/span>http:\/\/www.w3.org\/2001\/XMLSchema-instance<\/span>"<\/span> <\/span>xmlns<\/span>:<\/span>xs<\/span>=<\/span>"<\/span>http:\/\/www.w3.org\/2001\/XMLSchema<\/span>"<\/span>><\/span><\/span>\n     <\/span><<\/span>ApiKey<\/span>><\/span>test_api_key1<\/span><\/<\/span>ApiKey<\/span>><\/span><\/span>\n     <\/span><<\/span>Data<\/span>><\/span><\/span>\n         <\/span><<\/span>ReturnGuid<\/span>><\/span>true<\/span><\/<\/span>ReturnGuid<\/span>><\/span><\/span>\n         <\/span><<\/span>Receiver<\/span>><\/span><\/span>\n           <\/span><<\/span>Email<\/span>><\/span>patrick@mydomain.com<\/span><\/<\/span>Email<\/span>><\/span><\/span>\n         <\/span><\/<\/span>Receiver<\/span>><\/span><\/span>\n    <\/span><\/<\/span>Data<\/span>><\/span><\/span>\n <\/span><\/<\/span>ApiRequest<\/span>><\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
OK Response (no GUID):<\/p>\n\n\n\n
<\/path><\/path><\/svg><\/span>
HTTP\/1.1 201 Created <\/span><\/span>\nCache-Control: private <\/span><\/span>\nServer: Microsoft-IIS\/7.5 <\/span><\/span>\nX-AspNetMvc-Version: 2.0 <\/span><\/span>\nX-AspNet-Version: 2.0.50727 <\/span><\/span>\nSet-Cookie: TIMEZONE=Central European Standard Time; path=\/ <\/span><\/span>\nX-Powered-By: ASP.NET <\/span><\/span>\nDate: Fri, 08 Jul 2011 11:34:53 GMT <\/span><\/span>\nContent-Length: 0<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
OK Response (with GUID):<\/p>\n\n\n\n
<\/path><\/path><\/svg><\/span>
HTTP\/1.1 201 Created<\/span><\/span>\nCache-Control: private<\/span><\/span>\nContent-Type: text\/xml; charset=utf-8<\/span><\/span>\nServer: Microsoft-IIS\/7.5<\/span><\/span>\nX-AspNetMvc-Version: 5.2<\/span><\/span>\nX-AspNet-Version: 4.0.30319<\/span><\/span>\nSet-Cookie: TEMP_DATA=72940603-7e6e-4e32-8dcf-85b547297551; path=\/<\/span><\/span>\nX-Powered-By: ASP.NET<\/span><\/span>\nDate: Wed, 28 Jan 2015 16:30:11 GMT<\/span><\/span>\nContent-Length: 181<\/span><\/span>\n<\/span>\n<<\/span>ApiResponse<\/span> <\/span>xmlns<\/span>:<\/span>xsd<\/span>=<\/span>"<\/span>http:\/\/www.w3.org\/2001\/XMLSchema<\/span>"<\/span> <\/span>xmlns<\/span>:<\/span>xsi<\/span>=<\/span>"<\/span>http:\/\/www.w3.org\/2001\/XMLSchema-instance<\/span>"<\/span>><\/span><\/span>\n  <\/span><<\/span>Data<\/span>><\/span>c3a4bda9-07be-4d48-af20-df51293ec78f<\/span><\/<\/span>Data<\/span>><\/span><\/span>\n<\/<\/span>ApiResponse<\/span>><\/span><\/span><\/code><\/pre><\/div>\n","protected":false},"author":5,"featured_media":0,"parent":3559,"menu_order":327,"template":"","format":"standard","emp-category":[],"class_list":["post-3591","es","type-es","status-publish","format-standard","hentry"],"acf":[],"_links":{"self":[{"href":"https:\/\/help.expertsender.com\/pl\/wp-json\/wp\/v2\/es\/3591","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/help.expertsender.com\/pl\/wp-json\/wp\/v2\/es"}],"about":[{"href":"https:\/\/help.expertsender.com\/pl\/wp-json\/wp\/v2\/types\/es"}],"author":[{"embeddable":true,"href":"https:\/\/help.expertsender.com\/pl\/wp-json\/wp\/v2\/users\/5"}],"version-history":[{"count":2,"href":"https:\/\/help.expertsender.com\/pl\/wp-json\/wp\/v2\/es\/3591\/revisions"}],"predecessor-version":[{"id":8786,"href":"https:\/\/help.expertsender.com\/pl\/wp-json\/wp\/v2\/es\/3591\/revisions\/8786"}],"up":[{"embeddable":true,"href":"https:\/\/help.expertsender.com\/pl\/wp-json\/wp\/v2\/es\/3559"}],"wp:attachment":[{"href":"https:\/\/help.expertsender.com\/pl\/wp-json\/wp\/v2\/media?parent=3591"}],"wp:term":[{"taxonomy":"emp-category","embeddable":true,"href":"https:\/\/help.expertsender.com\/pl\/wp-json\/wp\/v2\/emp-category?post=3591"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}