Reference Guide

Reference Guide#

Introduction#

The WebSmart Email Verifier verifies that a submitted email address belongs to a valid domain. It can correct common misspellings of domains and update domain names if they have changed due to corporate mergers or other situations. The service also parses the email into mailbox name (the part before the @), the domain name and the top-level domain name (.com, .org and so on).

There are three ways to access the web service.

Service URLs#

Protocol

URL

SOAP

https://email.melissadata.net/v2/soap/service.svc

SOAP:WSDL

https://email.melissadata.net/v2/soap/service.svc?wsdl

SOAP:Flat WSDL

https://email.melissadata.net/v2/soap/service.wsdl

XML

https://email.melissadata.net/v2/xml/service.svc

REST

https://email.melissadata.net/v2/rest/service.svc

Sample Code#

Adding WebSmart Email Verifier Web Service to a Project#

If you are using the SOAP service with Visual Studio .NET, you need to add a web reference to the service to your project. Click on the Project menu and select Add Web Reference.... Enter the following URL on the Add Web Reference dialog box:

https://email.melissadata.net/v2/SOAP/Service.svc

If you are not using Visual Studio .NET, see the documentation for your SOAP interface for the procedure for adding the service to your project.

Submitting an XML Request#

After building your XML string from your data, an XML request to the web service is submitted using an HTTP POST operation to the following URL:

https://email.melissadata.net/v2/XML/Service.svc/doEmailCheck

Building a REST Request#

Query strings are sent to the web service as part of the URL using an HTTP Get operation appended to following URL:

https://email.melissadata.net/v2/REST/Service.svc/doEmailCheck

Many modern programming language have a URL encode and URL decoding function that automates these character replacements.

Email Verifier Request#

At the very minimum, a request to the WebSmart Email Verifier consists of the user’s Customer ID and at least one email address.

SOAP Request#

The following Visual Basic Code shows a simple order of operations for building and submitting a RequestArray object, submitting it to the web service and retrieving a response object.

Step 1 – Create the Request and Response Objects

Dim ReqEmail As New dqwsEmail.RequestArray
Dim ResEmail As New dqwsEmail.ResponseArray

Step 2 – Assign the General Request Values

There are two properties of the Request Array object that apply to the request as a whole. CustomerID is required.

ReqEmail.CustomerID = strCustID
ReqEmail.TransmissionReference = strTranRef

The Transmission Reference is a unique string value that identifies this request array.

Step 3 – Dimension the Record Array

The maximum number of records per request is 100, therefore the largest dimension will be 99.

ReDim ReqEmail.Record(99)

For maximum efficiency, you should dimension the array using the exact number of records being submitted minus one.

Step 4 – Build the Record Array

The exact method for building the array will depend on the exact database software in use, but you will need to loop through every record to be submitted and assign the required values to the corresponding elements for each record in the RequestArray.

ReqEmail.Record(intRecord) = New dqwsEmail.RequestArrayRecord
ReqEmail.Record(intRecord).Email = "ray@mailerssoftware.com"
ReqEmail.Record(intRecord).RecordID = 1

The lines above show only the elements that are absolutely required to submit a record to the web service.

Repeat for each record being submitted with the current RequestArray.

Step 5 – Submit the Request Array

The final step is to create the Service Client Object and then submit the RequestArray object doEmail method. This sends the data to the web service and retrieves the ResponseArray object.

EmailClient = New dqwsEmail.Service
ResEmail = EmailClient.doEmailCheck(ReqEmail)
EmailClient.Dispose()

XML Request#

The raw XML request is built using whatever XML tools are available via your development tools and submitted to the following URL using an HTTP POST request.

https://email.melissadata.net/v2/XML/Service.svc/doEmailCheck

Rather than an array of Record object, an XML request contains a <Record> element for each address record, up to 100.

The following XML Code contains the same request as the SOAP example above.

<?xml version="1.0" ?>
<RequestArray xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <TransmissionReference xmlns="urn:mdWebServiceEmail">Test
  </TransmissionReference>
  <CustomerID xmlns="urn:mdWebServiceEmail">XXXXXXXX</CustomerID>
  <Record xmlns="urn:mdWebServiceEmail">
    <Email>ray@melissadata.com</Email>
  </Record>
</RequestArray>

REST Request#

A REST request can submit a single address record via an HTTP GET. The following example uses the same address as the SOAP and XML samples.

https://email.melissadata.net/v2/REST/Service.svc/doEmailCheck?id=12345678&t=RestTest&email=ray%40mailerssoftware.com

Remember that the @ must be replaced by a URL entity before submitting the REST request to the web service.

The record ID element does not exist for the REST interface, since you can only submit a single record per request.

Request Elements#

The following section lists the elements that set the basic options for each and identify the user to the web service.

Customer ID#

This is a required string value containing the identifier number issued to the customer when signing up for the WebSmart Services.

You need a customer ID to access any Melissa Data web service. If this element is not populated, the web service will return an error. To receive a customer ID, call your Melissa Data sales representative.

SOAP#

Request.CustomerID = string

XML#

<RequestArray>
  <CustomerID>String</CustomerID>
</RequestArray>

REST#

id={CustomerID}

Transmission Reference#

This is an optional string value that may be passed with each Request Array to serve as a unique identifier for this set of records.

This value is returned as sent by the Response Array, allowing you to match the Response to the Request.

SOAP#

Request.TransmissionReference = string

XML#

<RequestArray>
  <TransmissionReference>String</TransmissionReference>
</RequestArray>

REST#

t={transMissionReference}

Record Elements#

For the SOAP and XML services, the Request Array will contain an element or property called Record. In SOAP this property is an array of object variables of the type Record. XML will have as many Record elements as there are addresses being submitted to the web service. The REST interface only allows a single record per request.

Record ID#

This element is a string value containing a unique identifier for the current record.

Use this element to match the record with the record returned with the Response Array.

When using the SOAP interface, if this element is not populated, the web service will automatically insert a sequential number for each record. There is no equivalent for Record ID for the REST interface.

SOAP#

Request.Record().RecordID = string

XML#

<RequestArray>
  <Record>
    <RecordID>String</RecordID>
  </Record>
</RequestArray>

Email#

This element must contain a well-formed email address.

A well-formed email address contains a mailbox and a domain name separated by a @ character.

SOAP#

Request.Record().Email = string

XML#

<RequestArray>
  <Record>
    <Email>String</Email>
  </Record>
</RequestArray>

REST#

email={Email}

Email Verifier Response#

The SOAP interface for the Email Verifier service returns a ResponseArray Object. The primary component of this object is an array of Record objects, one for each record submitted with the RequestArray, containing the verified and standardized email address.

The XML interface returns an XML document containing a number of <Record> elements, one for each record submitted with the Request, containing the verified and standardized email address.

The REST interface returns an XML document with a single <Record> element.

TransmissionReference#

Returns a string value containing the contents of the TransmissionReference element from the original Request.

If you passed any value to the TransmissionReference element when building your request, it is returned here. You can use this property to match the response to the request.

SOAP#

string = Response.TransmissionReference

XML#

<ResponseArray>
  <TransmissionReference>String</TransmissionReference>
</ResponseArray>

Total Records#

Returns a string value containing the number of records returned with the current response.

This property returns the number of records processed and returned by the response as a string value.

SOAP#

string = Response.TotalRecords

XML#

<ResponseArray>
  <TotalRecords>String</TotalRecords>
</ResponseArray>

Results#

Returns a string value containing the general and system error messages from the most recent request sent to the service.

Do not confuse this element with the Results element returned with each record. This element returns error messages caused by the most recent request as a whole.

For a list of these codes, see Email Verifier - Service Level Result Codes.

SOAP#

string = Response.Results

XML#

<ResponseArray>
  <Results>String</Results>
</ResponseArray>

Version#

Returns a string value containing the current version number of the Email Verifier Service.

SOAP#

string = Response.Version

XML#

<ResponseArray>
  <Version>String</Version>
</ResponseArray>

Response Record Elements#

The SOAP version of the Response Array returns a property called Record which is an array of Record objects, one for each record submitted with the original Request Array.

The XML service returns one <Record> element for every record submitted with the original request.

The REST response is identical to the XML response, but will only contain a single <Record> element.

Record ID#

For each record in the Response Array, this element returns a string value containing the unique identifier for the current record if one was passed to the Request Array.

Use this element to match the record in the Response Array with the record originally passed with the request.

SOAP#

string = Response.Record().RecordID

XML#

<ResponseArray>
  <Record>
    <RecordID>String</RecordID>
  </Record>
</ResponseArray>

Results#

For each record in the Response Array, this element returns a string value containing status and error codes for the current record. Multiple codes are separated by commas.

This element returns the status and error messages for each record in the Response Array.

The Result element may return one or more four-character strings, separated by commas, depending on the result generated by the current record.

If the address in the current record was verified, this element will contain the value ES01 at the very minimum and may include more of the ES codes. If the address could not be verified, the codes beginning with EE will indicate the reason or reasons why verification failed.

For a list of these codes, see Email Verifier - Record Level Result Codes.

SOAP#

string = Response.Record().Results

XML#

<ResponseArray>
  <Record>
    <Results>String</Results>
  </Record>
</ResponseArray>

EmailAddress#

For each record in the Response Array, this element returns the updated, corrected email address.

If the submitted address could not be verified, this will return the contents of the Email element submitted with the Request Array.

SOAP#

string = Response.Record().Email.EmailAddress

XML#

<ResponseArray>
  <Record>
    <Email>
      <EmailAddress>String</EmailAddress>
    </Email>
  </Record>
</ResponseArray>

Domain Name#

For each record in the Response Array, this element returns the domain name portion of the email address passed to the Request Array record, excluding the Top Level Domain, including any changes or corrections that have been made by the WebSmart Email Verifier.

This element returns a string value containing the domain name portion of the corrected email address. For example, it returns all characters that come after the @ character, not including the Top Level Domain, such as .com. If the final address is jsmith@melissadata.com, this property just returns melissadata.

To get the full domain name, combine the results of this element with a . character and the contents of the TopLevelDomain Name element.

SOAP#

string = Response.Record().Email.DomainName

XML#

<ResponseArray>
  <Record>
    <Email>
      <DomainName>String</DomainName>
    </Email>
  </Record>
</ResponseArray>

Mailbox Name#

For each record in the Response Array, this element returns the mailbox or user name portion of the email address passed to the VerifyEmail address, including any changes or corrections that have been made by the Web Service.

This element returns a string value containing the mailbox name or user name portion of the email address (all characters that precede the @ character). If the final address is jsmith@melissadata.com, this property returns jsmith.

SOAP#

string = Response.Record().Email.MailboxName

XML#

<ResponseArray>
  <Record>
    <Email>
      <MailboxName>String</MailboxName>
    </Email>
  </Record>
</ResponseArray>

Top Level Domain#

For each record in the Response Array, the Name element returns the Top Level Domain name portion of the email address passed to the Web Service address, including any changes or corrections that have been made by the Web Service. The Description element returns the long-form description of the Top Level Domain name portion of the email address.

The Name element returns a string value containing the Top Level Domain name portion of the corrected email address, such as com. If the final address is jsmith@melissadata.com, this element returns com.

SOAP#

string = Response.Record().Email.TopLevelDomain.Name
string = Response.Record().Email.TopLevelDomain.Description

XML#

<ResponseArray>
  <Record>
    <Email>
      <TopLevelDomain>
        <Name>String</Name>
        <Description>String</Description>
      </TopLevelDomain>
    </Email>
  </Record>
</ResponseArray>

Web Response XML Format#

The following shows the structure of the XML document returned by the Email Verifier Service.

<?xml version="1.0" ?>
<ResponseArray xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Version xmlns="urn:mdWebServiceEmail">1.0.32</Version>
  <TransmissionReference xmlns="urn:mdWebServiceEmail">Test</TransmissionReference>
  <Results xmlns="urn:mdWebServiceEmail" />
  <TotalRecords xmlns="urn:mdWebServiceEmail">1</TotalRecords>
  <Record xmlns="urn:mdWebServiceEmail">
    <RecordID>1</RecordID>
    <Results>ES01</Results>
    <Email>
      <EmailAddress>ray@melissadata.com</EmailAddress>
      <DomainName>melissadata</DomainName>
      <MailboxName>ray</MailboxName>
      <TopLevelDomain>
        <Name>com</Name>
        <Description>commercial</Description>
      </TopLevelDomain>
    </Email>
  </Record>
</ResponseArray>
Contents