soap api guide - e-shot™ · this document details how customers of e-shot can access ......
TRANSCRIPT
SOAP API Guide Introduction
SOAP API Guide 2
Contents Introduction ................................................................................................................. 4
Getting started ............................................................................................................. 5
Request ................................................................................................................................. 6
Successful response............................................................................................................ 6
Sample request XML: .......................................................................................................... 7
Sample response XML: ....................................................................................................... 8
Methods ........................................................................................................................ 9
CancelQueuedEshotSend ................................................................................................... 9
CreateHtmlUploadEmailDraft ......................................................................................... 10
CreateDynamicHtmlUploadEmailDraft .......................................................................... 14
DeleteContactFromGroup ................................................................................................ 17
DeleteQueuedEshotSend ................................................................................................. 20
FileUploadSubmitContact ................................................................................................ 21
GetCampaignsByStatus .................................................................................................... 26
GetCampaignsSentRecipientFilter .................................................................................. 31
GetContactDisplayNames ................................................................................................ 37
GetContactFields ............................................................................................................... 39
GetContactsByPage ........................................................................................................... 41
GetContactsCount ............................................................................................................. 61
GetEshotDetails ................................................................................................................. 63
GetEshotReports ............................................................................................................... 75
GetEshots ........................................................................................................................... 81
GetFileUploadStatus ......................................................................................................... 87
GetGroups .......................................................................................................................... 89
GetIdentities ....................................................................................................................... 93
GetMonitoredLinksSentRecipientFilter .......................................................................... 95
GetReadyToSendMessages .............................................................................................. 98
QueueSimpleEshotSend ................................................................................................. 101
SOAP API Guide Introduction
SOAP API Guide 3
ReQueueEshotSend ........................................................................................................ 103
SetQueuedEshotOnHold ................................................................................................ 104
SubmitContact ................................................................................................................. 106
SubmitGroup ................................................................................................................... 110
UnsubscribeContact ....................................................................................................... 114
UnsubscribeSmsContact ................................................................................................ 115
Schemas .................................................................................................................... 117
Requests/Responses ....................................................................................................... 117
Appendix ................................................................................................................... 118
Login.xsd .......................................................................................................................... 118
Service exceptions ........................................................................................................... 118
Mobile Numbers .............................................................................................................. 121
Contact...................................................................................................................... 122
SOAP API Guide Introduction
SOAP API Guide 4
Introduction
NOTE: Please contact your account manager to enable this feature as you will
require usernames and passwords to access your e-shot accounts using the API.
This document details how customers of e-shot can access the
API to allow integration into your own internal systems. This
document outlines the available functions of the API to you,
allowing you to customise your internal systems to interact
with e-shot.
Where the methods below relate to Campaigns, Sends, e-shots, they refer to the
email campaigns, sends, etc. SMS Campaigns cannot be manipulated through the
SOAP API.
The e-shot API is a SOAP web service which will allow you to:
Create and update contact information.
Retrieve contacts and their details.
Retrieve groups.
Retrieve reports with all the details for the e-shot send.
Retrieve e-shot send details such as whom the e-shot was sent to, the
number of contacts who read the email, forwarded the email, unsubscribed
and/or clicked.
Create and queue Single Send Campaigns.
SOAP API Guide Getting started
SOAP API Guide 5
Getting started We recommend using SoapUI to create the requests against our API, which can be
downloaded from https://www.soapui.org/downloads/soapui.html. This section is
written assuming SoapUI is being used; however, alternative programs are available.
Once SoapUI is installed the first step is to add a project, which is explained in detail
in this link, https://www.soapui.org/getting-started/your-first-soapui-project.html.
The next step is to associate the e-shot WSDL with the project, a formal definition of
methods, parameters, and return values are available in WSDL format at:
Environment URL Description
PreProduction http://testapi.e-
shot.net/esService.svc?wsdl
WSDL definition file
PreProduction http://testapi.e-
shot.net/help/definitions.html
Request & response body
definitions
Production http://api.e-shot.net/esService.svc?wsdl WSDL definition file
Production http://api.e-shot.net/help/definitions.html Request & response body
definitions
Production is the live environment and any alterations made within that
environment will result in changes to your actual data. PreProduction is our User
Acceptance Testing environment that's periodically backed up from the Production
environment, creating an environment that's ideal if you would like to test the
outcome of running a particular method without risking your live data integrity.
Once the setup has been completed, an XML request can be submitted, which
attempts to retrieve the chosen information and returns it in an XML response. Each
of the methods within this document display an example SOAP request and SOAP
response. All API methods request and return results in a single XML formatted
block; SOAP requests have the following structure:
SOAP API Guide Getting started
SOAP API Guide 6
Request
<s:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
Specific Request
</s:Body>
</s:Envelope>
Successful response
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
Specific Response
</s:Body>
</s:Envelope>
NOTE: Schemas can be found at http://api.e-shot.net/Help/definitions.html
To submit a SOAP request using SoapUI, within the navigation panel on the left,
expand the project tree, locate your chosen request and expand that. Double click on
‘Request 1’ to open the request and response windows, as shown below:
The next step is to locate the XML request within this document, amend the login
details to your standard e-shot website credentials and copy the CDATA information,
which is highlighted below:
SOAP API Guide Getting started
SOAP API Guide 7
Sample request XML:
<soapenv:Envelope xmlns:soapenv=http://schemas.xmlsoap.org/soap/envelope/
xmlns:tem=http://tempuri.org/>
<soapenv:Header/>
<soapenv:Body>
<tem:GetContactDisplayNames>
<tem:requestXML>
<![CDATA[
<GetContactDisplayNamesRq
xmlns:auth=”Login.xsd”
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xsi:noNameSpaceSchemaLocation=http://api.e-
shot.net/Integration/Custom/Requests/GetContactDisplayNamesRq.xsd>
<auth:Login>
<auth:Username>User</auth:Username>
<auth:Password>Pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</GetContactDisplayNamesRq>
]]>
</tem:requestXML>
</tem:GetContactDisplayNames>
</soapenv:Body>
</soapenv:Body>
</soapenv:Envelope>
Within SoapUI, locate the question mark in the request window XML text, delete it
and paste your copied text there. Then press the green arrow icon and observe the
XML response in the window on the right. In this example, the response should
return the available contact fields, although the output should be a long string of
text, rather than being formatted to display in a readable format as you can see
below:
SOAP API Guide Getting started
SOAP API Guide 8
Sample response XML:
<s:Envelope xmlns:s=”http://schemas.xmlsoap.org/soap/envelope/”>
<s:Body>
<GetContactDisplayNamesResponse xmlns=”http://tempuri.org/”>
<GetContactDisplayNamesResult>
<!{CDATA[
<GetContactDisplayNamesRs>
<field>
<DisplayName>Salutation</DisplayName>
<IsCustomField>false</IsCustomField>
</field>
<field>
<DisplayName>Firstname</DisplayName>
<IsCustomField>false</IsCustomField>
</field>
<field>
<DisplayName>Lastname</DisplayName>
<IsCustomField>false</IsCustomField>
</field>
<field>
<DisplayName>Company</DisplayName>
<IsCustomField>false</IsCustomField>
</field>
<field>
<DisplayName>Telephone</DisplayName>
<IsCustomField>false</IsCustomField>
</field>
<field>
<DisplayName>URN</DisplayName>
<IsCustomField>false</IsCustomField>
</field>
</GetContactDisplayNamesRs>
]]>
</GetContactDisplayNamesResult>
</GetContactDisplayNamesResponse>
</s:Body>
<s:Envelope>
If there are problems with the request, the response should display the fault and the
reasons behind it. Additionally, there is a list of the different Error codes at the end of
this document.
NOTE: Within this document, the "e-shot sends" are often referred to as Campaigns.
This does not represent campaigns as found in the Campaigns section of the web
site, it represents the e-shot sends that are produced by campaigns. The name of
this parameter has been retained for backwards compatibility.
e-shot sends represent the sending of an email Message to a list of contacts at a
specific point in time. With Single Send and Resend campaigns there will be a
maximum of one e-shot send per campaign, however in the case of Recurrent and
Automated Series campaigns there may be more than one e-shot send per
campaign.
SOAP API Guide Methods
SOAP API Guide 9
Methods
CancelQueuedEshotSend This method can be called if you have a send currently going out that you wish to
cancel.
Please be aware that, on average, an e-shot campaign queued to 3 million recipients
typicallyakes just under an hour to go out, so you would have to be quick at issuing
this command.
SMS Campaigns cannot be cancelled with this method.
Parameter Data Type Mandatory Description
EshotID Integer Y The campaign identifier
Note: Execute the API Method GetCampaignByStatus for the EshotID
SOAP API Guide Methods
SOAP API Guide 10
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:CancelQueuedEshotSend>
<tem:input>
<![CDATA[
<CancelQueuedEshotSendRequest xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/CancelQueuedEshotSendRequest.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<EshotID>1094</EshotID>
</CancelQueuedEshotSendRequest>
]]>
</tem:input>
</tem:CancelQueuedEshotSend>
</s:Body>
</s:Envelope>
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<CancelQueuedEshotSendResponse xmlns="http://tempuri.org/">
<CancelQueuedEshotSendResult>
<![CDATA[
<CancelQueuedEshotResponse
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Status>CommandSuccessfullyIssued</Status>
</CancelQueuedEshotResponse>
]]>
</CancelQueuedEshotSendResult>
</CancelQueuedEshotSendResponse>
</s:Body>
</s:Envelope>
CreateHtmlUploadEmailDraft This method can be used to create HTML or Text Messages in the e-shot system. e-
shot Message contents could be in the form of HTML and/or Text. The HTML content
SOAP API Guide Methods
SOAP API Guide 11
can be loaded into the system from an HTML file or from a URL that returns HTML
content. Similarly Text content can be supplied from a TEXT file or from a URL
containing text. When only HTML content is supplied and not Text content, e-shot will
generate the Text content from the HTML content. This method returns the ID of the
newly created Message.
Method request
Parameter Data Type Mandatory Description
HtmlUrl String See note A valid encoded URL for
HTML content
Example HtmlUrl:
http://www.yourhtmlcontent.co.uk?p1=a&p2=b
Encoded HTML:
http://www.yourhtmlcontent.co.uk?p1=a&p2=b
HtmlContent String See note Valid encoded HTML
string
Example HTML:
<html><body>your content</body></html>
Encoded HTML:
<html><body>yourcontent</body></html>
NOTE: One of HtmlUrl or HtmlContent must be supplied. It is invalid to supply both.
TextUrl String N Valid encoded URL for
TextContent
TextContent String N Encoded campaign text
for Text emails
NOTE: One of TextUrl or TextContent may be supplied. It is invalid to omit both.
MessageName String Yes, if not
inferred
Any encoded string to
reflect as a campaign's
subject
Example MessageName:
Combine first & second email
Encoded MessageName:
Combine first & second email
SOAP API Guide Methods
SOAP API Guide 12
Subject String Yes, if not
inferred
Any encoded string to
reflect as a campaign’s
subject
Example Subject:
Subject line for combining first & second email
Encoded Subject:
Subject line for combining first & second email
InferSubjectLineFromHtmlTitle Boolean N When true, we will
extract an appropriate
subject line from your
HTML
HtmlSourceRootUrl String N Base URL of HTML
images and links
TextSourceRootUrl String N Base URL for text links
Method response
Parameter Data Type Description
CampaignID Integer Despite being labelled CampaignID
this contains the Identifier of the
Message that was created. This
naming error has been retained for
backwards compatibility.
SOAP API Guide Methods
SOAP API Guide 13
Sample request XML:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<soapenv:Header/>
<soapenv:Body>
<tem:CreateHtmlUploadEmailDraft>
<tem:input>
<![CDATA[
<CreateHtmlUploadEmailDraftRequest xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/CreateHtmlUploadEmailDraftRequest.xs
d">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<HtmlUrl></HtmlUrl>
<HtmlContent>
<!DOCTYPE html>
<html lang="en">
<head>
<title>title of your HTML</title>
</head>
<body>
your html content here
tables
links
images
</body>
</html>
</HtmlContent>
<TextUrl></TextUrl>
<TextContent></TextContent>
<MessageName>{UNIQUE MESSAGE NAME}</MessageName>
<Subject></Subject>
<HtmlSourceRootUrl>http://www.e-shot.net/</HtmlSourceRootUrl>
<TextSourceRootUrl>http://www.e-shot.net/</TextSourceRootUrl>
<InferSubjectLineFromHtmlTitle>
True
</InferSubjectLineFromHtmlTitle>
</CreateHtmlUploadEmailDraftRequest>
]]>
</tem:input>
</tem:CreateHtmlUploadEmailDraft>
</soapenv:Body>
</soapenv:Envelope>
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
SOAP API Guide Methods
SOAP API Guide 14
<CreateHtmlUploadEmailDraftResponse xmlns="http://tempuri.org/">
<CreateHtmlUploadEmailDraftResult>
<?xml version="1.0"?>
<CreateHtmlUploadEmailDraftResponse
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<CampaignID>2916</CampaignID>
<CreateHtmlUploadEmailDraftResponse>
</CreateHtmlUploadEmailDraftResult>
</CreateHtmlUploadEmailDraftResponse>
</s:Body>
</s:Envelope>
CreateDynamicHtmlUploadEmailDraft This method can be used to create Dynamic Messages in the system. Similar to
CreateHtmlUploadEmailDraft method, this also returns the ID of the newly
created dynamic message. Message content can be supplied from any HTML or Text
URL. When only HTML content is supplied and not Text content, e-shot will generate
the Text content from the HTML content.
Method request
Parameter Data Type Mandatory Description
HtmlUrl String Y A valid encoded
URL for HTML
content
Example HtmlUrl:
http://www.yourhtmlcontent.co.uk?p1=a&p2=b
Encoded HTML:
http://www.yourhtmlcontent.co.uk?p1=a&p2=b
TextUrl String N Valid encoded URL
for text content
MessageName String Y A unique encoded
name for the
campaign
SOAP API Guide Methods
SOAP API Guide 15
Example MessageName:
Combine first & second email
Encoded MessageName:
Combine first & second email
Subject String Yes, if not
inferred
Any encoded string
to reflect as a
campaign’s subject
Example Subject:
Subject line for combining first & second email
Encoded Subject:
Subject line for combining first & second email
InferSubjectLineFromHtmlTitle Boolean N When true, we will
extract an
appropriate subject
line from your
HTML
HtmlSourceRootUrl String N Base URL of HTML
images and links
TextSourceRootUrl String N Base URL for text
links
Method response
Parameter Data Type Description
CampaignID Integer Despite being labelled CampaignID
this contains the Identifier of the
Message that was created. This
naming error has been retained for
backwards compatibility.
SOAP API Guide Methods
SOAP API Guide 16
Sample request XML
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<soapenv:Header/>
<soapenv:Body>
<tem:CreateDynamicHtmlUploadEmailDraft>
<tem:input>
<![CDATA[
<CreateDynamicHtmlUploadEmailDraftRequest xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/CreateDynamicHtmlUploadEmailDraftReq
uest.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<HtmlUrl>http://www.yourhtmlcontent.co.uk</HtmlUrl>
<TextUrl></TextUrl>
<TextContent> </TextContent>
<MessageName>{YOUR MESSAGE NAME}</MessageName>
<Subject></Subject>
<HtmlSourceRootUrl></HtmlSourceRootUrl>
<TextSourceRootUrl></TextSourceRootUrl>
<InferSubjectLineFromHtmlTitle> true
</InferSubjectLineFromHtmlTitle>
</CreateDynamicHtmlUploadEmailDraftRequest>
]]>
</tem:input>
</tem:CreateDynamicHtmlUploadEmailDraft>
</soapenv:Body>
</soapenv:Envelope>
Sample response XML
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<CreateDynamicHtmlUploadEmailDraftResponse
xmlns="http://tempuri.org/">
<CreateDynamicHtmlUploadEmailDraftResult>
<?xml version="1.0"?>
<CreateDynamicHtmlUploadEmailDraftResponse
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<CampaignID>2916</CampaignID>
<CreateDynamicHtmlUploadEmailDraftResponse>
</CreateDynamicHtmlUploadEmailDraftResult>
</CreateDynamicHtmlUploadEmailDraftResponse>
</s:Body>
</s:Envelope>
SOAP API Guide Methods
SOAP API Guide 17
DeleteContactFromGroup
Parameter Data Type Description
Email String Email address
Groups String Comma-separated list of group names (e.g.
"Group 1,Group 2,Group 3")
GroupIDs String Comma-separated list of group identifiers (e.g.
"123,546,3465")
NOTE: Execute the API Method GetContactsByPage or GetGroups to get all the
contacts from the group or contacts present across test groups. You must supply
either Groups or GroupIDs but not both at the same time.
SOAP API Guide Methods
SOAP API Guide 18
Remove by group name
Sample request XML
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:DeleteContactFromGroup>
<tem:RqXML>
<![CDATA[
<DeleteContactFromGroupRq
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/DeleteContactFromGroupRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<Email>[email protected]</Email>
<Groups>testing</Groups>
</Params>
<Params>
<Email>[email protected]</Email>
<Groups>testing</Groups>
</Params>
</DeleteContactFromGroupRq>
]]>
</tem:RqXML>
</tem:DeleteContactFromGroup>
</s:Body>
</s:Envelope>
Sample response XML
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<DeleteContactFromGroupResponse xmlns="http://tempuri.org/">
<DeleteContactFromGroupResult>
<![CDATA[
<DeleteContactFromGroupRs>
<Params>
<Email>[email protected]</Email>
<Groups>testing</Groups>
</Params>
<Params>
<Email>[email protected]</Email>
<Groups>testing</Groups>
</Params>
</DeleteContactFromGroupRs>
]]>
SOAP API Guide Methods
SOAP API Guide 19
</DeleteContactFromGroupResult>
</DeleteContactFromGroupResponse>
</s:Body>
</s:Envelope>
Remove by group identifiers
Sample request XML
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:DeleteContactFromGroup>
<tem:RqXML>
<![CDATA[
<DeleteContactFromGroupRq
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/DeleteContactFromGroupRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<Email>[email protected]</Email>
<GroupIDs>1,567,423</GroupIDs>
</Params>
</DeleteContactFromGroupRq>
]]>
</tem:RqXML>
</tem:DeleteContactFromGroup>
</s:Body>
</s:Envelope>
Sample response XML
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<DeleteContactFromGroupResponse xmlns="http://tempuri.org/">
<DeleteContactFromGroupResult>
<![CDATA[
<DeleteContactFromGroupRs>
<Params>
<Email>[email protected]</Email>
<GroupIDs>1,567,423</GroupIDs>
</Params>
SOAP API Guide Methods
SOAP API Guide 20
</DeleteContactFromGroupRs>
]]>
</DeleteContactFromGroupResult>
</DeleteContactFromGroupResponse>
</s:Body>
</s:Envelope>
DeleteQueuedEshotSend This method can be called if you want to delete an e-shot send that has been
queued, but has not been – and is not being – worked on by the campaign processor
to send the emails for the campaign.
One might use this method if a campaign has queued an e-shot send at some point
in the future and then you decide that it is no longer needed.
For Single Send and Resend campaign types this will return the campaign to the
Campaigns section of the web site.
For Automated Series and Recurrent campaigns the specified e-shot send will be lost!
This API does not deactivate the campaign and the campaign will continue to create
future sends as usual.
Queued SMS Campaigns cannot be deleted with this method.
Parameter Data Type Mandatory Description
EshotID Integer Y The e-shot send identifier
NOTE: To retrieve the EshotID execute the API method GetCampaignsByStatus
which returns all the e-shot sends, with their EshotID, that meet the search criteria
specified.
SOAP API Guide Methods
SOAP API Guide 21
Sample request XML
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:DeleteQueuedEshotSend>
<tem:input>
<![CDATA[
<DeleteQueuedEshotSendRequest
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/DeleteQueuedEshotSendRequest.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<EshotID>1095</EshotID>
</DeleteQueuedEshotSendRequest>
]]>
</tem:input>
</tem:DeleteQueuedEshotSend>
</s:Body>
</s:Envelope>
Sample response XML
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<DeleteQueuedEshotSendResponse xmlns="http://tempuri.org/">
<DeleteQueuedEshotSendResult>
<![CDATA[
<DeleteQueuedEshotResponse
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Status>CommandSuccessfullyIssued</Status>
</DeleteQueuedEshotResponse>
]]>
</DeleteQueuedEshotSendResult>
</DeleteQueuedEshotSendResponse>
</s:Body>
</s:Envelope>
FileUploadSubmitContact This method is used to submit contacts to the database by passing a CSV file as a
stream. Contacts and their associated custom field values will be added or updated
SOAP API Guide Methods
SOAP API Guide 22
to the specified group and source. This method will respond with a unique token
and a response message as soon as the file data has been uploaded to our servers.
The status of the upload can be retrieved by executing API method
GetFileUploadStatus with the unique token value.
If the uploaded file contains some invalid rows of data, only the valid rows of data
will be imported into the system. A response message will be returned indicating the
issues encountered.
NOTE: The first row of the CSV file must contain a comma separated list of column
names. If this is not present the upload will fail to complete even if the response
states otherwise.
The file encoding must be in Windows Ansi (code page 1252).
Special care must be taken if any of the fields in your data contain one or more
commas. See Upload File Formatting for more information.
You must supply either a GroupName or a GroupID column but not both.
Method request
Columns headings
Parameter Data Type Mandatory Description
GroupName String N Any string value (can be an
existing, or new, group
name)
GroupID Number N An identifier for a group
SourceName String Y Any string value (can be an
existing, or new, source
name)
Email String Y Valid email address
Mobile String N Valid mobile number (see
Mobile Numbers)
Salutation String N Contact salutation
Firstname String N Contact first name
Lastname String N Contact last name
SOAP API Guide Methods
SOAP API Guide 23
Company String N Company name
Telephone String N Valid telephone number
URN String N A unique reference
<customfieldname> String N E.g. Postcode
The system will create the GroupName/SourceName if they don’t exist in the
database.
If you specify the group by identifier by supplying a GroupID column then the group
must already exist or the upload will fail.
<customfieldname> - From the Name in the Contacts Manager – Field Manager.
Please create an instance of FileUploadContactMessage and populate the
properties. The file name and login credentials need to be passed to the message
header, while the file content should be passed as a stream within the message
body.
Class name: FileUploadContactMessage
MessageHeader
Parameter Data Type Mandatory Description
FileName String Y File name
LoginCredentials String Y Login
credentials
MessageBodyMember
Parameter Data Type Mandatory Description
FileByteStream Stream Y Stream
SOAP API Guide Methods
SOAP API Guide 24
Method response
The response can be retrieved using the class name:
FileUploadContactResponseMessage
MessageBodyMember
Parameter Data Type Mandatory Description
Token String Y API token
ResponseMessage String Y Description of progress
SOAP API Guide Methods
SOAP API Guide 25
E.g. (C# code)
var loginCredentials = @"<FileUploadSubmitContactRq
xmlns:auth=’Login.xsd’>
<auth:Login>
<auth:Username>username</auth:Username>
<auth:Password>password</auth:Password>
<auth:Email>email</auth:Email>
<auth:Subaccountid>subaccountid</auth:Subaccountid>
</auth:Login>
</FileUploadSubmitContactRq>";
var uploadMessage = new FileUploadContactMessage();
uploadMessage.FileName = Path.GetFileName(<filepath>);
var stream = File.Open(<filePath>, FileMode.Open, FileAccess.Read, File
Share.None);
uploadMessage.FileByteStream = stream;
uploadMessage.LoginCredentials = loginCredentials;
var serviceUrl = "http://api.e-shot.net/esService.svc/FileUpload";
var basicHttpBinding = new BasicHttpBinding
{
//THIS IS REQUIRED
MessageEncoding = WSMessageEncoding.Mtom
};
var fileUpload = new FileUploadServiceClient(basicHttpBinding, new
EndpointAddress(serviceUrl));
var response = fileUpload.FileUploadSubmitContact(uploadMessage);
var token = response.Token;
var responseMessage = response.ResponseMessage;
Upload File Formatting
The following is an example of the formatting required by our system. It is not an
example of the data you would eventually upload to e-shot but is only meant to
demonstrate the formatting requirements in a simple manner.
So if you had a record like this…
OwnID CompanyName FaxNumber
22 45 Consulting, Inc. 0207 885 6630, 0207 885 6631,
0207 885 6632
You can see that the CompanyName field contains a single comma and the
FaxNumber field contains multiple commas. When you output these fields to a CSV
file for upload you would need to take special care to make sure that the content of
the CompanyName and FaxNumber fields are correctly escaped.
SOAP API Guide Methods
SOAP API Guide 26
NOTE: Fields with one or more embedded commas must be output with double
quotes at the start and the end of the field data.
The double quote must be a simple double quote (hex value 0x22) and not the smart
quotes commonly used by word processing applications.
So the previous example would need to be output like this…
OwnID,CompanyName,FaxNumber
22, "4S Consulting, Inc. ","0207 885 6630,0207 885 6631,0207 885 6632"
None of the field headers have embedded commas and so do not need to be
wrapped in simple double quotes.
The OwnID field does not need to be enclosed in quote marks because the field data
does not contain any commas. You could output it wrapped in double quotes as well
if you wanted to.
The CompanyName contains a single comma and so must be wrapped in simple
double quotes.
The FaxNumber field has multiple embedded commas and so also needs to be
wrapped in quotes.
GetCampaignsByStatus This method is used to retrieve all the e-shot sends with details like ID,
MessageType, Name, Status and Subject.
The status of SMS Campaigns cannot be obtained with this method.
NOTE: This API is from before the Campaigns section was added to the e-shot web
site. What this API actually returns is details of e-shot sends which are produced by
Campaigns. In the case of Automated Series and Recurrent campaigns there may be
more than one e-shot send for each campaign. The name of this API has been
retained for backwards compatibility.
SOAP API Guide Methods
SOAP API Guide 27
Statuses that can be assigned to an e-shot send
ResponseMessage
Waiting
OnHold
InProgress
Cancelled
Undefined
Parameter Data Type Mandatory Description
ConstructionType Enumeration Y Unknown,
TemplateWizard,
HtmlEditor,
HtmlUpload,
PlainText,
DynamicHtmlUpload
& DragAndDrop
IncludeArchive Boolean Y true or false
Status Enumeration Y Undefined, OnHold,
Waiting,
InProgress, Sent
& Cancelled
SendDateFrom* DateTime Y Nillable attribute
or datetime value
SendDateTo* DateTime Y Nillable attribute
or datetime value
SubjectLine Complex Type N Optional element
SubjectLine\SearchType Enumeration Y Contains, Exact,
StartsWith,
EndsWith
SubjectLine\Text String N Optional element
ReportName Complex Type N
SOAP API Guide Methods
SOAP API Guide 28
ReportName\SearchType Enumeration Y Unknown,
TemplateWizard,
HtmlEditor,
HtmlUpload,
PlainText,
DynamicHtmlUpload
& DragAndDrop
ReportName\Text Boolean Y true or false
* If the XML elements SendDateFrom or SendDateTo are specified, but no value
given, you will need to explicitly set them to NILLABLE=TRUE, (e.g xsi:nil="true") as
demonstrated below:
Example
<SendDateFrom xsi:nil="true"></SendDateFrom>
<SendDateTo xsi:nil="true"></SendDateTo>
The example below uses the <SearchType> element to narrow the search results:
SOAP API Guide Methods
SOAP API Guide 29
Sample request XML
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetCampaignsByStatus>
<tem:input>
<![CDATA[
<GetCampaignByStatusRequest
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetCampaignByStatusRequest.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<ConstructionType>PlainText</ConstructionType>
<IncludeArchive>true</IncludeArchive>
<SendDateFrom>2014-09-01T00:00:00</SendDateFrom>
<SendDateTo>2014-09-09T00:00:00</SendDateTo>
<Status>Sent</Status>
<SubjectLine>
<SearchType>Contains</SearchType>
<Text>ClickThroughTesting</Text>
</SubjectLine>
</GetCampaignByStatusRequest>]]>
</tem:input>
</tem:GetCampaignsByStatus>
</s:Body>
</s:Envelope>
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetCampaignsByStatusResponse xmlns="http://tempuri.org/">
<GetCampaignsByStatusResult>
<![CDATA[<?xml version="1.0"?>
<CampaignBasicDetailsResponse
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Campaigns>
<CampaignBasicDetails>
<ID>1196</ID>
<MessageType>PlainText</MessageType>
<Name>ClickThroughTesting</Name>
<Status>Sent</Status>
<Subject>ClickThroughTesting</Subject>
</CampaignBasicDetails>
</Campaigns>
</CampaignBasicDetailsResponse>
]]>
SOAP API Guide Methods
SOAP API Guide 30
</GetCampaignsByStatusResult>
</GetCampaignsByStatusResponse>
</s:Body>
</s:Envelope>
The example below uses the <ReportName> element to narrow the search results:
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetCampaignsByStatus>
<tem:input>
<![CDATA[
<GetCampaignByStatusRequest
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetCampaignByStatusRequest.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<ConstructionType>PlainText</ConstructionType>
<IncludeArchive>true</IncludeArchive>
<SendDateFrom>2014-09-01T00:00:00</SendDateFrom>
<SendDateTo>2014-09-09T00:00:00</SendDateTo>
<Status>Sent</Status>
<ReportName>
<SearchType>Contains</SearchType>
<Text>Click</Text>
</ReportName>
</GetCampaignByStatusRequest>
]]>
</tem:input>
</tem:GetCampaignsByStatus>
</s:Body>
</s:Envelope>
SOAP API Guide Methods
SOAP API Guide 31
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetCampaignsByStatusResponse xmlns="http://tempuri.org/">
<GetCampaignsByStatusResult>
<![CDATA[
<CampaignBasicDetailsResponse
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Campaigns>
<CampaignBasicDetails>
<ID>1196</ID>
<MessageType>PlainText</MessageType>
<Name>ClickThroughTesting</Name>
<Status>Sent</Status>
<Subject>ClickThroughTesting</Subject>
</CampaignBasicDetails>
</Campaigns>
</CampaignBasicDetailsResponse>
]]>
</GetCampaignsByStatusResult>
</GetCampaignsByStatusResponse>
</s:Body>
</s:Envelope>
GetCampaignsSentRecipientFilter This method returns sent e-shot send information for the specified filter criteria.
NOTE: This API is from before the Campaigns section was added to the e-shot web
site. What this API actually returns is details of e-shot sends which are produced by
Campaigns. In the case of Automated Series and Recurrent campaigns there may be
more than one e-shot send for each campaign. The name of this API has been
retained for backwards compatibility.
The values that can be passed for ConstructionType element are as follows:
Parameter Data Type Mandatory Description
ConstructionType Enumeration Y Unknown, TemplateWizard,
HtmlEditor, HtmlUpload,
PlainText,
DynamicHtmlUpload &
DragAndDrop
SOAP API Guide Methods
SOAP API Guide 32
IncludeArchive Boolean Y true or false
Status Enumeration Y Undefined, OnHold,
Waiting, InProgress,
Sent & Cancelled
SendDateFrom* DateTime Y Nillable attribute or
datetime value
SendDateTo* DateTime Y Nillable attribute or
datetime value
SubjectLine\
SearchType
Enumeration N Contains, Exact,
StartsWith, EndsWith
* If the XML elements SendDateFrom or SendDateTo are specified, but no value
given, you will need to explicitly set them to NILLABLE=TRUE, (e.g xsi:nil="true") as
demonstrated below:
Example
<SendDateFrom xsi:nil="true"></SendDateFrom>
<SendDateTo xsi:nil="true"></SendDateTo>
SOAP API Guide Methods
SOAP API Guide 33
Sample request XML
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetCampaignsSentRecipientFilter>
<tem:input>
<![CDATA[
<GetCampaignsSentRecipientFilterRequest
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetCampaignsSentRecipientFilterReque
st.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<ConstructionType>Unknown</ConstructionType>
<IncludeArchive>true</IncludeArchive>
<SendDateFrom>2014-01-01T00:00:00</SendDateFrom>
<SendDateTo>2014-02-21T00:00:00</SendDateTo>
<Status>Sent</Status>
</GetCampaignsSentRecipientFilterRequest>
]]>
</tem:input>
</tem:GetCampaignsSentRecipientFilter>
</s:Body>
</s:Envelope>
Sample response XML
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetCampaignsSentRecipientFilterResponse xmlns="http://tempuri.org/">
<GetCampaignsSentRecipientFilterResult>
<![CDATA[
<?xml version="1.0"?>
<CampaignsSentRecipientFilterResponse
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Recipients>
<CampaignSentRecipientFilterCriteria>
<CampaignID>1084</CampaignID>
<ReportName>Retailers_2014</ReportName>
<SentDate>2014-01-06T10:20:08.693</SentDate>
<SubjectLine>Take Advantage of the Rush</SubjectLine>
</CampaignSentRecipientFilterCriteria>
<CampaignSentRecipientFilterCriteria>
<CampaignID>1090</CampaignID>
<ReportName>testing 17 Jan-1</ReportName>
<SentDate>2014-01-20T12:19:33.363</SentDate>
<SubjectLine>testing 17 Jan</SubjectLine>
SOAP API Guide Methods
SOAP API Guide 34
</CampaignSentRecipientFilterCriteria>
</Recipients>
</CampaignsSentRecipientFilterResponse>
]]>
</GetCampaignsSentRecipientFilterResult>
</GetCampaignsSentRecipientFilterResponse>
</s:Body>
</s:Envelope>
The example below uses the <SubjectLine> element to narrow the search results:
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetCampaignsSentRecipientFilter>
<tem:input>
<![CDATA[
<GetCampaignsSentRecipientFilterRequest
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetCampaignsSentRecipientFilterReque
st.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<ConstructionType>Unknown</ConstructionType>
<IncludeArchive>true</IncludeArchive>
<SendDateFrom>2014-01-01T00:00:00</SendDateFrom>
<SendDateTo>2014-02-21T00:00:00</SendDateTo>
<Status>Sent</Status>
<SubjectLine>
<SearchType>Contains</SearchType>
<Text>Take Advantage of the Rush</Text>
</SubjectLine>
</GetCampaignsSentRecipientFilterRequest>
]]>
</tem:input>
</tem:GetCampaignsSentRecipientFilter>
</s:Body>
</s:Envelope>
SOAP API Guide Methods
SOAP API Guide 35
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetCampaignsSentRecipientFilterResponse xmlns="http://tempuri.org/">
<GetCampaignsSentRecipientFilterResult>
<![CDATA[
<CampaignsSentRecipientFilterResponse
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xs="http://www.w3.org/2001/XMLSchema-instance">
<Recipients>
<CampaignSentRecipientFilterCriteria>
<CampaignID>1084</CampaignID>
<ReportName>Retailers_2014</ReportName>
<SentDate>2014-01-06T10:20:08.693</SentDate>
<SubjectLine>Take Advantage of the Rush</SubjectLine>
</CampaignSentRecipientFilterCriteria>
</Recipients>
</CampaignsSentRecipientFilterResponse>
]]>
</GetCampaignsSentRecipientFilterResult>
</GetCampaignsSentRecipientFilterResponse>
</s:Body>
</s:Envelope>
The example below uses the <ReportName> element to narrow the search results:
SOAP API Guide Methods
SOAP API Guide 36
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetCampaignsSentRecipientFilter>
<tem:input>
<![CDATA[
<GetCampaignsSentRecipientFilterRequest
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetCampaignsSentRecipientFilterReque
st.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<ConstructionType>Unknown</ConstructionType>
<IncludeArchive>true</IncludeArchive>
<SendDateFrom>2014-01-01T00:00:00</SendDateFrom>
<SendDateTo>2014-02-21T00:00:00</SendDateTo>
<Status>Sent</Status>
<ReportName>
<SearchType>Contains</SearchType>
<Text>test</Text>
</ReportName>
</GetCampaignsSentRecipientFilterRequest>
]]>
</tem:input>
</tem:GetCampaignsSentRecipientFilter>
</s:Body>
</s:Envelope>
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetCampaignsSentRecipientFilterResponse xmlns="http://tempuri.org/">
<GetCampaignsSentRecipientFilterResult>
<![CDATA[
<CampaignsSentRecipientFilterResponse
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Recipients>
<CampaignSentRecipientFilterCriteria>
<CampaignID>1090</CampaignID>
<ReportName>testing 17 Jan-1</ReportName>
<SentDate>2014-01-20T12:19:33.363</SentDate>
<SubjectLine>testing 17 Jan</SubjectLine>
</CampaignSentRecipientFilterCriteria>
</Recipients>
</CampaignsSentRecipientFilterResponse>
SOAP API Guide Methods
SOAP API Guide 37
]]>
</GetCampaignsSentRecipientFilterResult>
</GetCampaignsSentRecipientFilterResponse>
</s:Body>
</s:Envelope>
GetContactDisplayNames Returns a list of the active and visible contact fields.
NOTE: The returned list does not include the email field as this is always present. All
standard and custom fields are included.
Parameter Data Type Mandatory Description
No parameters for this method call
SOAP API Guide Methods
SOAP API Guide 38
Sample request XML:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<soapenv:Header/>
<soapenv:Body>
<tem:GetContactDisplayNames>
<tem:requestXML>
<![CDATA[
<GetContactDisplayNamesRq
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetContactDisplayNamesRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
</GetContactDisplayNamesRq>
]]>
</tem:requestXML>
</tem:GetContactDisplayNames>
</soapenv:Body>
</soapenv:Envelope>
SOAP API Guide Methods
SOAP API Guide 39
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetContactDisplayNamesResponse xmlns="http://tempuri.org/">
<GetContactDisplayNamesResult>
<![CDATA[
<GetContactDisplayNamesRs>
<field>
<DisplayName>Salutation</DisplayName>
<IsCustomField>false</IsCustomField>
</field>
<field>
<DisplayName>Firstname</DisplayName>
<IsCustomField>false</IsCustomField>
</field>
<field>
<DisplayName>Lastname</DisplayName>
<IsCustomField>false</IsCustomField>
</field>
<field>
<DisplayName>Company</DisplayName>
<IsCustomField>false</IsCustomField>
</field>
<field>
<DisplayName>Telephone</DisplayName>
<IsCustomField>false</IsCustomField>
</field>
<field>
<DisplayName>URN</DisplayName>
<IsCustomField>false</IsCustomField>
</field>
</GetContactDisplayNamesRs>
]]>
</GetContactDisplayNamesResult>
</GetContactDisplayNamesResponse>
</s:Body>
</s:Envelope>
GetContactFields This method returns a list of Contact Fields (Standard and Custom). RowNumber and
Email are always returned by GetContactsByPage, as they are mandatory fields
they are not returned by this method. The Standard fields are Salutation, Firstname,
Lastname, Company, Telephone, URN and Mobile Number. Should you require extra
fields adding to your account, please contact e-shot Support.
Parameter Data Type Mandatory Description
No parameters for this method call
SOAP API Guide Methods
SOAP API Guide 40
GetContactFields
This would retrieve all (standard and custom) contact fields associated with Sub
Account ID 2.
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetContactFields>
<tem:XML>
<![CDATA[
<GetContactFieldsRequest
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetContactFieldsRequest.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
</GetContactFieldsRequest>
]]>
</tem:XML>
</tem:GetContactFields>
</s:Body>
</s:Envelope>
SOAP API Guide Methods
SOAP API Guide 41
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetContactFieldsResponse xmlns="http://tempuri.org/">
<![CDATA[
<GetContactFields>
<DisplayFields>
<DisplayField DataType="String">
<Name>Salutation</Name>
</DisplayField>
<DisplayField DataType="String">
<Name>Firstname</Name>
</DisplayField>
<DisplayField DataType="String">
<Name>Lastname</Name>
</DisplayField>
<DisplayField DataType="String">
<Name>Company</Name>
</DisplayField>
<DisplayField DataType="String">
<Name>Telephone</Name>
</DisplayField>
<DisplayField DataType="String">
<Name>URN</Name>
</DisplayField>
<DisplayField DataType="String">
<Name>Nickname</Name>
</DisplayField>
<DisplayField DataType="Date">
<Name>Birthday</Name>
</DisplayField>
<DisplayField DataType="DayAndMonth">
<Name>Anniversary</Name>
</DisplayField>
</DisplayFields>
</GetContactFields>
]]>
</GetContactFieldsResponse>
</s:Body>
</s:Envelope>
GetContactsByPage This method is used to provide Paged retrieval of Contacts. The fields returned are
specified in the Select parameter, RowNumber and Email are always returned and it
is invalid to specify them as select fields. GetContactsByPage also provides a
greater degree of flexibility with the provision of the Where parameter. Contacts can
be filtered by Source(s) and/or Group(s) and also by DisplayNameValues by using
the ComparisonTypes available (see ComparisonType for details). PageSize
cannot exceed 10,000 rows.
SOAP API Guide Methods
SOAP API Guide 42
Parameter Data Type Mandatory Description
Select String N Fields to be returned by the query.
RowNumber and Email will always be
returned and should NOT be included in the list
of select fields. The list can include both
standard fields [Salutation, Firstname,
Lastname, Company, Telephone, URN, Mobile,
Unsubscribe, HardBounce, SoftBounce] and
custom fields. Custom fields are fields that you
have requested e-shot support add to your
contact custom fields. A list of all contact fields,
both standard and custom, can be retrieved by
calling GetContactFields.
Please note Group is NOT a valid column
selection as a single contact can belong to many
groups.
Where Complex
Type
Y See Where clause for details
NOTE: The SOAP response list will return all of the standard fields, however the
actual values will not be returned unless they are specified in the <Select> section
of the request.
Where
Parameter Data
Type
Mandatory Description
AccountID String Y AccountID – The sub account against
which the query is to be run. Example
DisplayNameValues Complex
Type
N A list of ContactAttribute –
against which to query. Requires the
Name of the field to query against and
the ComparisonType for this query
(see DisplayNameValues below for
SOAP API Guide Methods
SOAP API Guide 43
details). However the
ComparisonType does not
necessarily require any comparison
attributes to be declared (i.e.
CompareOperator or IsEmpty). See
default values as given below when not
declared
Groups Complex
Type
N A list of Group names to filter on.
Operator – And/Or operator. Defines
behaviour across multiple groups.
There should be at least one group
name (String) specified in a <Group>
tag. Example
GroupIDs Complex
Type
N A list of Group identifiers to filter on.
Operator – And/Or operator. Defines
behaviour across multiple Group
identifiers. There should be at least
one Group ID (Integer) specified in the
<Identifier> tag. Example
Page Complex
Type
Y PageSize – Number of rows per page.
PageNumber – The number of the page
being requested.
Provides a mechanism to break up the
amount of data you retrieve into
“Chunks”. [e.g. 100,000 records could
be broken into 20 pages of 5,000
records each, Increment the
PageNumber each request to retrieve
the next page]. Example
Sources Complex
Type
N A list of Source names to include
Operator – And/Or operator. Defines
behaviour across multiple Sources.
<Sources> should appear after <Page>
<Where>
<AccountID>?</AccountID>
<Page>…</Page>
<Sources Operator="Or">
<Source>WEBSITE</Source>
<Sources></Where>
SOAP API Guide Methods
SOAP API Guide 44
DisplayNameValues
This block provides the greater flexibility to filter contacts with certain values in their
standard or custom contact fields be specifying the contact field name(s) and the
filter criteria in the following format. Field names can include both standard fields
[Email, Salutation, Firstname, Lastname, Company, Telephone, URN, Unsubscribe,
Hardbounce, Mobile] and custom fields. Each field name should be in its own
<ContactAttribute> tag with related ComparisonType. Check DisplayNameValues
examples.
<DisplayNameValues>
<ContactAttribute>
<Name>FieldName</Name>
<ComparisonType CompareOperator="And" IsEmpty="false">
<!-Attributes are optional->
<!–Your selected ComparisonType goes here->
</ComparisonType>
</ContactAttribute>
</DisplayNameValues>
ComparisonType
Parameter Data
Type
Mandatory Description
CompareOperator
attribute
String N CompareOperator – Defines [And/Or]
relation to other ContactAttribute
queries. Default operator is [And] in
case nothing is specified. The operator
is case sensitive
IsEmpty
attribute
Boolean N Used to define whether the Name field
IsEmpty or not. Can be used in
conjunction with one of the
ComparisonType to refine queries or
simply filter out blank or null values.
IsEmpty = null as a default. When
nothing is specified the result can have
both empty and null records
SOAP API Guide Methods
SOAP API Guide 45
Compare
Parameter Data Type Mandatory Description
Contains/
NotContains
String N Performs a “Like/Not Like” query
for the Name field against a single
string value passed in.
Only valid for columns defined as
string (varchar) datatype. e.g.
<Contains>sometext</Contains
>
Equal/NotEqual String N Matches the Name field that is
Equal or NotEqual to the value
passed in. Valid for all data types
except Date/DateTime.
e.g.
<Equal>sometext</Equal>When
nothing is specified the result can
have both empty and null records
In/NotIn String N Performs an In/NotIn query for the
Name field against an array of
strings passed in.
<In>
<string>String1</string>
<string>String2</string>
</In>
LessThan/
GreaterThan
String N Performs <or> query for the Name
field against the value passed in.
Valid for all data types.
e.g.
<LessThan>100</LessThan>
SOAP API Guide Methods
SOAP API Guide 46
EqualDayMonthYear DateCompare Matches the Name field where the
Day, Month and Year are equal.
Only valid for columns defined as
Date or DateTime datatypes.
Ignores the time part if it exists in
the database field.
e.g.
<EqualDayMonthYear>
<Day>25</Day>
<Month>7</Month>
<Year>2014</Year>
</EqualDayMonthYear>
Wild card searches can be
performed by putting a 0 as the
wild card in one or more fields. The
following would match 25th July for
any year.
e.g.
<EqualDayMonthYear>
<Day>25</Day>
<Month>7</Month>
<Year>0</Year>
</EqualDayMonthYear>
IsAnniversary
Boolean N Matches the Name field where the
Day and Month are equal to the
Current System Date (Day and
Month) for any year.
Only valid for columns defined as
Date or DateTime datatypes.
e.g.
<IsAnniversary>true</IsAnniv
ersary>
GetContactsByPage
This would retrieve all of the contacts associated with Sub Account ID 2 using a
PageSize of 1000. By incrementing the PageNumber after each request, retrieve all
the records 1000 at a time. (See GetContactsCount for details on how to retrieve
the total number of records)
SOAP API Guide Methods
SOAP API Guide 47
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetContactsByPage>
<tem:XML>
<![CDATA[
<GetContactsByPageRequest
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetContactsByPageRequest.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Select>
<Name>Salutation</Name>
<Name>Firstname</Name>
<Name>Lastname</Name>
<Name>Company</Name>
<Name>Telephone</Name>
<Name>URN</Name>
<Name>Unsubscribe</Name>
<Name>HardBounce</Name>
<Name>SoftBounce</Name>
<Name>Mobile</Name>
</Select>
<Where>
<AccountID>2</AccountID>
<Page>
<PageNumber>1</PageNumber>
<PageSize>1000</PageSize>
</Page>
</Where>
</GetContactsByPageRequest>
]]>
</tem:XML>
</tem:GetContactsByPage>
</s:Body>
</s:Envelope>
SOAP API Guide Methods
SOAP API Guide 48
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetContactsByPageResponse xmlns="http://tempuri.org/">
<![CDATA[
<GetContactsByPage>
<Contacts>
<ContactBasicDetails>
<RowNumber>1</RowNumber>
<Email>[email protected]</Email>
<Salutation>Mr</Salutation>
<Firstname>John</Firstname>
<Lastname>Smith</Lastname>
<Company>Smith & Sons Ltd</Company>
<Telephone>01234567890</Telephone>
<Urn>UrnFieldValue</Urn>
<Unsubscribe>False</Unsubscribe>
<HardBounce>True</HardBounce>
<SoftBounce>False</SoftBounce>
<Mobile>07900 123456</Mobile>
</ContactBasicDetails>
<ContactBasicDetails>
Next record values, repeated for each row in resultset.
</ContactBasicDetails>
</Contacts>
</GetContactsByPage>
]]>
</GetContactsByPageResponse>
</s:Body>
</s:Envelope>
Get contacts by page where groups (Groups):
This would retrieve all of the contacts associated with Sub Account ID 2 using a
PageSize of 1000, where the contacts are in a group named TestGroup0 or
TestGroup1. Where Sources queries match the behaviour of groups.
SOAP API Guide Methods
SOAP API Guide 49
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetContactsByPage>
<tem:XML>
<![CDATA[
<GetContactsByPageRequest
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetContactsByPageRequest.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Select>
<Name>Salutation</Name>
<Name>Firstname</Name>
<Name>Lastname</Name>
<Name>Company</Name>
<Name>Telephone</Name>
<Name>URN</Name>
<Name>Unsubscribe</Name>
<Name>HardBounce</Name>
<Name>SoftBounce</Name>
<Name>Mobile</Name>
</Select>
<Where>
<AccountID>2</AccountID>
<Groups Operator="Or">
<Group>TestGroup0</Group>
<Group>TestGroup1</Group>
</Groups>
<Page>
<PageNumber>1</PageNumber>
<PageSize>1000</PageSize>
</Page>
</Where>
</GetContactsByPageRequest>
]]>
</tem:XML>
</tem:GetContactsByPage>
</s:Body>
</s:Envelope>
SOAP API Guide Methods
SOAP API Guide 50
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetContactsByPageResponse xmlns="http://tempuri.org/">
<![CDATA[
<GetContactsByPage>
<Contacts>
<ContactBasicDetails>
<RowNumber>1</RowNumber>
<Email>[email protected]</Email>
<Salutation>Mr</Salutation>
<Firstname>John</Firstname>
<Lastname>Smith</Lastname>
<Company>Smith & Sons Ltd</Company>
<Telephone>01234567890</Telephone>
<Urn>UrnFieldValue</Urn>
<Unsubscribe>False</Unsubscribe>
<HardBounce>True</HardBounce>
<SoftBounce>False</SoftBounce>
<Mobile>07900 123456</Mobile>
</ContactBasicDetails>
<ContactBasicDetails>
Next record values, repeated for each row in resultset.
</ContactBasicDetails>
</Contacts>
</GetContactsByPage>
]]>
</GetContactsByPageResponse>
</s:Body>
</s:Envelope>
Get contacts by page where group identifiers (GroupIDs):
This would retrieve all of the contacts associated with Sub Account ID 2 using a
PageSize of 1000, where the contacts are in a group with an ID of 1 or 2. Where
Sources queries match the behaviour of groups.
SOAP API Guide Methods
SOAP API Guide 51
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetContactsByPage>
<tem:XML>
<![CDATA[
<GetContactsByPageRequest
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetContactsByPageRequest.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Select>
<Name>Salutation</Name>
<Name>Firstname</Name>
<Name>Lastname</Name>
<Name>Company</Name>
<Name>Telephone</Name>
<Name>URN</Name>
<Name>Unsubscribe</Name>
<Name>HardBounce</Name>
<Name>SoftBounce</Name>
<Name>Mobile</Name>
</Select>
<Where>
<AccountID>2</AccountID>
<GroupIDs Operator="Or">
<Identifier>1</Identifier>
<Identifier>2</Identifier>
</GroupIDs>
<Page>
<PageNumber>1</PageNumber>
<PageSize>1000</PageSize>
</Page>
</Where>
</GetContactsByPageRequest>
]]>
</tem:XML>
</tem:GetContactsByPage>
</s:Body>
</s:Envelope>
SOAP API Guide Methods
SOAP API Guide 52
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetContactsByPageResponse xmlns="http://tempuri.org/">
<![CDATA[
<GetContactsByPage>
<Contacts>
<ContactBasicDetails>
<RowNumber>1</RowNumber>
<Email>[email protected]</Email>
<Salutation>Mr</Salutation>
<Firstname>John</Firstname>
<Lastname>Smith</Lastname>
<Company>Smith & Sons Ltd</Company>
<Telephone>01234567890</Telephone>
<Urn>UrnFieldValue</Urn>
<Unsubscribe>False</Unsubscribe>
<HardBounce>True</HardBounce>
<SoftBounce>False</SoftBounce>
<Mobile>07900 123456</Mobile>
</ContactBasicDetails>
<ContactBasicDetails>
Next record values, repeated for each row in resultset.
</ContactBasicDetails>
</Contacts>
</GetContactsByPage>
]]>
</GetContactsByPageResponse>
</s:Body>
</s:Envelope>
DisplayNameValues examples
Parameter Data
Type
Mandatory Description
Unsubscribe Boolean N The contact's subscription status,
denoted bny the values "True" or
"False"
HardBounce Boolean N The contact's bounce status, denoted
by the values "True" or "False"
Email String N The contact's email
Any other
standard field
String N See DisplayNameValues section
above for a list of the standard fields
as of the most recent document
publication
SOAP API Guide Methods
SOAP API Guide 53
Any other custom
field
String N As created by the account
administrator
Get contacts by page where the contacts have not unsubscribed and are hardbounced (DisplayNameValue):
This would retrieve all of the contacts associated with Sub Account ID 2 using a
PageSize of 10, where all contacts that have not unsubscribed and are
hardbounced. Notice that when IsEmpty field is not specified the records can have
both empty and non-empty values for the unsubscribe column value. Compare
operator is of [And] type by default, in this case.
SOAP API Guide Methods
SOAP API Guide 54
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetContactsByPage>
<tem:XML>
<![CDATA[
<GetContactsByPageRequest
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetContactsByPageRequest.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Select>
<Name>Salutation</Name>
<Name>Firstname</Name>
<Name>Lastname</Name>
<Name>Unsubscribe</Name>
<Name>Hardbounce</Name>
</Select>
<Where>
<AccountID>2</AccountID>
<DisplayNameValues>
<ContactAttribute>
<Name>Unsubscribe</Name>
<ComparisonType CompareOperator="And" IsEmpty="false">
<Equal>False</Equal>
</ComparisonType>
</ContactAttribute>
<ContactAttribute>
<Name>HardBounce</Name>
<ComparisonType CompareOperator="And" IsEmpty="false">
<Equal>True</Equal>
</ComparisonType>
</ContactAttribute>
</DisplayNameValues>
<Page>
<PageNumber>1</PageNumber>
<PageSize>10</PageSize>
</Page>
</Where></GetContactsByPageRequest>]]>
</tem:XML>
</tem:GetContactsByPage>
</s:Body>
</s:Envelope>
SOAP API Guide Methods
SOAP API Guide 55
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetContactsByPageResponse xmlns="http://tempuri.org/">
<![CDATA[
<GetContactsByPage>
<Contacts>
<ContactBasicDetails>
<RowNumber>1</RowNumber>
<Email>[email protected]</Email>
<Salutation>Mr</Salutation>
<Firstname>John</Firstname>
<Lastname>Smith</Lastname>
<Unsubscribe>False</Unsubscribe>
<HardBounce>True</HardBounce>
<ContactResponseAttributes />
</ContactBasicDetails>
<ContactBasicDetails>
Next record values, repeated for each row in resultset.
</ContactBasicDetails>
</Contacts>
</GetContactsByPage>
]]>
</GetContactsByPageResponse>
</s:Body>
</s:Envelope>
Get contacts by page where one or more fields match one or more values (DisplayNameValue):
This would retireve all of the contacts assocated with Sub Account ID 2 using a
PageSize of 1000, where the Lastname equals “Smith” and JobTitle equals “Sales
Administrator”. NB JobTitle would need to be a field that you have added to your
custom fields via Field Manager.
SOAP API Guide Methods
SOAP API Guide 56
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetContactsByPage>
<tem:XML>
<![CDATA[
<GetContactsByPageRequest
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetContactsByPageRequest.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Select>
<Name>Salutation</Name>
<Name>Firstname</Name>
<Name>Lastname</Name>
<Name>Company</Name>
<Name>Telephone</Name>
<Name>URN</Name>
<Name>JobTitle</Name>
</Select>
<Where>
<AccountID>2</AccountID>
<DisplayNameValues>
<ContactAttribute>
<Name>Lastname</Name>
<ComparisonType CompareOperator="And" IsEmpty="false">
<Equal>Smith</Equal>
</ComparisonType>
</ContactAttribute>
<ContactAttribute>
<Name>JobTitle</Name>
<ComparisonType CompareOperator="And" IsEmpty="false">
<Equal>Sales Administrator</Equal>
</ComparisonType>
</ContactAttribute>
</DisplayNameValues>
<Page>
<PageNumber>1</PageNumber>
<PageSize>1000</PageSize>
</Page>
</Where>
</GetContactsByPageRequest>
]]>
</tem:XML>
</tem:GetContactsByPage>
</s:Body>
</s:Envelope>
Sample response XML:
SOAP API Guide Methods
SOAP API Guide 57
Get contacts by page where a field is greater than a value (DisplayNameValue):
This would retrieve all of the contacts associated with Sub Account ID 2 using a
PageSize of 1000, where Age is greater than 65. NB Age would need to be a field
that you have added to your contact custom fields via Field Manager.
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetContactsByPageResponse xmlns="http://tempuri.org/">
<![CDATA[
<GetContactsByPage>
<Contacts>
<ContactBasicDetails>
<RowNumber>1</RowNumber>
<Email>[email protected]</Email>
<Salutation>Mr</Salutation>
<Firstname>John</Firstname>
<Lastname>Smith</Lastname>
<Company>Smith & Sons Ltd</Company>
<Telephone>01234567890</Telephone>
<Urn>UrnFieldValue</Urn>
<ContactResponseAttributes>
<ContactResponseAttribute>
<Name>JobTitle</Name>
<Value>Sales Administrator</Value>
</ContactResponseAttribute>
</ContactResponseAttributes>
</ContactBasicDetails>
</Contacts>
</GetContactsByPage>
]]>
</GetContactsByPageResponse>
</s:Body>
</s:Envelope>
SOAP API Guide Methods
SOAP API Guide 58
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetContactsByPage>
<tem:XML>
<![CDATA[
<GetContactsByPageRequest
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetContactsByPageRequest.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Select>
<Name>Salutation</Name>
<Name>Firstname</Name>
<Name>Lastname</Name>
<Name>Age</Name>
</Select>
<Where>
<AccountID>2</AccountID>
<DisplayNameValues>
<ContactAttribute>
<Name>Age</Name>
<ComparisonType CompareOperator="And" IsEmpty="false">
<GreaterThan>65</GreaterThan>
</ComparisonType>
</ContactAttribute>
</DisplayNameValues>
<Page>
<PageNumber>1</PageNumber>
<PageSize>1000</PageSize>
</Page>
</Where>
</GetContactsByPageRequest>
]]>
</tem:XML>
</tem:GetContactsByPage>
</s:Body>
</s:Envelope>
SOAP API Guide Methods
SOAP API Guide 59
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetContactsByPageResponse xmlns="http://tempuri.org/">
<![CDATA[
<GetContactsByPage>
<Contacts>
<ContactBasicDetails>
<RowNumber>1</RowNumber>
<Email>[email protected]</Email>
<Salutation>Mr</Salutation>
<Firstname>John</Firstname>
<Lastname>Smith</Lastname>
<ContactResponseAttributes>
<ContactResponseAttribute>
<Name>Age</Name>
<Value>72</Value>
</ContactResponseAttribute>
</ContactResponseAttributes>
</ContactBasicDetails>
<ContactBasicDetails>
Next record values, repeated for each row in resultset.
</ContactBasicDetails>
</Contacts>
</GetContactsByPage>
]]>
</GetContactsByPageResponse>
</s:Body>
</s:Envelope>
Get contacts by page where a Date or DateTime field has an Anniversary (IsAnniversary):
This would retrieve all of the contacts associated with Sub Account 2 using a
PageSize of 1000, where today is their birthday. NB DateOfBirth would need to
be a field that you have added to your contact custom fields via Field Manager.
SOAP API Guide Methods
SOAP API Guide 60
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetContactsByPage>
<tem:XML>
<![CDATA[
<GetContactsByPageRequest
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetContactsByPageRequest.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Select>
<Name>Salutation</Name>
<Name>Firstname</Name>
<Name>Lastname</Name>
<Name>DateOfBirth</Name>
</Select>
<Where>
<AccountID>2</AccountID>
<DisplayNameValues>
<ContactAttribute>
<Name>DateOfBirth</Name>
<ComparisonType CompareOperator="And" IsEmpty="false">
<IsAnniversary>true</IsAnniversary>
</ComparisonType>
</ContactAttribute>
</DisplayNameValues>
<Page>
<PageNumber>1</PageNumber>
<PageSize>1000</PageSize>
</Page>
</Where>
</GetContactsByPageRequest>
]]>
</tem:XML>
</tem:GetContactsByPage>
</s:Body>
</s:Envelope>
SOAP API Guide Methods
SOAP API Guide 61
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetContactsByPageResponse xmlns="http://tempuri.org/">
<![CDATA[
<GetContactsByPage>
<Contacts>
<ContactBasicDetails>
<RowNumber>1</RowNumber>
<Email>[email protected]</Email>
<Salutation>Mr</Salutation>
<Firstname>John</Firstname>
<Lastname>Smith</Lastname>
<ContactResponseAttributes>
<ContactResponseAttribute>
<Name>DateOfBirth</Name>
<Value>14/08/1974 00:00:00</Value>
</ContactResponseAttribute>
</ContactResponseAttributes>
</ContactBasicDetails>
<ContactBasicDetails>
Next record values, repeated for each row in resultset.
</ContactBasicDetails>
</Contacts>
</GetContactsByPage>
]]>
</GetContactsByPageResponse>
</s:Body>
</s:Envelope>
GetContactsCount This method is used to retrieve the number of Contacts matching the Where criteria
passed in.
Parameter Data Type Mandatory Description
Where ComplexType Y The Where parameter matches that used in
GetContactsByPage request. (see Where
for details)
Page is ignored, so you can use exactly the
same Where parameter as you would for
your GetContactsByPage request
SOAP API Guide Methods
SOAP API Guide 62
GetContactsCount (Page):
This would retrieve the number of contacts associated with Sub Account ID 2.
SOAP API Guide Methods
SOAP API Guide 63
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetContactsCount>
<tem:XML>
<![CDATA[
<GetContactsCountRequest
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetContactsCountRequest.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Where>
<AccountID>2</AccountID>
</Where>
</GetContactsCountRequest>
]]>
</tem:XML>
</tem:GetContactsCount>
</s:Body>
</s:Envelope>
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetContactsCountResponse xmlns="http://tempuri.org/">
<![CDATA[
<GetContactsCount>
<Count>395679</Count>
</GetContactsCount>
]]>
</GetContactsCountResponse>
</s:Body>
</s:Envelope>
GetEshotDetails This method is used to retrieve the contact and link details based on the
DetailType and Type filter criteria.
SMS send details cannot be returned using this method.
SOAP API Guide Methods
SOAP API Guide 64
Parameter Data Type Mandatory Description
DetailType Enumeration Y SentTo, SoftBounce, HardBounce,
Read, Unsubscribers, Clicks, Links,
Forward
Type Enumeration Y All*
Retrieve details of All the e-shots
Filter*
Retrieve the details of the e-shot based on
the Filter string passed in the 'FilterString'
tag
FilterString String N Email, ReportName, Firstname,
Lastname, Subject, Salutation,
Company
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetEshotDetails>
<tem:RqXML>
<![CDATA[
<GetEshotDetailsRq xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetEshotDetailsRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<DetailType>SentTo</DetailType>
<Type>Filter</Type>
<FilterString>useractioneventdate between '20131201' and
'20140128'</FilterString>
</Params>
</GetEshotDetailsRq>
]]>
</tem:RqXML>
</tem:GetEshotDetails>
</s:Body>
</s:Envelope>
SOAP API Guide Methods
SOAP API Guide 65
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetEshotDetailsResponse xmlns="http://tempuri.org/">
<GetEshotDetailsResult>
<![CDATA[
<GetEshotDetailsRs>
<Contact>
<AutoID>769831</AutoID>
<EshotReportName>Furniture_2013.2</EshotReportName>
<Email>[email protected]</Email>
<Salutation></Salutation>
<Firstname></Firstname>
<Lastname></Lastname>
<Company></Company>
<Telephone></Telephone>
<URN></URN>
</Contact>
<Contact>
<AutoID>965</AutoID>
<EshotReportName>Furniture_2013.1</EshotReportName>
<Email>[email protected]</Email>
<Salutation>Mr</Salutation>
<Firstname>G N</Firstname>
<Lastname>Walnut</Lastname>
<Company>Discount Furniture</Company>
<Telephone>0208999999</Telephone>
<URN></URN>
</Contact>
</GetEshotDetailsRs>
]]>
</GetEshotDetailsResult>
</GetEshotDetailsResponse>
</s:Body>
</s:Envelope>
e-shot details can be filtered by passing the user action date to the filter string. For
example, if we pass the filter as shown below we would retrieve the list of contacts
who read the e-shot between specified dates.
The valid Date formats for <FilterString>useractioneventdate are:
yyyyMMdd
yyyy-MM-dd
yyyyMMdd HH:mm:ss
yyyy-MM-dd HH:mm:ss
SOAP API Guide Methods
SOAP API Guide 66
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetEshotDetails>
<tem:RqXML>
<![CDATA[
<GetEshotDetailsRq xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetEshotDetailsRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<DetailType>Read</DetailType>
<Type>Filter</Type>
<FilterString>useractioneventdate between '2013-12-01' and
'2014-01-28'</FilterString>
</Params>
</GetEshotDetailsRq>
]]>
</tem:RqXML>
</tem:GetEshotDetails>
</s:Body>
</s:Envelope>
Retrieving e-shots matching specified filter criteria (DetailType):
Filter by SentTo
The example below will return a list of contacts that have been sent e-shots matching
the filter criteria specified.
SOAP API Guide Methods
SOAP API Guide 67
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetEshotDetails>
<tem:RqXML>
<![CDATA[
<GetEshotDetailsRq xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetEshotDetailsRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<DetailType>SentTo</DetailType>
<Type>Filter</Type>
<FilterString>useractioneventdate between '20131201' and
'20140128'</FilterString>
</Params>
</GetEshotDetailsRq>
]]>
</tem:RqXML>
</tem:GetEshotDetails>
</s:Body>
</s:Envelope>
Filter by Read
The example below will return a list of contacts who have displayed e-shots matching
the filter criteria specified.
SOAP API Guide Methods
SOAP API Guide 68
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetEshotDetails>
<tem:RqXML>
<![CDATA[
<GetEshotDetailsRq xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetEshotDetailsRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<DetailType>Read</DetailType>
<Type>Filter</Type>
<FilterString>subject='this is the subject'</FilterString> </Params>
</GetEshotDetailsRq>
]]>
</tem:RqXML>
</tem:GetEshotDetails>
</s:Body>
</s:Envelope>
Filter by Clicks
The example below will result in a list of contacts who have clicked on monitored
links within e-shots matching the filter criteria specified.
SOAP API Guide Methods
SOAP API Guide 69
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetEshotDetails>
<tem:RqXML>
<![CDATA[
<GetEshotDetailsRq xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetEshotDetailsRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<DetailType>Clicks</DetailType>
<Type>Filter</Type>
<FilterString>subject='this is the subject'</FilterString>
</Params>
</GetEshotDetailsRq>
]]>
</tem:RqXML>
</tem:GetEshotDetails>
</s:Body>
</s:Envelope>
Filter by Unsubscribers
The example below will return a list of contacts who have unsubscribed from e-
shots matching the filter criteria specified.
SOAP API Guide Methods
SOAP API Guide 70
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetEshotDetails>
<tem:RqXML>
<![CDATA[
<GetEshotDetailsRq xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetEshotDetailsRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<DetailType>Unsubscribers</DetailType>
<Type>Filter</Type>
<FilterString>subject='this is the subject'</FilterString>
</Params>
</GetEshotDetailsRq>
]]>
</tem:RqXML>
</tem:GetEshotDetails>
</s:Body>
</s:Envelope>
Filter by Links
The example below will return a list of contacts, along with the web link and friendly
name for those who have been sent e-shots matching the filter criteria specified.
SOAP API Guide Methods
SOAP API Guide 71
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetEshotDetails>
<tem:RqXML>
<![CDATA[
<GetEshotDetailsRq xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetEshotDetailsRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<DetailType>Links</DetailType>
<Type>Filter</Type>
<FilterString>subject='this is the subject'</FilterString>
</Params>
</GetEshotDetailsRq>
]]>
</tem:RqXML>
</tem:GetEshotDetails>
</s:Body>
</s:Envelope>
SOAP API Guide Methods
SOAP API Guide 72
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetEshotDetailsResponse xmlns="http://tempuri.org/">
<GetEshotDetailsResult>
<![CDATA[
<GetEshotDetailsRs>
<Contact>
<AutoID>769831</AutoID>
<EshotReportName>Furniture_20132</EshotReportName>
<Email>[email protected]</Email>
<Salutation></Salutation>
<Firstname></Firstname>
<Lastname></Lastname>
<Company></Company>
<Telephone></Telephone>
<URN></URN>
<Link>http://www.test.co.uk?utm_source=eshot&
utm_medium=email&utm_campaign=1273</Link>
<FriendlyName>Test Link</FriendlyName>
</Contact>
</GetEshotDetailsRs>
]]>
</GetEshotDetailsResult>
</GetEshotDetailsResponse>
</s:Body>
</s:Envelope>
SOAP API Guide Methods
SOAP API Guide 73
Filter by Softbounce
The example below will return a list of softbounce contacts that have been sent e-
shots matching the filter criteria specified.
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetEshotDetails>
<tem:RqXML>
<![CDATA[
<GetEshotDetailsRq xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetEshotDetailsRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<DetailType>Softbounce</DetailType>
<Type>Filter</Type>
<FilterString>subject='this is the subject'</FilterString>
</Params>
</GetEshotDetailsRq>
]]>
</tem:RqXML>
</tem:GetEshotDetails>
</s:Body>
</s:Envelope>
Filter by Hardbounce
The example below will return a list of hardbounce contacts that have been sent e-
shots matching the filter criteria specified.
SOAP API Guide Methods
SOAP API Guide 74
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetEshotDetails>
<tem:RqXML>
<![CDATA[
<GetEshotDetailsRq xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetEshotDetailsRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<DetailType>Hardbounce</DetailType>
<Type>Filter</Type>
<FilterString>subject='this is the subject'</FilterString>
</Params>
</GetEshotDetailsRq>
]]>
</tem:RqXML>
</tem:GetEshotDetails>
</s:Body>
</s:Envelope>
Filter by Forward
The example below will result in a list of contacts that have been forwarded e-shots
matching the filter criteria specified.
SOAP API Guide Methods
SOAP API Guide 75
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetEshotDetails>
<tem:RqXML>
<![CDATA[
<GetEshotDetailsRq xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetEshotDetailsRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<DetailType>Forward</DetailType>
<Type>Filter</Type>
<FilterString>subject='this is the subject'</FilterString>
</Params>
</GetEshotDetailsRq>
]]>
</tem:RqXML>
</tem:GetEshotDetails>
</s:Body>
</s:Envelope>
GetEshotReports This method is used to retrieve the details of all contacts that performed particular
actions such as read, click, forward, etc. This can be filtered based on Campaign
Name, Email Subject Line or Action Date.
SMS send reports cannot be obtained using this method.
Parameter Data Type Mandatory Description
DetailType Ennumeration Y Contacts can be retrieved by
passing:
All – Retrieve all details of
actions (i.e. read, clicks,
forward, etc.) performed by
the contacts
Filter – Retrieve the
details of specific action
performed by the contacts
SOAP API Guide Methods
SOAP API Guide 76
based on the Filter string
passed in the
DetailTypeFilterString
tag
DetailTypeFilterString
(Used with
DetailType=Filter)
String N Softbounce
Hardbounce
Forward
SentTo
Read
Unsubscribers
Clicks
Links
Type Enumeration Y e-shots can be retrieved by
passing:
All – Retrieve details of All
the e-shots sends
Filter – Retrieve the
details of the e-shot sends
based on the Filter string
passed in the
FilterString tag
FilterString
(Used with Type=Filter)
String N ReportName – The name of
the Campaign that created
the e-shot send, e.g.
ReportName='My
Campaign'
Subject – The Subject line
of the sent Email, e.g.
Subject='My Subject
Line'
UserActionEventDate –
The Date the user
performed the action, e.g.
UserActionEventDate
between '2014-03-01'
and '2014-03-30'.
SOAP API Guide Methods
SOAP API Guide 77
Retrieve contact details
Filter All contact actions by matching subject text
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetEshotReports>
<tem:RqXML>
<![CDATA[
<GetEshotReportsRq
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetEshotReportsRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<DetailType>All</DetailType>
<Type>Filter</Type>
<FilterString>subject='this is the subject'</FilterString>
</Params>
</GetEshotReportsRq>
]]>
</tem:RqXML>
</tem:GetEshotReports>
</s:Body>
</s:Envelope>
SOAP API Guide Methods
SOAP API Guide 78
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetEshotReportsResponse xmlns="http://tempuri.org/">
<GetEshotReportsResult>
<![CDATA[
<GetEshotReportsRs>
<BounceLogContacts>
<Contact>
<AutoID>132676</AutoID>
<EshotReportName>1_NYC_ASC</EshotReportName>
<Email>[email protected]</Email>
<Salutation>Mr</Salutation>
<Firstname>James</Firstname>
<Lastname>Alexandra</Lastname>
<Company>Kerry Foods (Omagh)</Company>
<Telephone></Telephone>
<URN></URN>
</Contact>
</BounceLogContacts>
<ReadContacts>
<Contact>
<AutoID>132677</AutoID>
<EshotReportName>1_NYC_ASC</EshotReportName>
<Email>[email protected]</Email>
<Salutation>Mr</Salutation>
<Firstname>Paul</Firstname>
<Lastname>Simons</Lastname>
<Company>Kerry Foods (Omagh)</Company>
<Telephone></Telephone>
<URN></URN>
</Contact>
</ReadContacts>
<UnsubscribersContacts>
<Contact>
<AutoID>132678</AutoID>
<EshotReportName>1_NYC_ASC</EshotReportName>
<Email>[email protected]</Email>
<Salutation>Miss</Salutation>
<Firstname>Julia</Firstname>
<Lastname>Icansing</Lastname>
<Company>Songs are us</Company>
<Telephone></Telephone>
<URN></URN>
</Contact>
</UnsubscribersContacts>
<ClicksContacts>
<Contact>
<AutoID>132679</AutoID>
<EshotReportName>1_NYC_ASC</EshotReportName>
<Email>[email protected]</Email>
<Salutation>Mr</Salutation>
<Firstname>Huge</Firstname>
<Lastname>Engine</Lastname>
<Company>Drivers Union</Company>
<Telephone></Telephone>
<URN></URN>
</Contact>
</ClicksContacts>
<LinksContacts>
<Contact>
<AutoID>132680</AutoID>
SOAP API Guide Methods
SOAP API Guide 79
<EshotReportName>1_NYC_ASC</EshotReportName>
<Email>[email protected]</Email>
<Salutation>Ms</Salutation>
<Firstname>Jill</Firstname>
<Lastname>Sandwich</Lastname>
<Company>Kerry Foods (Omagh)</Company>
<Telephone></Telephone>
<URN></URN>
</Contact>
</LinksContacts>
<ForwardContacts>
<Contact>
<AutoID>132681</AutoID>
<EshotReportName>1_NYC_ASC</EshotReportName>
<Email>[email protected]</Email>
<Salutation>Mr</Salutation>
<Firstname>Jeremy</Firstname>
<Lastname>Lunch</Lastname>
<Company>Kerry Foods (Omagh)</Company>
<Telephone></Telephone>
<URN></URN>
</Contact>
</ForwardContacts>
<SoftbounceContacts>
<Contact>
<AutoID>132682</AutoID>
<EshotReportName>1_NYC_ASC</EshotReportName>
<Email>[email protected]</Email>
<Salutation>Mrs</Salutation>
<Firstname>Jane</Firstname>
<Lastname>Hungry</Lastname>
<Company>Kerry Foods (Omagh)</Company>
<Telephone></Telephone>
<URN></URN>
</Contact>
</SoftbounceContacts>
<HardbounceContacts>
<Contact>
<AutoID>132683</AutoID>
<EshotReportName>1_NYC_ASC</EshotReportName>
<Email>[email protected]</Email>
<Salutation>Ms</Salutation>
<Firstname>Jessica</Firstname>
<Lastname>Rabbit</Lastname>
<Company>Cartoon Network</Company>
<Telephone></Telephone>
<URN></URN>
</Contact>
</HardbounceContacts>
</GetEshotReportsRs>
]]>
</GetEshotReportsResult>
</GetEshotReportsResponse>
</s:Body>
</s:Envelope>
Filter contact actions that are Read or Clicked by matching the Subject text
SOAP API Guide Methods
SOAP API Guide 80
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetEshotReports>
<tem:RqXML>
<![CDATA[
<GetEshotReportsRq
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetEshotReportsRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<DetailType>All</DetailType>
<DetailTypeFilterString>Read,Clicks</DetailTypeFilterString>
<Type>Filter</Type>
<FilterString>subject='this is the subject'</FilterString>
</Params>
</GetEshotReportsRq>
]]>
</tem:RqXML>
</tem:GetEshotReports>
</s:Body>
</s:Envelope>
SOAP API Guide Methods
SOAP API Guide 81
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetEshotReportsResponse xmlns="http://tempuri.org/">
<GetEshotReportsResult>
<![CDATA[
<GetEshotReportsRs>
<ReadContacts>
<Contact>
<AutoID>132677</AutoID>
<EshotReportName>1_NYC_ASC</EshotReportName>
<Email>[email protected]</Email>
<Salutation>Mr</Salutation>
<Firstname>Paul</Firstname>
<Lastname>Simons</Lastname>
<Company>Kerry Foods (Omagh)</Company>
<Telephone></Telephone>
<URN></URN>
</Contact>
</ReadContacts>
<ClicksContacts>
<Contact>
<AutoID>132679</AutoID>
<EshotReportName>1_NYC_ASC</EshotReportName>
<Email>[email protected]</Email>
<Salutation>Ms</Salutation>
<Firstname>Huge</Firstname>
<Lastname>Engine</Lastname>
<Company>Drivers Union</Company>
<Telephone></Telephone>
<URN></URN>
</Contact>
<Contact>
<AutoID>132680</AutoID>
<EshotReportName>1_NYC_ASC</EshotReportName>
<Email>eshot.test. [email protected]</Email>
<Salutation>Ms</Salutation>
<Firstname>Speedy</Firstname>
<Lastname>Gonzalez</Lastname>
<Company>Drivers Union</Company>
<Telephone></Telephone>
<URN></URN>
</Contact>
</ClicksContacts>
</GetEshotReportsRs>
]]>
</GetEshotReportsResult>
</GetEshotReportsResponse>
</s:Body>
</s:Envelope>
GetEshots This method is used to retrieve all the e-shot sends. A simple filter can be specified
and the result columns can be selected.
SOAP API Guide Methods
SOAP API Guide 82
This method does not return SMS Sends.
Parameter Data Type Mandatory Description
FilterString Enumeration N Name, Subject, SentDate,
CreatedDate, FromEmail &
FromName
Type Enumeration Y All – Returns all e-shots (excluding
archived)
Filter – (used in conjunction with
the FilterString)
SelectFields Enumeration N Fields to be returned as part of the
query:
Name
Subject
SentDate
CreatedDate
HTMLSource (HTML of a campaign)
TextSource (TEXT of a campaign)
TotalSent
FromEmail
FromName
ReplyTo
DateWhentoSend
Status (Waiting, InProgress,
OnHold, Sent)
Type (Message creation type used)
ConfirmedUser
CreatedUser
By default the API will retrieve all the
above details from e-shot
SOAP API Guide Methods
SOAP API Guide 83
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetEshots>
<tem:RqXML>
<![CDATA[
<GetEshotsRq
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetEshotsRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<Type>All</Type>
</Params>
</GetEshotsRq>
]]>
</tem:RqXML>
</tem:GetEshots>
</s:Body>
</s:Envelope>
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetEshotsResponse xmlns="http://tempuri.org/">
<GetEshotsResult>
<![CDATA[
<GetEshotsRs>
<Eshot>
<AutoID>1085</AutoID>
<Name>Retailers_follow_up_2014</Name>
<SentDate>2014-01-08T12:19:25.013</SentDate>
<CreatedDate>2014-01-08T12:18:21.377</CreatedDate>
<Subject>Now’s the Time to Make Your Marketing
Meaningful</Subject>
<HTMLSource>
<html>
<head>
<meta content="text/html; charset=iso-8859-1" http-
equiv="content-type">
<meta name="generator" content="mshtml
8.00.6001.18975">
<style>
body {font-family:arial,verdana,83eneva83ca,83eneva,sans-
serif;color:#000000;font-size:12px;}
</style>
SOAP API Guide Methods
SOAP API Guide 84
</head>
<body bgcolor="#ffffff">HTML BODY CONTENT GOES HERE
</body>
</html>
</HTMLSource>
<TextSource>TEXT BODY CONTENT GOES HERE</TextSource>
<TotalSent>46</TotalSent>
<FromEmail>[email protected]</FromEmail>
<FromName>Joe Blogs – Forfront.net</FromName>
<ReplyTo>[email protected]</ReplyTo>
<DateWhentoSend>2014-01-14T10:30:00</DateWhentoSend>
<Status>Sent</Status>
<Type>HTML</Type>
<ConfirmedUser>Sonia Hernandez</ConfirmedUser>
<CreatedUser>Sonia Hernandez</CreatedUser>
</Eshot>
</GetEshotsRs>
]]>
</GetEshotsResult>
</GetEshotsResponse>
</s:Body>
</s:Envelope>
Retrieving e-shots matching specified filter criteria (FilterString):
Filter by subject
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetEshots>
<tem:RqXML>
<![CDATA[
<GetEshotsRq
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetEshotsRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<Type>Filter</Type>
<FilterString>subject='test'</FilterString>
</Params>
</GetEshotsRq>
]]>
SOAP API Guide Methods
SOAP API Guide 85
</tem:RqXML>
</tem:GetEshots>
</s:Body>
</s:Envelope>
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetEshotsResponse xmlns="http://tempuri.org/">
<GetEshotsResult>
<![CDATA[
<GetEshotsRs>
<Eshot>
<AutoID>1085</AutoID>
<Name>Retailers_follow_up_2014</Name>
<SentDate>2014-01-08T12:19:25.013</SentDate>
<CreatedDate>2014-01-08T12:18:21.377</CreatedDate>
<Subject>test</Subject>
<HTMLSource>
<html>
<head>
<meta content="text/html; charset=iso-8859-1" http-
equiv="content-type">
<meta name="generator" content="mshtml
8.00.6001.18975">
<style>
body {font-family:arial,verdana,85eneva85ca,85eneva,sans-
serif;color:#000000;font-size:12px;}
</style>
</head>
<body bgcolor="#ffffff">HTML BODY CONTENT GOES HERE
</body>
</html>
</HTMLSource>
<TextSource>TEXT BODY CONTENT GOES HERE</TextSource>
<TotalSent>46</TotalSent>
<FromEmail>[email protected]</FromEmail>
<FromName>Joe Blogs – Forfront.net</FromName>
<ReplyTo>[email protected]</ReplyTo>
<DateWhentoSend>2014-01-14T10:30:00</DateWhentoSend>
<Status>Sent</Status>
<Type>HTML</Type>
<ConfirmedUser>Sonia Hernandez</ConfirmedUser>
<CreatedUser>Sonia Hernandez</CreatedUser>
</Eshot>
</GetEshotsRs>
]]>
</GetEshotsResult>
</GetEshotsResponse>
</s:Body>
</s:Envelope>
The e-shot fields returned can be customised by using SelectFields element. You
can specify one or more fields within the SelectFields tag separated by a comma.
SOAP API Guide Methods
SOAP API Guide 86
Filter by SelectFields
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<s:Header/>
<s:Body>
<tem:GetEshots>
<tem:RqXML>
<![CDATA[
<GetEshotsRq
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetEshotsRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<Type>Filter</Type>
<FilterString>subject='test'</FilterString>
<SelectFields>Name</SelectFields>
</Params>
</GetEshotsRq>
]]>
</tem:RqXML>
</tem:GetEshots>
</s:Body>
</s:Envelope>
SOAP API Guide Methods
SOAP API Guide 87
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetEshotsResponse xmlns="http://tempuri.org/">
<GetEshotsResult>
<![CDATA[
<GetEshotsRs>
<Eshot>
<AutoID>1085</AutoID>
<Name>Retailers_follow_up_2014</Name>
</Eshot>
</GetEshotsRs>
]]>
</GetEshotsResult>
</GetEshotsResponse>
</s:Body>
</s:Envelope>
GetFileUploadStatus This method is used to get the status and additional information of the file upload.
Parameter Data Type Mandatory Description
Token String Y This is a unique GUID that is returned as part of a
call to the FileUploadSubmitContact method
Possible file upload status types:
File uploaded to the server successfully
File upload contacts are partially imported as the file contains some invalid records
File upload contacts are partially imported as the subaccount limit exceeded the
maximum number of contacts
File upload contacts are partially imported as file contains some invalid records and
the subaccount limit exceeded the maximum number of contacts
File upload contacts are imported successfully
File header column names are not valid
File contents are not valid
File upload contacts failed to be imported
File upload error
SOAP API Guide Methods
SOAP API Guide 88
Sample request XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetFileUploadStatus xmlns="http://tempuri.org/">
<requestXML>
<![CDATA[
<GetFileUploadStatusRq xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetFileUploadStatusRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<Token>e3e657b2-cc7f-45d6-9281-0231d7ec98e8</Token>
</Params>
</GetFileUploadStatusRq>
]]>
</requestXML>
</GetFileUploadStatus>
</s:Body>
</s:Envelope>
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetFileUploadStatusResponse xmlns="http://tempuri.org/">
<GetFileUploadStatusResult>
<![CDATA[
<GetFileUploadStatusRs>
<Params>
<Token>e3e657b2-cc7f-45d6-9281-0231d7ec98e8</Token>
<Status>File upload contacts are imported
successfully</Status>
<AdditionalInformation>All contacts mentioned in the file are
imported successfully</AdditionalInformation>
<ErrorFileName></ErrorFileName>
<ErrorFileUrl></ErrorFileUrl>
</Params>
</GetFileUploadStatusRs>
]]>
</GetFileUploadStatusResult>
</GetFileUploadStatusResponse>
</s:Body>
</s:Envelope>
SOAP API Guide Methods
SOAP API Guide 89
GetGroups This method is used to retrieve the details of the group such as Name, Description,
ParentGroupId, etc. based on the type filter criteria.
Parameter Data Type Mandatory Description
Type Enumeration Y Groups can be retrieved by passing:
All – Retrieves All the groups
Filter – Retrieves the groups based
on the Filter string passed in the
FilterString tag
Contact – Retrieves the groups based
on the Contact email passed in the
FilterString tag
FilterString String Required
when the
Type has a
value other
than All
specified
Name, Description, AutoID
SOAP API Guide Methods
SOAP API Guide 90
Retrieve all the groups:
Sample request XML:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<soapenv:Header/>
<soapenv:Body>
<tem:GetGroups>
<tem:RqXML>
<![CDATA[
<GetGroupsRq xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetGroupsRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<Type>All</Type>
</Params>
</GetGroupsRq>
]]>
</tem:RqXML>
</tem:GetGroups>
</soapenv:Body>
</soapenv:Envelope>
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetGroupsResponse xmlns="http://tempuri.org/">
<GetGroupsResult>
<![CDATA[
<GetGroupsRs>
<Group>
<AutoID>53</AutoID>
<Name>ADS – Recruitment</Name>
<Description></Description>
<ParentGroupID></ParentGroupID>
<IsTest>0</IsTest>
</Group>
<Group>
<AutoID>54</AutoID>
<Name>ADS – Menswear – Retail</Name>
<Description></Description>
<ParentGroupID></ParentGroupID>
<IsTest>0</IsTest>
</Group>
</GetGroupsRs>
SOAP API Guide Methods
SOAP API Guide 91
]]>
</GetGroupsResult>
</GetGroupsResponse>
</s:Body>
</s:Envelope>
Retrieve the groups matching the group name specified (name):
Sample request XML:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<soapenv:Header/>
<soapenv:Body>
<tem:GetGroups>
<tem:RqXML>
<![CDATA[
<GetGroupsRq xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetGroupsRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<Type>Filter</Type>
<FilterString>Name='test group'</FilterString>
</Params>
</GetGroupsRq>
]]>
</tem:RqXML>
</tem:GetGroups>
</soapenv:Body>
</soapenv:Envelope>
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetGroupsResponse xmlns="http://tempuri.org/">
<GetGroupsResult>
<![CDATA[
<GetGroupsRs>
<Group>
SOAP API Guide Methods
SOAP API Guide 92
<AutoID>14</AutoID>
<Name>test group</Name>
<Description></Description>
<ParentGroupID></ParentGroupID>
<IsTest>1</IsTest>
</Group>
</GetGroupsRs>
]]>
</GetGroupsResult>
</GetGroupsResponse>
</s:Body>
</s:Envelope>
Retrieve the groups containing the contact with the email address specified (email):
Sample request XML:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<soapenv:Header/>
<soapenv:Body>
<tem:GetGroups>
<tem:RqXML>
<![CDATA[
<GetGroupsRq xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetGroupsRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<Type>Contact</Type>
<FilterString>[email protected]</FilterString>
</Params>
</GetGroupsRq>
]]>
</tem:RqXML>
</tem:GetGroups>
</soapenv:Body>
</soapenv:Envelope>
Sample response XML:
SOAP API Guide Methods
SOAP API Guide 93
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetGroupsResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Responses/GetGroupsRs.xsd">
<GetGroupsResult>
<![CDATA[
<GetGroupsRs>
<Group>
<AutoID>14</AutoID>
<Name>test group</Name>
<Description></Description>
<ParentGroupID></ParentGroupID>
<IsTest>1</IsTest>
</Group>
</GetGroupsRs>
]]>
</GetGroupsResult>
</GetGroupsResponse>
</s:Body>
</s:Envelope>
GetIdentities This method returns a list of defined “from” and “reply email address”.
An email identity must be specified when a message is created, to enable recipients
of the email to reply, as well as see from whom the email came.
Parameter Data Type Mandatory Description
No parameters for this method call
SOAP API Guide Methods
SOAP API Guide 94
Sample request XML:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<soapenv:Header/>
<soapenv:Body>
<tem:GetIdentities>
<tem:input>
<![CDATA[
<GetIdentitiesRequest
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetIdentitiesRequest.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
</GetIdentitiesRequest>
]]>
</tem:input>
</tem:GetIdentities>
</soapenv:Body>
</soapenv:Envelope>
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetIdentitiesResponse xmlns="http://tempuri.org/">
<GetIdentitiesResult>
<![CDATA[
<GetIdentitiesResponse
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Identities>
<Identity>
<FromEmail>[email protected]</FromEmail>
<FromName>Your company name</FromName>
<ID>18</ID>
<Name>Your company name</Name>
<ReplyEmail>[email protected]</ReplyEmail>
</Identity>
</Identities>
</GetIdentitiesResponse>
]]>
</GetIdentitiesResult>
</GetIdentitiesResponse>
</s:Body>
</s:Envelope>
SOAP API Guide Methods
SOAP API Guide 95
GetMonitoredLinksSentRecipientFilter This method returns monitored link information for the specified filter criteria.
Monitored link information can only be obtained for email messages using this
method.
Parameter Data Type Mandatory Description
CampaignIDs Integer Array Y A list of e-shot send IDs. NOTE: The
name of this parameter is misleading,
it does not represent campaigns as
found in the Campaigns section of the
web site. It represents the e-shot
sends that are produced by
campaigns. In the case of Automated
Series and Recurrent campaigns there
may be more than one e-shot send
per campaign. The name of this
parameter has been retained for
backwards compatibility.
ClickType Enumeration Y Either, Clicked, NotClicked
IncludeArchive Boolean Y Boolean (true or false)
IsMonitored Boolean Y Boolean (true or false)
DestinationUrl String N Destination URL
FriendlyName String N Friendly name associated with a URL
IsHtml Boolean N Boolean (true or false)
NOTE: Execute the GetCampaignByStatus or
GetCampaignsSentRecipientFilter methods to retrieve the campaign IDs
(EshotID)
The example below searches for all clicked HTML monitored links for an e-shot
send with ID “1” or “2”, including archived campaigns:
SOAP API Guide Methods
SOAP API Guide 96
Sample request XML:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<soapenv:Header/>
<soapenv:Body>
<tem:GetMonitoredLinksSentRecipientFilter>
<tem:input>
<![CDATA[
<GetMonitoredLinksSentRecipientFilterRequest
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetMonitoredLinksSentRecipientFilter
Request.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<CampaignIDs>
<ID>1</ID>
<ID>2</ID>
</CampaignIDs>
<ClickType>Clicked</ClickType>
<IncludeArchive>1</IncludeArchive>
<IsMonitored>1</IsMonitored>
<IsHtml>true</IsHtml>
</GetMonitoredLinksSentRecipientFilterRequest>
]]>
</tem:input>
</tem:GetMonitoredLinksSentRecipientFilter>
</soapenv:Body>
</soapenv:Envelope>
SOAP API Guide Methods
SOAP API Guide 97
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetMonitoredLinksSentRecipientFilterResponse
xmlns="http://tempuri.org/">
<GetMonitoredLinksSentRecipientFilterResult>
<![CDATA[
<GetMonitoredLinksSentRecipientFilterCriteriaResponse
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<MonitorLinks>
<MonitoredLinksSentRecipientFilterCriteria>
<CampaignID>1</CampaignID>
<CampaignReportName>testing 17 Jan</CampaignReportName>
<CampaignSentDate>2014-01-17T11:07:14.31</CampaignSentDate>
<CampaignSubjectLine>testing 17 Jan</CampaignSubjectLine>
<ClickableLinkID>26908</ClickableLinkID>
<DestinationUrl>http://www.e-
shot.net?utm_source=eshot&utm_medium=email&utm_campaign=testing
17 Jan</DestinationUrl>
<FriendlyName />
<IsArchived>false</IsArchived>
<IsMonitored>true</IsMonitored>
</MonitoredLinksSentRecipientFilterCriteria>
</MonitorLinks>
</GetMonitoredLinksSentRecipientFilterCriteriaResponse>
]]>
</GetMonitoredLinksSentRecipientFilterResult>
</GetMonitoredLinksSentRecipientFilterResponse>
</s:Body>
</s:Envelope>
To retrieve information for more than one e-shot send, please specify a list of ID
elements with appropriate e-shot send ID values.
Example:
<CampaignIDs>
<ID>1</ID>
<ID>2</ID>
<ID>3</ID>
</CampaignIDs>
SOAP API Guide Methods
SOAP API Guide 98
GetReadyToSendMessages This method returns draft messages that are fully constructed and ‘ready for
sending’. A message is considered to be ‘ready for sending’ when there are no
missing images, the links and images have been validated and all steps of the
message construction process completed.
Messages that are ‘ready for sending’ are represented in the Design Studio with a tick
in the ‘is ready to send’ column of the displayed table.
This method does not return SMS Messages that are ready to send.
Parameter Data Type Mandatory Description
ConstructionType Enumeration Y TemplateWizard – Messages
constructed using the template
wizard
HtmlEditor – Messages
constructed using the HTML
editor
HTMLUpload – Messages
uploaded into the system using
the HTML upload facility
PlainText – Messages
constructed using the plain text
editor
DynamicHtmlUpload –
Messages uploaded into the
system from a URL (typically
unattended)
DragAndDrop – Messages
constructed using the Drag &
Drop editor
Name String N Name of the message (draft
campaign)
Name/SearchType Enumeration Required only
if Name/Text
is specified
Exact – If the message Name is
an exact match for the specified
text
Contains – If the message Name
contains the specified text
StartsWith – If the message
Name starts with the specified
SOAP API Guide Methods
SOAP API Guide 99
text
EndsWith – If the message Name
ends with the specified text
Name/Text String N Text to search with by
SearchType
SubjectLine Complex
Type
N
SubjectLine/
SearchType
Enumeration Required only
if
SubjectLine/
Text is
specified
Exact – If the message Subject
line is an exact match for the
specified text
Contains – If the message
Subject line contains the
specified text
StartsWith – If the message
Subject line starts with the
specified text
EndsWith – If the message
Subject line ends with the
specified text
SubjectLine/
Text
String Text to search with by
SearchType
SOAP API Guide Methods
SOAP API Guide 100
Sample request XML:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<soapenv:Header/>
<soapenv:Body>
<tem:GetReadyToSendMessages>
<tem:input>
<![CDATA[
<GetReadyToSendMessagesRequest
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/GetReadyToSendMessagesRequest.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<ConstructionType>HtmlEditor</ConstructionType>
<Name>
<SearchType>Contains</SearchType>
<Text>Marketing</Text>
</Name>
<SubjectLine>
<SearchType>Contains</SearchType>
<Text>Harumble</Text>
</SubjectLine>
</GetReadyToSendMessagesRequest>
]]>
</tem:input>
</tem:GetReadyToSendMessages>
</soapenv:Body>
</soapenv:Envelope>
The above sample request will show all the messages which have a
ConstructionType of HtmlEditor with a message name containing “Marketing”
and subject line containing “Harumble” which are ready for sending.
SOAP API Guide Methods
SOAP API Guide 101
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetReadyToSendMessagesResponse xmlns="http://tempuri.org/">
<GetReadyToSendMessagesResult>
<![CDATA[
<GetReadyToSendMessagesResponse
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Messages>
<ReadyToSendCampaignDraft>
<ID>4</ID>
<MessageType>HtmlEditor</MessageType>
<Name>Marketing</Name>
<Subject>This is a test…Harumble!</Subject>
</ReadyToSendCampaignDraft>
</Messages>
</GetReadyToSendMessagesResponse>
]]>
</GetReadyToSendMessagesResult>
</GetReadyToSendMessagesResponse>
</s:Body>
</s:Envelope>
QueueSimpleEshotSend This method is used to create a Single Send campaign and queue the campaign for
sending.
SMS Campaigns cannot be queued using this method.
Parameter Data Type Mandatory Description
CampaignDraftID Integer Y The ID of the Message that you wish
to send. For a list of Messages and
their IDs call the
GetReadyToSendMessages API.
SendDate DateTime Y (Must be a valid datetime in the
format yyyy-mm-dd)
SendSettings Complex Type Y
SendSettings/
ReportName
String Y Report name. This must be unique
within the systemSub Account the e-
shot is being created in.
SOAP API Guide Methods
SOAP API Guide 102
SendSettings/
EmailIdentityID
Integer Y The ID of the Identity to use for the
FromName, FromEmail and Reply To
addresses. A list of Identities and
their IDs call the GetIdentities API.
Note: It is not possible to use the ‘Manual’ identity for this field.
Groups/ID Integer Array N A list of IDs for the Groups that you
wish to send the Message to. Each ID
is listed in a separate <ID> sub
element of the main <Groups>
element. For a list of Groups and
their IDs call the GetGroups API.
Sample request XML:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<soapenv:Header/>
<soapenv:Body>
<tem:QueueSimpleEshotSend>
<tem:input>
<![CDATA[
<QueueSimpleEshotSendRequest
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/QueueSimpleEshotSendRequest.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<CampaignDraftID>994</CampaignDraftID>
<SendDate>2014-02-13T16:30:00</SendDate>
<Groups>
<ID>905</ID>
</Groups>
<SendSettings>
<ReportName>APITest</ReportName>
<EmailIdentityID>2</EmailIdentityID>
</SendSettings>
</QueueSimpleEshotSendRequest>]]>
</tem:input>
</tem:QueueSimpleEshotSend>
</soapenv:Body>
</soapenv:Envelope>
SOAP API Guide Methods
SOAP API Guide 103
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<QueueSimpleEshotSendResponse xmlns="http://tempuri.org/">
<QueueSimpleEshotSendResult>
<![CDATA[
<QueueEshotSendResponse
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<EshotID>1171</EshotID>
</QueueEshotSendResponse>
]]>
</QueueSimpleEshotSendResult>
</QueueSimpleEshotSendResponse>
</s:Body>
</s:Envelope>
ReQueueEshotSend This method can be called if you want to:
Change the send date of a queued e-shot send that is not in the middle of
sending.
Queue an e-shot send that has been placed on-hold.
SMS sends cannot be requeued using this method.
Parameter Data Type Mandatory Description
EshotID Integer Y e-shot send identifier. Dependencies
(API call to retrieve values for the
element): GetEshots
SendDate DateTime Y Datetime value (must not be in the
past)
An e-shot send can be placed on hold by calling SetQueuedEshotOnHold.
SOAP API Guide Methods
SOAP API Guide 104
Sample request XML:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<soapenv:Header/>
<soapenv:Body>
<tem:ReQueueEshotSend>
<tem:input>
<![CDATA[
<ReQueueEshotSendRequest
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/ReQueueEshotSendRequest.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<EshotID>1171</EshotID>
<SendDate>2015-12-02T14:54:00</SendDate>
</ReQueueEshotSendRequest>
]]>
</tem:input>
</tem:ReQueueEshotSend>
</soapenv:Body>
</soapenv:Envelope>
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<ReQueueEshotSendResponse xmlns="http://tempuri.org/">
<ReQueueEshotSendResult>
<![CDATA[
<ReQueueEshotResponse
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Status>CommandSuccessfullyIssued</Status>
</ReQueueEshotResponse>
]]>
</ReQueueEshotSendResult>
</ReQueueEshotSendResponse>
</s:Body>
</s:Envelope>
SetQueuedEshotOnHold
SOAP API Guide Methods
SOAP API Guide 105
This method can be called if you want to place a queued e-shot send on-hold. This
can then be re-queued at a later time using the RequeueEshotSend API method.
SMS sends cannot be put on hold using this method.
Parameter Data Type Mandatory Description
EshotID Integer Y e-shot send identifier
NOTE: Execute the API method QueueSimpleEshotSend to retrieve the EshotID.
Sample request XML:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<soapenv:Header/>
<soapenv:Body>
<tem:SetQueuedEshotOnHold>
<tem:input>
<![CDATA[
<SetQueuedEshotOnHoldRequest
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/SetQueuedEshotOnHoldRequest.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<EshotID>1095</EshotID>
</SetQueuedEshotOnHoldRequest>
]]>
</tem:input>
</tem:SetQueuedEshotOnHold>
</soapenv:Body>
</soapenv:Envelope>
SOAP API Guide Methods
SOAP API Guide 106
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<SetQueuedEshotOnHoldResponse xmlns="http://tempuri.org/">
<SetQueuedEshotOnHoldResult>
<![CDATA[
<SetQueueEshotOnHoldResponse
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Status>CommandSuccessfullyIssued</Status>
</SetQueueEshotOnHoldResponse>
]]>
</SetQueuedEshotOnHoldResult>
</SetQueuedEshotOnHoldResponse>
</s:Body>
</s:Envelope>
SubmitContact This method is used to create or update a contact in the e-shot system. The contact
will be added to the specified group/source. Custom fields can be passed with the
values.
The system will add the contact into the groups which are mentioned in the Groups
or GroupIDs tag. It will not remove them from other groups not specified by the
request that they also reside in.
NewEmail is an optional field. When you specify a service request, the System will
update the contact’s Email with NewEmail, ensuring that NewEmail is a valid email
address and that it doesn’t already exist in the system.
If any issues are encountered with any of the contacts submitted as part of a single
SubmitContact request, none of the submitted contacts will be uploaded into the
system and a response will be provided detailing the first issue encountered.
NOTE: Email and Source elements are mandatory parameters and should be
specified in that order, as dictated by the XSD and shown in the sample XML request
below. Also the third element must be Groups OR GroupIDs. You cannot specify
them both.
Parameter Data Type Mandatory Description
SOAP API Guide Methods
SOAP API Guide 107
Email String Y Email address
Source String Y Source name
Groups String N Comma separated list of Group
names
GroupIDs String N Comma separated list of Group
identifiers
NewEmail String N New email address
Salutation String N E.g. "Mr."
Firstname String N First name
Lastname String N Last name
Mobile String N Valid mobile number (see Mobile
Numbers)
<customfieldname> String N E.g. Postcode
The following example shows how to submit a contact and specify the groups by
name.
SOAP API Guide Methods
SOAP API Guide 108
Sample request XML:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<soapenv:Header/>
<soapenv:Body>
<tem:SubmitContact>
<tem:RqXML>
<![CDATA[
<SubmitContactRq
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/SubmitContactRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<Email>[email protected]</Email>
<Source>website</Source>
<Groups>MyGroup,MySecondGroup</Groups>
<NewEmail>[email protected]</NewEmail>
<LastName>Contact</LastName>
<Salutation>Mr</Salutation>
<FirstName>API Test</FirstName>
</Params>
</SubmitContactRq>
]]>
</tem:RqXML>
</tem:SubmitContact>
</soapenv:Body>
</soapenv:Envelope>
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<SubmitContactResponse xmlns="http://tempuri.org/">
<SubmitContactResult>
<![CDATA[
<SubmitContactRs>
<Params>
<Email>[email protected]</Email>
<Source>website</Source>
<Groups>MyGroup,MySecondGroup</Groups>
<NewEmail>[email protected]</NewEmail>
<LastName>Contact</LastName>
<Salutation>Mr</Salutation>
<FirstName>API Test</FirstName>
</Params>
</SubmitContactRs>
]]>
SOAP API Guide Methods
SOAP API Guide 109
</SubmitContactResult>
</SubmitContactResponse>
</s:Body>
</s:Envelope>
The following example shows how to submit a contact and specify the groups by id.
Sample request XML:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<soapenv:Header/>
<soapenv:Body>
<tem:SubmitContact>
<tem:RqXML>
<![CDATA[
<SubmitContactRq
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/SubmitContactRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<Email>[email protected]</Email>
<Source>website</Source>
<GroupIDs>1,2</GroupIDs>
<NewEmail>[email protected]</NewEmail>
<LastName>Contact</LastName>
<Salutation>Mr</Salutation>
<FirstName>API Test</FirstName>
</Params>
</SubmitContactRq>
]]>
</tem:RqXML>
</tem:SubmitContact>
</soapenv:Body>
</soapenv:Envelope>
SOAP API Guide Methods
SOAP API Guide 110
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<SubmitContactResponse xmlns="http://tempuri.org/">
<SubmitContactResult>
<![CDATA[
<SubmitContactRs>
<Params>
<Email>[email protected]</Email>
<Source>website</Source>
<Groups>Website</Groups>
<NewEmail>[email protected]</NewEmail>
<LastName>Contact</LastName>
<Salutation>Mr</Salutation>
<FirstName>API Tes</FirstName>
</Params>
</SubmitContactRs>
]]>
</SubmitContactResult>
</SubmitContactResponse>
</s:Body>
</s:Envelope>
SubmitGroup This method is used to create or update a Group in the e-shot system.
If you want to create a group then specify the Name parameter and optionally
Description, Display or DefaultChecked parameters.
If you want to update an existing group you can identify the group that you would
like to modify by specifying the Id or Name parameter. Please note that you should
only specify one of these and not both. If you specify both the Id and the Name
parameters the request will fail.
When updating a group you can now change the name of the group by specifying a
NewName parameter.
Parameter Data Type Mandatory Description
Name String Y Email address
Id Integer Y Source name
NewName String N Comma separated list of Group
names
SOAP API Guide Methods
SOAP API Guide 111
Description String N Comma separated list of Group
identifiers
Display Boolean N New email address
DefaultChecked Boolean N E.g. "Mr."
Updating an existing group or creating a new group by Name
Sample request XML:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<soapenv:Header/>
<soapenv:Body>
<tem:SubmitGroup>
<tem:requestXML>
<![CDATA[
<SubmitGroupRq
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/SubmitGroupRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<Name>Test Group 1</Name>
<Description>Created via the API</Description>
</Params>
</SubmitGroupRq>
]]>
</tem:requestXML>
</tem:SubmitGroup>
</soapenv:Body>
</soapenv:Envelope>
SOAP API Guide Methods
SOAP API Guide 112
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<SubmitGroupResponse xmlns="http://tempuri.org/">
<SubmitGroupResult>
<![CDATA[
<SubmitGroupRs>
<Params>
<Description>Created via the API</Description>
<Name>Test Group 1</Name>
</Params>
</SubmitGroupRs>
]]>
</SubmitGroupResult>
</SubmitGroupResponse>
</s:Body>
</s:Envelope>
SOAP API Guide Methods
SOAP API Guide 113
Updating a group name and description by Id
Sample request XML:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<soapenv:Header/>
<soapenv:Body>
<tem:SubmitGroup>
<tem:requestXML>
<![CDATA[
<SubmitGroupRq
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/SubmitGroupRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<Id>285</Id>
<NewName>New Group Name</NewName>
<Description>New Group Description</Description>
</Params>
</SubmitGroupRq>
]]>
</tem:requestXML>
</tem:SubmitGroup>
</soapenv:Body>
</soapenv:Envelope>
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<SubmitGroupResponse xmlns="http://tempuri.org/">
<SubmitGroupResult>
<![CDATA[
<SubmitGroupRs>
<Params>
<Name>New Group Name</Name>
<Description>New Group Description</Description>
</Params>
</SubmitGroupRs>
]]>
</SubmitGroupResult>
</SubmitGroupResponse>
</s:Body>
</s:Envelope>
SOAP API Guide Methods
SOAP API Guide 114
UnsubscribeContact This method is used to unsubscribe a contact from the database using the
mandatory Email parameter. If an unsubscribed contact is re-added to the system,
they will maintain a status of ‘unsubscribed’ and cannot be sent to.
Parameter Data Type Mandatory Description
Email String Y Valid email address
Sample request XML:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<soapenv:Header/>
<soapenv:Body>
<tem:UnsubscribeContact>
<tem:RqXML>
<![CDATA[
<UnsubscribeContactRq
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.e-
shot.net/Integration/Custom/Requests/UnsubscribeContactRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>2</auth:Subaccountid>
</auth:Login>
<Params>
<Email>[email protected]</Email>
</Params>
<Params>
<Email>[email protected]</Email>
</Params>
</UnsubscribeContactRq>
]]>
</tem:RqXML>
</tem:UnsubscribeContact>
</soapenv:Body>
</soapenv:Envelope>
SOAP API Guide Methods
SOAP API Guide 115
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<UnsubscribeContactResponse xmlns="http://tempuri.org/">
<UnsubscribeContactResult>
<![CDATA[
<UnsubscribeContactRs>
<Params>
<Email>[email protected]</Email>
</Params>
<Params>
<Email>[email protected]</Email>
</Params>
</UnsubscribeContactRs>]]>
</UnsubscribeContactResult>
</UnsubscribeContactResponse>
</s:Body>
</s:Envelope>
UnsubscribeSmsContact This method is used to unsubscribe a contact, for SMS Campaign Sends, from the
database using the Mobile parameter.
A contact’s mobile number is not unique so this method will unsubscribe all contacts
with the matching mobile number (see Mobile Numbers in the Appendix).
For each Mobile number supplied, the following response is returned
<Mobile Valid="true" ContactsUpdated="2">+447931775623</Mobile>
Valid states whether the mobile phone number was valid; the ContactsUpdated is
the number of contacts, with the supplied mobile number, have been affected.
Parameter Data Type Mandatory Description
Mobile String Y Valid mobile number
SOAP API Guide Methods
SOAP API Guide 116
Sample request XML:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="http://tempuri.org/">
<soapenv:Header/>
<soapenv:Body>
<tem:UnsubscribeSmsContact>
<tem:RqXML>
<![CDATA[<UnsubscribeSmsContactRq
xmlns:auth="Login.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://api.eshot.net/Integration/Custom/Re
quests/UnsubscribeSmsContactRq.xsd">
<auth:Login>
<auth:Username>user</auth:Username>
<auth:Password>pwd</auth:Password>
<auth:Email>[email protected]</auth:Email>
<auth:Subaccountid>5</auth:Subaccountid>
</auth:Login>
<Params>
<Mobile>+447931775623</Mobile>
</Params>
</UnsubscribeSmsContactRq>
]]>
</tem:RqXML>
</tem:UnsubscribeSmsContact>
</soapenv:Body>
</soapenv:Envelope>
Sample response XML:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<UnsubscribeSmsContactResponse xmlns="http://tempuri.org/">
<UnsubscribeSmsContactResult>
<![CDATA[
<UnsubscribeSmsContactRs>
<Params>
<Mobile Valid="true"
ContactsUpdated="2">+447931775623</Mobile>
</Params>
</UnsubscribeSmsContactRs>]]>
</UnsubscribeSmsContactResult>
</UnsubscribeSmsContactResponse>
</s:Body>
</s:Envelope>
SOAP API Guide Schemas
SOAP API Guide 117
Schemas
Requests/Responses These can be downloaded from the following URL:
http://api.e-shot.net/Help/definitions.html
SOAP API Guide Appendix
SOAP API Guide 118
Appendix
Login.xsd
<?xml version="1.0" encoding="utf-8" ?>
<xsd:schema xmlns:auth="Login.xsd" attributeFormDefault="unqualified"
elementFormDefault="qualified" targetNamespace="Login.xsd"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="Login">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Username" type="xsd:string" />
<xsd:element name="Password" type="xsd:string" />
<xsd:element name="Email" type="auth:EmailType" />
<xsd:element name="Subaccountid" minOccurs="0" type="xsd:integer"
nillable ="true" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:simpleType name="EmailType">
<xsd:restriction base="xsd:string">
<xsd:pattern value=" [A-Za-z0-9_]+([-+.'][A-Za-z0-9_]+)*@[A-Za-z0-
9_]+([-.][A-Za-z0-9_]+)*\.[A-Za-z0-9_]+([-.][A-Za-z0-9_]+)*" />
</xsd:restriction>
</xsd:simpleType>
</xsd:schema>
Service exceptions
Error code Description
1 XmlSuppliedIsInvalid
2 XmlSuppliedIsInvalid
3 IssueGettingDetails
4 IssueUpdatingDetails
5 IssueImportingDetails
6 BadRequest
7 CampaignFilterRulesRequired
SOAP API Guide Appendix
SOAP API Guide 119
8 CampaignNotFound
9 CampaignSendStateModification
10 MessageIdMissing
11 SendDateNotValid
12 EmailIdentityMissing
13 ReportNameMissing
14 MessageMissing
15 SentCountArgumentOutOfRange
16 RuleSetIdMissing
17 RuleSetMissing
18 RecipientFilterResultNotFound
19 RuleSetNameMissing
20 RuleSetNameNotUnique
21 GroupsNotSpecified
22 CampaignIdMissing
23 InvalidRuleTypeValueForRecipientFilterRule
24 ContactsNotFound
25 ContainerLimitReached
26 GroupDoesNotExist
27 UserAuthenticationFailed
28 InvalidCsvFieldValue
29 MissingParameter
30 NoEshotReportsFound
31 NoResultForSelectedInputParameters
SOAP API Guide Appendix
SOAP API Guide 120
32 MissingHtmlMessageContent
33 MessageNameNotUnique
34 MessageNameNotUnique
35 CouldNotValidateHtml
36 CampaignStructureNotValid
37 MessageNotFound
38 EshotIdNotFoundException
39 SendDateCannotBeInThePast
40 InvalidEmailAddress
41 AccountIdNotFound
42 ContactRecordNotFound
43 ContactColumnMappingRecordNotFound
44 DatabaseSqlException
45 DownloadFileToServerException
46 FileContentSteamNotValidException
47 FileHeaderNotValidException
48 FileUploadSchemaException
49 UserActionEventDateNotValidException
50 ToDateMustBeGreaterThanFromDateException
51 OutOfRangeException
56 ReportNameAlreadyExistsException
57 CanNotUseManualIdentityException
58 AccountExpiredException
59 AccountSuspendedException
SOAP API Guide Appendix
SOAP API Guide 121
Mobile Numbers Mobile numbers can be accepted in any standard format (with or without spaces):
07931 xxxxxx
0044 7931 xxxxxx
+44 7931 xxxxxx
If the 07931 xxxxxxx format is used, the county code is assumed to be UK.
And, assuming that xxxxxx is the same number in the examples above, these
numbers will all be interpreted as the same mobile number.