Skip to content

Get messages list

Messages collection contains a list of all sent messages. Multiple messages matching specified criteria can be retrieved. Specifying single message ID can be used to retrieve detailed information about a specific message.

Request data format

Get multiple messages

Request URL parameters:

Element/attributeTypeNotes
apiKeystringYour API key, required for authentication. Required.
tagstringTag. Optional. If specified, only messages tagged with its value will be returned.
startDatedateStart date. Optional. If specified, messages sent before this date will not be returned. May be used together with endDate to specify a period of time. YYYY-MM-DD format.
endDatedateSee startDate.
typestringOnly return specific message types. Optional. Valid values:
Newsletter
Autoresponder
Trigger
Transactional
Confirmation
Recurring
Test
FreeEmailPreview
PaidEmailPreview
WorkflowMessage

Examples:

https://api.esv2.com/v2/Api/Messages?apiKey=YOUR_API_KEY_HERE 
https://api.esv2.com/v2/Api/Messages?apiKey=YOUR_API_KEY_HERE&tag=sports 
https://api.esv2.com/v2/Api/Messages?apiKey=YOUR_API_KEY_HERE&tag=sports&startDate=2010-05-20&endDate=2010-05-22
https://api.esv2.com/v2/Api/Messages?apiKey=YOUR_API_KEY_HERE&tag=sports&startDate=2010-05-20&endDate=2010-05-22&type=Recurring

Get message by Message ID

Request URL parameters:

Element/attributeTypeNotes
apiKeystringYour API key, required for authentication. Required.
IDintMessage ID. Required as a part of address (not GET parameter). See example below.

Examples:

https://api.esv2.com/v2/Api/Messages/123?apiKey=YOUR_API_KEY_HERE

Response

Get multiple messages

Response Data element:

Element/attributeTypeNotes
UserUnknownsarray[complex]Array of Message elements.

Message element children:

Element/attributeTypeNotes
IdintMessage identifier.
FromNamestringName used in “From:” header.
FromEmailstringEmail used in “From:” header. 
SubjectstringMessage subject.
TypestringMessage type (Newsletter, Autoresponder, Trigger etc).
SentDatedatetimeOptional. Date when the message was sent. For messages that are sent many times (e.g. Autoresponders) it is the first date matching specified date range.
TagsstringOptional. List of comma-separated message tags.

Get message by Message ID

Response Data element:

Element/attributeTypeNotes
IdintMessage identifier.
FromEmailstringEmail used in “From:” header.
FromNamestringName used in “From:” header. 
SubjectstringMessage subject.
TypestringMessage type (Newsletter, Autoresponder, Trigger etc).
SentDatedatetimeOptional. Date when the message was sent. For messages that are sent many times (e.g. Autoresponders) it is the first date matching specified date range.
TagsstringOptional. List of comma-separated message tags.
ThrottlingMethodstringOptional. Throttling method.
ThrottlingintOptional. Throttling period (hrs.). Filled only if ThrottlingMethod is “Manual”.
GoogleAnalyticsTagsarray[complex]Optional. Array of GoogleAnalyticsTag elements (if message uses Google Analytics).
YandexListIdcomplexOptional. Information about Yandex List ID (if message uses Yandex integration). 
ChannelsstringOptional. List of comma-separated channels (if message was sent using channels other than default).
Listsarray[complex]Optional. Array of List elements (target subscriber lists).
Segmentsarray[complex]Optional. Array of Segment elements (target subscriber segments).
ExcludedListsarray[complex]Optional. Array of excluded List elements (target subscriber lists).
ExcludedSegmentsarray[complex]Optional. Array of excluded Segment elements (target subscriber segments).
StatusstringOptional. Available only for newsletters.

GoogleAnalyticsTag element children:

Element/attributeTypeNotes
NamestringTag name, e.g. “utm_source”.
ValuestringTag value.

YandexListId element children:

Element/attributeTypeNotes
IdentifierstringYandex identifier.
CommentstringComment.

List element children:

Element/attributeTypeNotes
IdintList identifier.
NamestringList name.

ExcludedLists element children:

Element/attributeTypeNotes
IdintList identifier.
NamestringList name.

ExcludedSegments element children:

Element/attributeTypeNotes
IdintSegment identifier.
NamestringSegment name.

Segment element children:

Element/attributeTypeNotes
IdintSegment identifier.
NamestringSegment name.

List of all possible ThrottlingMethod values:

ThrottlingMethod valuesNotes
NoneMessage is not throttled
AutoAutomatic throtling speed is applied.
ManualThrottling time was specified manually (see “Throttling” element)

List of all possible Status values:

Status value
Scheduled
InProgress
Sent
Paused
Draft
Deleted

Examples

Get multiple messages

Request:

GET 
https://api.esv2.com/v2/Api/Messages?startDate=2010-05-19&apiKey=test_api_key1 HTTP/1.1 
Accept-Encoding: gzip,deflate 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com

OK response:

HTTP/1.1 200 OK 
Cache-Control: private 
Content-Type: text/xml; charset=utf-8 
Content-Encoding: gzip 
Vary: Accept-Encoding 
Server: Microsoft-IIS/7.5 
Set-Cookie: ASP.NET_SessionId=cu23cqm125fq1qih1kg4ux45; path=/; HttpOnly 
X-AspNetMvc-Version: 1.0 
X-AspNet-Version: 2.0.50727 
X-Powered-By: ASP.NET 
Date: Mon, 24 May 2010 12:56:22 GMT 
Content-Length: 415 

<ApiResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <Data>
     <Messages>
       <Message>
         <Id>892</Id>
         <FromName>John Smith</FromName>
         <FromEmail>j.smith@domain.com</FromEmail>
         <Subject>test newsletter</Subject>
         <Type>Newsletter</Type>
         <SentDate>2010-05-19T19:35:08</SentDate>
       </Message>
       <Message>
         <Id>893</Id>
         <FromName>Your Favorite Shop</FromName>
         <FromEmail>contact@yfs.com</FromEmail>
         <Subject>test newsletter 2</Subject>
         <Type>Newsletter</Type>
          <SentDate>2010-05-21T14:09:15</SentDate>
         <Tags>test 1</Tags>
       </Message>
     </Messages>
   </Data>
</ApiResponse>

Get message by Message ID

Request:

GET 
https://api.esv2.com/v2/Api/Messages/893?apiKey=test_api_key1 HTTP/1.1 
Accept-Encoding: gzip,deflate 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com

OK response:

HTTP/1.1 200 OK 
Cache-Control: private 
Content-Type: text/xml; charset=utf-8 
Content-Encoding: gzip 
Vary: Accept-Encoding 
Server: Microsoft-IIS/7.5 
Set-Cookie: ASP.NET_SessionId=3e0htsjefgfcby55ra5b2045; path=/; HttpOnly 
X-AspNetMvc-Version: 1.0 
X-AspNet-Version: 2.0.50727 
X-Powered-By: ASP.NET 
Date: Mon, 24 May 2010 12:59:37 GMT 
Content-Length: 369  

<ApiResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <Data>
     <Id>893</Id>
     <FromName>Your Favorite Shop</FromName>
     <FromEmail>contact@yfs.com</FromEmail>
     <Subject>test newsletter 2</Subject>
     <Type>Newsletter</Type>
     <SentDate>2010-05-21T14:09:15</SentDate>
     <Tags>test 1</Tags>
     <Channels>192.168.10.2, 192.168.10.3</Channels>
     <Status>Sent</Status>
     <Lists>
       <List>
         <Id>2</Id>
         <Name>test list</Name>
       </List>
     </Lists>
      <ExcludedLists>
        <List>
          <Id>7484</Id>
          <Name>test exclude - filtr</Name>
        </List>
      </ExcludedLists>
      <ExcludedSegments>
        <Segment>
          <Id>3400</Id>
          <Name>test exclude - filtr</Name>
        </Segment>
      </ExcludedSegments>
    </Data>
</ApiResponse>

Example response with Google Analytics tags and Yandex List ID:

HTTP/1.1 200 OK 
Cache-Control: private 
Content-Type: text/xml; charset=utf-8 
Content-Encoding: gzip 
Vary: Accept-Encoding 
Server: Microsoft-IIS/7.5 
Set-Cookie: ASP.NET_SessionId=3e0htsjefgfcby55ra5b2045; path=/; HttpOnly 
X-AspNetMvc-Version: 1.0 
X-AspNet-Version: 2.0.50727 
X-Powered-By: ASP.NET 
Date: Mon, 24 May 2010 12:59:37 GMT 
Content-Length: 455 

<ApiResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Data>
    <Id>123951</Id>
    <FromName>myFromName</FromName>
    <FromEmail>myfromEmail@domain.com</FromEmail>
    <Subject>Google Analytics tags test</Subject>
    <Type>Newsletter</Type>
    <ThrottlingMethod>Auto</ThrottlingMethod>
    <GoogleAnalyticsTags>
      <GoogleAnalyticsTag>
        <Name>utm_source</Name>
        <Value>testsource</Value>
      </GoogleAnalyticsTag>
      <GoogleAnalyticsTag>
        <Name>utm_medium</Name>
        <Value>Email</Value>
      </GoogleAnalyticsTag>
      <GoogleAnalyticsTag>
        <Name>utm_content</Name>
        <Value>testcontent</Value>
      </GoogleAnalyticsTag>
      <GoogleAnalyticsTag>
        <Name>utm_campaign</Name>
        <Value>testcampaign</Value>
      </GoogleAnalyticsTag>
    </GoogleAnalyticsTags>
    <YandexListId>
      <Identifier>testid</Identifier>
      <Comment>testcomment</Comment>
    </YandexListId>
    <Status>Draft</Status>
  </Data>
</ApiResponse>
Privacy policy