{"id":3588,"date":"2023-08-29T19:48:19","date_gmt":"2023-08-29T18:48:19","guid":{"rendered":"https:\/\/help.expertsender.com\/?post_type=es&p=3588"},"modified":"2024-03-19T13:21:55","modified_gmt":"2024-03-19T12:21:55","slug":"send-transactional-messages","status":"publish","type":"es","link":"https:\/\/help.expertsender.com\/pl\/emp\/api\/methods\/email-messages\/send-transactional-messages\/","title":{"rendered":"Send 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

<\/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\/Transactionals\/123<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
Data part of request for sending 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>
ListId<\/td>integer <\/td>Identifier of subscriber’s list. May be used to specify list context used to send the transactional message. This can be useful if subscriber is present on multiple lists. If omitted, first found list will be used as a context. Optional.<\/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 fields must be specified to identify the subscriber. If Email\/EmailMd5 is specified, subscriber with this email or its MD5 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<\/a><\/p>\n\n\n\n
Warning: Trying to send a transactional message that is inactive or deleted will trigger an error. An error is also returned if specified subscriber cannot be found in the database or has unsubscribed from all lists.<\/p>\n\n\n\n
<\/a><\/a>Re<\/strong>sponse<\/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\/Transactionals\/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\/Transactionals\/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\/Transactionals\/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>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\/Transactionals\/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\n\n\n
Error Response (bad subscriber):<\/p>\n\n\n\n
<\/path><\/path><\/svg><\/span>
HTTP\/1.1 400 Bad Request <\/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: 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:37:19 GMT <\/span><\/span>\nContent-Length: 274 <\/span><\/span>\n<\/span>\n<<\/span>ApiResponse<\/span> <\/span>xmlns<\/span>:<\/span>xsi<\/span>=<\/span>"<\/span>http:\/\/www.w3.org\/2001\/XMLSchema-instance<\/span>"<\/span> <\/span>xmlns<\/span>:<\/span>xsd<\/span>=<\/span>"<\/span>http:\/\/www.w3.org\/2001\/XMLSchema<\/span>"<\/span>><\/span><\/span>\n  <\/span><<\/span>ErrorMessage<\/span>><\/span><\/span>\n    <\/span><<\/span>Code<\/span>><\/span>400<\/span><\/<\/span>Code<\/span>><\/span><\/span>\n    <\/span><<\/span>Message<\/span>><\/span>Subscriber does not exist in the database or has unsubscribed.<\/span><\/<\/span>Message<\/span>><\/span><\/span>\n  <\/span><\/<\/span>ErrorMessage<\/span>><\/span><\/span>\n<\/<\/span>ApiResponse<\/span>><\/span><\/span><\/code><\/pre><\/div>\n","protected":false},"author":5,"featured_media":0,"parent":3559,"menu_order":328,"template":"","format":"standard","emp-category":[],"class_list":["post-3588","es","type-es","status-publish","format-standard","hentry"],"acf":[],"_links":{"self":[{"href":"https:\/\/help.expertsender.com\/pl\/wp-json\/wp\/v2\/es\/3588","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\/3588\/revisions"}],"predecessor-version":[{"id":8785,"href":"https:\/\/help.expertsender.com\/pl\/wp-json\/wp\/v2\/es\/3588\/revisions\/8785"}],"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=3588"}],"wp:term":[{"taxonomy":"emp-category","embeddable":true,"href":"https:\/\/help.expertsender.com\/pl\/wp-json\/wp\/v2\/emp-category?post=3588"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}