Reference Guide#

Introduction #

Welcome to the EmailLib Service by Melissa. Validate and parse email addresses, correct common typographical errors, and standardize email addresses. Features real-time email mailbox verification which removes up to 95% of bad emails.

Data Path #

This is set during the containerization service setup. It is whatever data path you set.

See {{data_path}} in the Example Docker Setup

Service Port Number #

This is set during the containerization service setup. It defaults to 6245, but can be any port you set.

See {{port_number}} in the Example Docker Setup

Machine Name #

This is your local machine name. You’ll use this in every request you send to your local containerization service. You can view your machine name by using the hostname command in the command prompt.

Licensing #

The License Key is a software key required to use the web service. You will receive your license key from your Melissa representative. If you don’t have a license key, contact the Melissa sales team at sales@melissa.com or 800-MELISSA ext. 3 (800-635-4772 ext. 3). Without a license key the service will not function.

Endpoints #

/V3/WEB/ContactVerify/GetVersion #

Introduction #

Use this endpoint to check the version of the EmailLib Service.

Try It Now #

GET JSON

curl -X GET \
"http://{{machine_name}}:{{port_number}}/V3/WEB/ContactVerify/GetVersion" \
-H "accept: application/json"

Headers #

GET JSON

cache-control: no-cache,no-store,must-revalidate,private
content-type: application/json; charset=utf-8
pragma: no-cache

Response #

GET JSON

{
  "ServiceName": "Global Email",
  "Version": "7.2.1.4253",
  "mdMicroServices_Version": "1.2.1.5368",
  "CustomerIDCheckVersion": "7.2.1.5374",
  "EventReportVersion": "7.2.1.5340",
  "RequestLogVersion": "7.2.1.5352",
  "ResourceStoreVersion": "7.2.1.5333",
  "emailLibService_Version": "7.2.1.17282",
  "BuildNumber": "17282",
  "DatabaseDate": "2023-02-15",
  "ExpirationDate": "2023-08-15"
}

/V3/WEB/ContactVerify/doContactVerify #

Introduction #

Use this endpoint to use all the email verification capabilities of Email Object.

Try It Now #

GET JSON
POST JSON

curl -X GET \
"http://{{machine_name}}:{{port_number}}/V3/WEB/ContactVerify/doContactVerify?\
t=test\
&id={{license_key}}\
&ctry=US\
&a1=22382%20Avenida%20Empresa\
&city=Rancho%20Santa%20Margarita\
&state=CA\
&postal=92688\
&comp=Melissa\
&format=json"\
-H "accept:application/json"

curl -X 'POST' \
  'http://{{machine_name}}:{{port_number}}/V3/WEB/ContactVerify/doContactVerify' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "customerId": "{{license_key}}",
  "options": "",
  "transmissionReference": "test",
  "records": [
    {
      "recordID": "1",
      "addressLine1": "22382 Avenida Empresa",
      "addressLine2": "",
      "suite": "",
      "city": "Rancho Santa Margarita",
      "state": "CA",
      "postalCode": "92688",
      "lastLine": "",
      "plus4": "",
      "deliverypointcode": "",
      "company": "Melissa",
      "urbanization": "",
      "lastName": "",
      "country": "US"
    }
  ]
}'

Request Parameters #

GET JSON
POST JSON

Code

Description

This is a string value that serves as a unique identifier for this set of records. It is returned as sent.

The License Key issued by Melissa.

opt

Set Options
VerifyMailBox
DomainCorrection
TimeToWait
WhoIsLookup
AllowQuotes

format

Specify the desired format of the response (XML or JSON). Defaults to XML.

The email address to be verified.

Code

Description

TransmissionReference

This is a string value that serves as a unique identifier for this set of records. It is returned as sent.

CustomerID

The License Key issued by Melissa.

Options

Set Options
VerifyMailBox
DomainCorrection
TimeToWait
WhoIsLookup
AllowQuotes

RecordID

A unique identifier for the current record.

The email address to be verified.

Headers #

GET JSON
POST JSON

Content-Type: application/json
Accept: application/json

Content-Type: application/json
Accept: application/json

Response #

GET JSON
POST JSON

{
  "Version": "7.2.1.4253",
  "TransmissionReference": "Test",
  "TransmissionResults": "",
  "TotalRecords": "1",
  "Records": [
    {
      "RecordID": "1",
      "DeliverabilityConfidenceScore": "61",
      "Results": "ES01,ES07,ES21",
      "EmailAddress": "test@melissa.com",
      "MailboxName": "test",
      "DomainName": "melissa",
      "DomainAuthenticationStatus": "",
      "TopLevelDomain": "com",
      "TopLevelDomainName": "Commercial",
      "DateChecked": "5/25/2023 12:23:32 AM",
      "EmailAgeEstimated": "2072",
      "DomainAgeEstimated": "9867",
      "DomainExpirationDate": "2023-09-14T23:00:00",
      "DomainCreatedDate": "1995-09-15T23:00:00",
      "DomainUpdatedDate": "2022-09-13T12:15:20",
      "DomainEmail": "",
      "DomainOrganization": "Domains By Proxy, LLC",
      "DomainAddress1": "DomainsByProxy.com 2155 E Warner Rd",
      "DomainLocality": "Tempe",
      "DomainAdministrativeArea": "Arizona",
      "DomainPostalCode": "85284",
      "DomainCountry": "UNITED STATES",
      "DomainAvailability": "UNAVAILABLE",
      "DomainCountryCode": "US",
      "DomainPrivateProxy": "1",
      "PrivacyFlag": "N",
      "MXServer": "",
      "DomainTypeIndicator": "Business/Organization",
      "BreachCount": ""
    }
  ]
}

{
  "Version": "7.2.1.4253",
  "TransmissionReference": "Test",
  "TransmissionResults": "",
  "TotalRecords": "2",
  "Records": [
    {
      "RecordID": "1",
      "DeliverabilityConfidenceScore": "61",
      "Results": "ES01,ES07,ES21",
      "EmailAddress": "info@melissa.com",
      "MailboxName": "info",
      "DomainName": "melissa",
      "DomainAuthenticationStatus": "",
      "TopLevelDomain": "com",
      "TopLevelDomainName": "Commercial",
      "DateChecked": "5/11/2023 7:08:48 PM",
      "EmailAgeEstimated": "2022",
      "DomainAgeEstimated": "9867",
      "DomainExpirationDate": "2023-09-14T23:00:00",
      "DomainCreatedDate": "1995-09-15T23:00:00",
      "DomainUpdatedDate": "2022-09-13T12:15:20",
      "DomainEmail": "",
      "DomainOrganization": "Domains By Proxy, LLC",
      "DomainAddress1": "DomainsByProxy.com 2155 E Warner Rd",
      "DomainLocality": "Tempe",
      "DomainAdministrativeArea": "Arizona",
      "DomainPostalCode": "85284",
      "DomainCountry": "UNITED STATES",
      "DomainAvailability": "UNAVAILABLE",
      "DomainCountryCode": "US",
      "DomainPrivateProxy": "1",
      "PrivacyFlag": "N",
      "MXServer": "",
      "DomainTypeIndicator": "Business/Organization",
      "BreachCount": ""
    },
    {
      "RecordID": "2",
      "DeliverabilityConfidenceScore": "61",
      "Results": "ES01,ES07,ES21",
      "EmailAddress": "test@melissa.com",
      "MailboxName": "test",
      "DomainName": "melissa",
      "DomainAuthenticationStatus": "",
      "TopLevelDomain": "com",
      "TopLevelDomainName": "Commercial",
      "DateChecked": "5/25/2023 12:23:32 AM",
      "EmailAgeEstimated": "2072",
      "DomainAgeEstimated": "9867",
      "DomainExpirationDate": "2023-09-14T23:00:00",
      "DomainCreatedDate": "1995-09-15T23:00:00",
      "DomainUpdatedDate": "2022-09-13T12:15:20",
      "DomainEmail": "",
      "DomainOrganization": "Domains By Proxy, LLC",
      "DomainAddress1": "DomainsByProxy.com 2155 E Warner Rd",
      "DomainLocality": "Tempe",
      "DomainAdministrativeArea": "Arizona",
      "DomainPostalCode": "85284",
      "DomainCountry": "UNITED STATES",
      "DomainAvailability": "UNAVAILABLE",
      "DomainCountryCode": "US",
      "DomainPrivateProxy": "1",
      "PrivacyFlag": "N",
      "MXServer": "",
      "DomainTypeIndicator": "Business/Organization",
      "BreachCount": ""
    }
  ]
}

Service Level Response Fields #

Output Name	Description
Version	The current service version number.
TransmissionReference	Optional. Serves as a unique request identifier.
TransmissionResults	Lists error codes from any errors caused by the most recent request as a whole.
TotalRecords	Total number of records.

Record Level Response Fields #

Output Name	Description
RecordID	The number of the record. Always 1 for a single email request, otherwise it serves as an index of the array of records.
Results	Comma delimited status, error codes, and change codes for the record.
DeliverabilityConfidenceScore	The probability [`0-100`]% of an email sent to this mailbox will be successfully delivered.
EmailAddress	The email address or domain, including any correcctions or updates made by Global Email.
MailboxName	The mailbox or user name portion of the email address (Everything before the “`@`” in the email address).
DomainName	The domain name portion of the email address. (All characters between the “`@`” and “`.`” characters.).
DomainAuthenticationStatus	The security protocols used on the receiving mail server.
TopLevelDomain	The description associated with the top-level domain name of the email address (e.g. com is Commercial).
TopLevelDomainName	The top level domain name portion of the email address (All characters after the “`.`”, e.g. com).
DateChecked	The date the email was validated. It returns UTC, Unix Time (Epoch Time) in the `MM/DD/YYYY H:MM:SS` format.
EmailAgeEstimated	The estimated minimum age of the email in days based on historical data. The value is zero when we lack historical data on a given email.
DomainAgeEstimated	The estimated age of the domain in days.
DomainExpirationDate	The date the domain expires/expired in the `YYYY-MM-DDTHH:MM:SS` format. This is When the domain will be renewed or available to buy.
DomainCreatedDate	The date the domain was created in the `YYYY-MM-DDTHH:MM:SS` format.
DomainUpdatedDate	The date the domain was last updated in the `YYYY-MM-DDTHH:MM:SS` format.
DomainEmail	The email associated with the domain owner.
DomainOrganization	The company associated with the domain owner.
DomainAddress1	The address of the DomainOrganization.
DomainLocality	The city of the DomainOrganization.
DomainAdministrativeArea	The state of the DomainOrganization.
DomainPostalCode	The postal code of the DomainOrganization.
DomainCountry	The country of the DomainOrganization.
DomainCountryCode	The country code of the DomainCountry.
DomainAvailability	Check to see if domain is available for purchase.
DomainPrivateProxy	Check if domain is behind a private proxy.
PrivacyFlag	Is this email affected by additional privacy reglations, such as GDPR. Returns `Y` for yes and `N` for no.
MXServer	Premium only. The Mail Exchange (MX) Server used to validate the email.
Domain Type Indicator	Predicts if email belongs to a personal or business/organization email by analyzing the domain.
Breach Count	The known number of breaches that this email account has been involved in.

Options #

List options in the following format, with multiple options delimited with a ,.

OptionName:Parameter,OptionName:Parameter

VerifyMailBox #

Express #

The Express option of EmailLib Service will use cached mailbox validations, so any submitted emails will be checked against a database of known bad and known good emails. Any emails that are sent into the EXPRESS will also be cached so they can be looked up during a 90-day cycle. Use this option for increased cost savings or where speed and performance are of upmost importance.

Premium #

The Premium option always does the most comprehensive type of real-time checking by using domain-specific logic as well as SMTP commands and other proprietary mechanisms to validate email boxes. Use the PREMIUM option when you absolutely require the highest level of Mailbox verification. Bear in mind it can sometimes take up to 12 seconds to verify an email box. Applications that are time sensitive in nature should be programmed to call the express mode instead.

Parameter	Description
Express	Default. Quickly validates against database of known email addresses.
Premium	A real time check is performed to determine email deliverability.

DomainCorrection #

Parameter	Description
On	Default. Activates fuzzy email domain correction if the domain is a suspected typo.
Off	No email domain correction.

TimeToWait #

TimeToWait allows you to select how long (in seconds) that you would like our web service to wait on a single email before it times out. Select a smaller number if time is of essence, or longer if you would prefer more accurate results.

Parameter	Description
# [5 - 45]	Default set to 25. Select how long the web service will wait before it times out on an email.

WhoIsLookup #

Parameter	Description
On	Default. Activates domain information Lookups.
Off	Deactivates domain information Lookups.

AllowQuotes #

Parameter	Description
On	Default. Allow double-quoted mailbox names. This allows special characters and whitespace within a valid quoted string.
Off	Do not allow double-quoted mailbox names. Illegal special characters and whitespace will be stripped.

Input Best Practices #

While text encoding is a rare issue with email addresses, note that EmailLib Service will not support any wrongly-encoded special characters or non-Latin characters. In general, text encoding is an important part of any data enterprise.

This service can deal with multiple languages and scripts. It expects UTF-8 encoding. Be on the lookout for question marks (?), squares (▖) or other unwanted characters like �. They may be an indication of encoding issues and may result in data loss. Bad encoding or character loss is not something our service can correct for you.

Reference Guide

Contents

Reference Guide#