Quickstart Guide

Global Email

Introduction

Global Email can be used to:

  • Correct syntax errors (remove illegal characters, extra “@” characters etc.)
  • Verify and correct top-level domains
  • Correct common misspellings in domain names
  • Update domains that have changed
  • Standardize casing
  • Validate emails against our database (single or batch requests)
  • Perform real-time mailbox validation

Basic Order of Operations

Email Validation

  • Set up the request
    • License key, options, etc.
  • Send the request.
  • Get JSON or XML response.
  • Interpret and use results.

Input Request

REST

Use a REST request to quickly validate an individual email.

curl -X GET "https://globalemail.melissadata.net/v4/WEB/GlobalEmail/doGlobalEmail?&id=&opt=VerifyMailbox:Express,DomainCorrection:OFF,TimeToWait:25&format=JSON&email=test@melissa.com"

Simply replace to test this request. It will also work in any browser.

Batch

You can send batch requests of up to 10 records per batch that are sent using HTTP POST. This means you cannot send it in a browser like with HTTP GET.

Header

Make sure the header includes this line.

Accept: application/json

Body

{
  "TransmissionReference":"Global Email Request Test",
  "CustomerID":"LICENSE_KEY_HERE",
  "Options":" ",
  "Records":[{
    "RecordID":"1",
    "Email":"email1@sample.com"
  },
  {
    "RecordID":"2",
    "Email":"email1@sample.com"
  }]
}

Input Fields

Batch Input REST Input Description REQUIRED
TransmissionReference t This is a string value that serves as a unique identifier for this set of records. It is returned as sent. NO
CustomerID id The License Key issued by Melissa. YES
Options opt VerifyMailbox
Code Description
Express Default. Quickly validates against database of known email addresses.
Premium A real time check is performed to determine email deliverability.
Domain Correction
Code Description
ON Default. Activates fuzzy email domain correction if the domain is a suspected typo.
OFF No email domain correction.
TimeToWait
Code Description
[5-45] Defaults to 25. Select how long the web service will wait before it times out on an email.
WhoIsLookup
Code Description
ON Default. Gets additional information about the domain from WhoIs.
OFF Does not use WhoIs.
Email email The email address to be verified. YES
format Specify the desired format of the response (XML or JSON). Defaults to XML. NO

Input Best Practices

While text encoding is a rare issue with email addresses, note that Global Email 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.

Output Response

JSON Response

Here is a sample response of the REST request from above.

{
  "Version": "4.2.1.4202",
  "TransmissionReference": "Lookup",
  "TransmissionResults": "",
  "TotalRecords": "1",
  "Records": [
    {
      "RecordID": "1",
      "DeliverabilityConfidenceScore": "63",
      "Results": "ES01,ES07,ES22",
      "EmailAddress": "test@melissa.com",
      "MailboxName": "test",
      "DomainName": "melissa",
	  "DomainAuthenticationStatus": "",
      "TopLevelDomain": "com",
      "TopLevelDomainName": "Commercial",
      "DateChecked": "9/7/2022 10:31:19 PM",
      "EmailAgeEstimated": "0",
      "DomainAgeEstimated": "9322",
      "DomainExpirationDate": "2021-09-14T23:00:00",
      "DomainCreatedDate": "1995-09-15T23:00:00",
      "DomainUpdatedDate": "2020-09-15T04:49:41",
      "DomainEmail": "",
      "DomainOrganization": "",
      "DomainAddress1": "",
      "DomainLocality": "",
      "DomainAdministrativeArea": "California",
      "DomainPostalCode": "",
      "DomainCountry": "UNITED STATES",
      "DomainAvailability": "UNAVAILABLE",
      "DomainCountryCode": "US",
      "DomainPrivateProxy": "",
      "PrivacyFlag": "N",
      "MXServer": "melissadata.com.mx1.rcimx.com",
	  "DomainTypeIndicator": "Business/Organization",
	  "BreachCount": ""
    }
  ]
}

Even when activated, WhoIs sometimes returns incomplete information. We simply relay what we get from them.

The “Mxserver” field is only used with Premium validation.

If receiving a batch response, “TotalRecords” will reflect the number of records, and each record will be in the “Records” array, each having its own “RecordID”, “Results”, etc.

Output Fields

Response (Base Level)

Output Name Description
Version The current service version
TransmissionReference Optional request identifier
TransmissionResults Service and General Transmission Errors
TotalRecords Total number of records.

Record Level

Output Name Description
RecordID The number of the record. Always 1 for 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 A number (0-100) that indicates how confident Global Email is that the email is deliverable.
EmailAddress The email address, after any correcctions or updates were made.
MailboxName Everything before the "@" in the email address.
DomainName The site that provides the email.
DomainAuthenticationStatus The security protocols used on the receiving mail server.
TopLevelDomain The type of domain (e.g. com)
TopLevelDomainName The full name of the top level domain (e.g. com is Commercial)
DateChecked The date the email was validated.
EmailAgeEstimated The estimated minimum age of the email.
DomainAgeEstimated How long the domain has been active
DomainExpirationDate When the domain will be renewed or available to buy.
DomainCreatedDate When the domain was first created.
DomainUpdatedDate When the domain was last renewed.
DomainEmail An email to contact the owner of the domain.
DomainOrganization The company that owns the domain.
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 Is the domain available.
DomainPrivateProxy Does the domain have a provate proxy.
PrivacyFlag Is this email affected by additional privacy reglations, such as GDPR.
MXServer Premium only. The MX server of the domain.
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.

Interpreting Results

Global Email includes a DeliverabilityConfidenceScore (DCS) with each email.

The DCS is a single number in range 0-100 that represents how confident we are that an email will successfully send. It can be used as a quicker and simpler way to filter emails, either as a first step before diving into result codes, or for a single pass of data cleansing.

DCS is not simply a numerical representation of our result codes, though. We leverage various reference data to further refine DCS, which also makes it dynamic - even more dynamic than our existing result codes.

While certain use cases will vary, our general recommendation for using DCS is:

DCS Recommendation
0 to 30 Do not send.
31 to 60 Email delivery not guaranteed.
61 to 100 Send mail. There is a high chance of email delivery success.

If you require more granular analysis, or just need to maintain consistency with other Melissa products, please continue reading to learn about Global Email’s result codes.

All Melissa products use result codes. Result codes are four-character, alpha-numeric codes to two letters followed by two numbers, e.g. ES01. Result codes are returned as a comma-delimited string with no whitespace, e.g. ES01,ES22.

The following table shows the most common result codes seen while using Global Email, and our recommendations for how to interpret them.

Code Description Recommendation for Marketing Recommendation for Point of Entry
ES01 This email was confirmed to be a valid email. Accept Accept
ES03 This email's status is unknown due to unknown external factors. Please try again another time. Reject Caution
ES21 Verified. The email status was found in our database of cached emails. Accept Accept
ES22 Verified. The mailbox validation was performed in real-time. Accept Accept
EE01 There is a syntax error in the submitted email address. Reject Reject
EE02 A Domain of the submitted email address was not found. Reject Reject
EE03 The mail server of the submitted email address was not found. Reject Reject
EE04 An invalid mailbox was detected (i.e. noreply). Reject Reject

For a list of the common transmission errors, see the General Info - Response Level Errors page.

For the full list of all possible result codes, please visit our Result Wiki page at Global Email Result Code Details.