Reference Guide

Reference Guide#

Introduction#

Welcome to the Global Email 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 99% of bad emails.

CORS Handling - Header Changes

The Access-Control response headers for some requests will change by December 2025.

To read more about this change, please see the advisory.

Base URL#

https://globalemail.melissadata.net

New to Melissa Cloud APIs?#

We highly recommend first time users of our Cloud APIs to review our Using Melissa Cloud APIs section. It will cover critical topics like:

Endpoints#

/V4/WEB/GlobalEmail/doGlobalEmail#

Use this endpoint to use all the email address verification abilities of Global Email.

Try It Now#

  • GET JSON
  • POST JSON
  • GET XML
  • POST XML
curl -X GET "https://globalemail.melissadata.net/v4/WEB/GlobalEmail/doGlobalEmail?\
&format=JSON\
&id={{customerId}}\
&opt=VerifyMailbox:Express,DomainCorrection:OFF,TimeToWait:25\
&t=Test\
&email=info@melissa.com" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

curl -X POST "https://globalemail.melissadata.net/v4/WEB/GlobalEmail/doGlobalEmail" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
       "CustomerID": "{{customerId}}",
       "Options": "VerifyMailbox:Express,DomainCorrection:OFF,TimeToWait:25",
       "Records":
       [{
          "Email": "info@melissa.com",
          "RecordID": "1"
       },{
          "Email": "sales@melissa.com",
          "RecordID": "2"
       }],
       "TransmissionReference": "test"
    }'

curl -X GET "https://globalemail.melissadata.net/v4/WEB/GlobalEmail/doGlobalEmail?\
&format=xml\
&id={{customerId}}\
&opt=VerifyMailbox:Express,DomainCorrection:OFF,TimeToWait:25\
&t=Test\
&email=info@melissa.com" \
-H "Content-Type: application/xml" \
-H "Accept: */*"

curl -X POST "https://globalemail.melissadata.net/v4/WEB/GlobalEmail/doGlobalEmail" \
-H "Content-Type: application/xml" \
-H "Accept: */*" \
-d '<Request>
       <CustomerID>{{customerId}}</CustomerID>
       <Options>VerifyMailbox:Express,DomainCorrection:OFF,TimeToWait:25</Options>
       <Records>
          <RequestRecord>
             <Email>info@melissa.com</Email>
             <RecordID>1</RecordID>
          </RequestRecord>
          <RequestRecord>
             <Email>sales@melissa.com</Email>
             <RecordID>2</RecordID>
          </RequestRecord>
       </Records>
       <TransmissionReference>Test</TransmissionReference>
    </Request>'

Request Parameters#

  • GET JSON
  • POST JSON
  • GET XML
  • POST XML

Code

Description

Request Level Parameters

format

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

id

The License Key issued by Melissa.

opt

Set Options

AllowQuotes

BounceCheck

DomainCorrection

TimeToWait

VerifyMailBox

WhoIsLookup

t

Optional. Serves as a unique request identifier.

Record Level Parameters

email

The email address to be verified.

Code

Description

Request Level Parameters

CustomerID

The License Key issued by Melissa.

Format

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

Options

Set Options

AllowQuotes

BounceCheck

DomainCorrection

TimeToWait

VerifyMailBox

WhoIsLookup

TransmissionReference

Optional. Serves as a unique request identifier.

Record Level Parameters

Email

The email address to be verified.

RecordID

A unique identifier for the current record.

Code

Description

Request Level Parameters

format

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

id

The License Key issued by Melissa.

opt

Set Options

AllowQuotes

BounceCheck

DomainCorrection

TimeToWait

VerifyMailBox

WhoIsLookup

t

Optional. Serves as a unique request identifier.

Record Level Parameters

email

The email address to be verified.

Code

Description

Request Level Parameters

CustomerID

The License Key issued by Melissa.

Format

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

Options

Set Options

AllowQuotes

BounceCheck

DomainCorrection

TimeToWait

VerifyMailBox

WhoIsLookup

TransmissionReference

Optional. Serves as a unique request identifier.

Record Level Parameters

Email

The email address to be verified.

RecordID

A unique identifier for the current record.
Options#

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

OptionName:Parameter,OptionName:Parameter
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.
BounceCheck#

The BounceCheck option enables more accurate validation for Yahoo-like domains that tend to mark all emails as “valid” (sometimes referred to as “Accept-All” or “Catch-All”). With BounceCheck enabled, we will conditionally trigger a real-time test message to the mail server for a given mailbox. While most requests complete in a few seconds or less, this method may take longer as we wait for a bounce from the mail server.

When using this option, the minimum value for TimeToWait becomes 25 (seconds).

Parameter

Description

Off

Default. No test messages will be sent.

On

A real-time test message may be sent to the mail server for this mailbox.
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 Cloud API 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 Cloud API will wait before it times out on an email.
VerifyMailBox#

Express

The Express option of Global Email 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 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. While most mailbox checks take milliseconds, some may take up to TimeToWait seconds (default of 25). Applications that are time sensitive in nature should be programmed to have a shorter TimeToWait or call the express mode instead.

Parameter

Description

Express

Quickly validates against database of known email addresses.

Premium

Default. A real time check is performed to determine email deliverability.
WhoIsLookup#

Parameter

Description

On

Default. Activates domain information Lookups.

Off

Deactivates domain information Lookups.

Headers#

  • GET JSON
  • POST JSON
  • GET XML
  • POST XML
Content-Type: application/json
Accept: application/json

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

Content-Type: application/xml
Accept: */*

Content-Type: application/xml
Accept: */*

Response#

  • GET JSON
  • POST JSON
  • GET XML
  • POST XML
{
   "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": ""
   }]
}

<Response
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns="urn:mdGlobalEmail">
   <Version>7.2.1.4253</Version>
   <TransmissionReference>Test</TransmissionReference>
   <TransmissionResults />
   <TotalRecords>1</TotalRecords>
   <Records>
      <ResponseRecord>
         <RecordID>1</RecordID>
         <DeliverabilityConfidenceScore>61</DeliverabilityConfidenceScore>
         <Results>ES01,ES07,ES21</Results>
         <EmailAddress>info@melissa.com</EmailAddress>
         <MailboxName>info</MailboxName>
         <DomainName>melissa</DomainName>
         <DomainAuthenticationStatus />
         <TopLevelDomain>com</TopLevelDomain>
         <TopLevelDomainName>Commercial</TopLevelDomainName>
         <DateChecked>5/11/2023 7:08:48 PM</DateChecked>
         <EmailAgeEstimated>2023</EmailAgeEstimated>
         <DomainAgeEstimated>9867</DomainAgeEstimated>
         <DomainExpirationDate>2023-09-14T23:00:00</DomainExpirationDate>
         <DomainCreatedDate>1995-09-15T23:00:00</DomainCreatedDate>
         <DomainUpdatedDate>2022-09-13T12:15:20</DomainUpdatedDate>
         <DomainEmail />
         <DomainOrganization>Domains By Proxy, LLC</DomainOrganization>
         <DomainAddress1>DomainsByProxy.com 2155 E Warner Rd</DomainAddress1>
         <DomainLocality>Tempe</DomainLocality>
         <DomainAdministrativeArea>Arizona</DomainAdministrativeArea>
         <DomainPostalCode>85284</DomainPostalCode>
         <DomainCountry>UNITED STATES</DomainCountry>
         <DomainAvailability>UNAVAILABLE</DomainAvailability>
         <DomainCountryCode>US</DomainCountryCode>
         <DomainPrivateProxy>1</DomainPrivateProxy>
         <PrivacyFlag>N</PrivacyFlag>
         <MXServer />
         <DomainTypeIndicator>Business/Organization</DomainTypeIndicator>
         <BreachCount />
      </ResponseRecord>
   </Records>
</Response>

<Response
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns="urn:mdGlobalEmail">
   <Version>7.2.1.4253</Version>
   <TransmissionReference>Test</TransmissionReference>
   <TransmissionResults />
   <TotalRecords>2</TotalRecords>
   <Records>
      <ResponseRecord>
         <RecordID>1</RecordID>
         <DeliverabilityConfidenceScore>61</DeliverabilityConfidenceScore>
         <Results>ES01,ES07,ES21</Results>
         <EmailAddress>info@melissa.com</EmailAddress>
         <MailboxName>info</MailboxName>
         <DomainName>melissa</DomainName>
         <DomainAuthenticationStatus />
         <TopLevelDomain>com</TopLevelDomain>
         <TopLevelDomainName>Commercial</TopLevelDomainName>
         <DateChecked>5/11/2023 7:08:48 PM</DateChecked>
         <EmailAgeEstimated>2023</EmailAgeEstimated>
         <DomainAgeEstimated>9867</DomainAgeEstimated>
         <DomainExpirationDate>2023-09-14T23:00:00</DomainExpirationDate>
         <DomainCreatedDate>1995-09-15T23:00:00</DomainCreatedDate>
         <DomainUpdatedDate>2022-09-13T12:15:20</DomainUpdatedDate>
         <DomainEmail />
         <DomainOrganization>Domains By Proxy, LLC</DomainOrganization>
         <DomainAddress1>DomainsByProxy.com 2155 E Warner Rd</DomainAddress1>
         <DomainLocality>Tempe</DomainLocality>
         <DomainAdministrativeArea>Arizona</DomainAdministrativeArea>
         <DomainPostalCode>85284</DomainPostalCode>
         <DomainCountry>UNITED STATES</DomainCountry>
         <DomainAvailability>UNAVAILABLE</DomainAvailability>
         <DomainCountryCode>US</DomainCountryCode>
         <DomainPrivateProxy>1</DomainPrivateProxy>
         <PrivacyFlag>N</PrivacyFlag>
         <MXServer />
         <DomainTypeIndicator>Business/Organization</DomainTypeIndicator>
         <BreachCount />
      </ResponseRecord>
      <ResponseRecord>
         <RecordID>2</RecordID>
         <DeliverabilityConfidenceScore>55</DeliverabilityConfidenceScore>
         <Results>ES01,ES07,ES21</Results>
         <EmailAddress>sales@melissa.com</EmailAddress>
         <MailboxName>sales</MailboxName>
         <DomainName>melissa</DomainName>
         <DomainAuthenticationStatus />
         <TopLevelDomain>com</TopLevelDomain>
         <TopLevelDomainName>Commercial</TopLevelDomainName>
         <DateChecked>5/16/2022 1:40:17 PM</DateChecked>
         <EmailAgeEstimated>2010</EmailAgeEstimated>
         <DomainAgeEstimated>9867</DomainAgeEstimated>
         <DomainExpirationDate>2023-09-14T23:00:00</DomainExpirationDate>
         <DomainCreatedDate>1995-09-15T23:00:00</DomainCreatedDate>
         <DomainUpdatedDate>2022-09-13T12:15:20</DomainUpdatedDate>
         <DomainEmail />
         <DomainOrganization>Domains By Proxy, LLC</DomainOrganization>
         <DomainAddress1>DomainsByProxy.com 2155 E Warner Rd</DomainAddress1>
         <DomainLocality>Tempe</DomainLocality>
         <DomainAdministrativeArea>Arizona</DomainAdministrativeArea>
         <DomainPostalCode>85284</DomainPostalCode>
         <DomainCountry>UNITED STATES</DomainCountry>
         <DomainAvailability>UNAVAILABLE</DomainAvailability>
         <DomainCountryCode>US</DomainCountryCode>
         <DomainPrivateProxy>1</DomainPrivateProxy>
         <PrivacyFlag>N</PrivacyFlag>
         <MXServer />
         <DomainTypeIndicator>Business/Organization</DomainTypeIndicator>
         <BreachCount />
      </ResponseRecord>
   </Records>
</Response>
Service Level Response Fields#

Output Name

Description

TotalRecords

Total number of records.

TransmissionReference

A pass-through of the input TransmissionReference field.

TransmissionResults

Lists error codes from any errors caused by the most recent request as a whole.

Version

The current service version number.
Record Level Response Fields#

Output Name

Description

Breach Count

The known number of breaches that this email account has been involved in.

DateChecked

The date the email was validated. It returns UTC, Unix Time (Epoch Time) in the MM/DD/YYYY H:MM:SS format.

DeliverabilityConfidenceScore

The probability [0-100]% of an email sent to this mailbox will be successfully delivered.

Domain Type Indicator

Predicts if email belongs to a personal or business/organization email by analyzing the domain.

DomainAddress1

The address of the DomainOrganization.

DomainAdministrativeArea

The state of the DomainOrganization.

DomainAgeEstimated

The estimated age of the domain in days.

DomainAuthenticationStatus

The security protocols used on the receiving mail server.

DomainAvailability

Check to see if domain is available for purchase.

DomainCountry

The country of the DomainOrganization.

DomainCountryCode

The country code of the DomainCountry.

DomainCreatedDate

The date the domain was created in the YYYY-MM-DDTHH:MM:SS format.

DomainEmail

The email associated with the domain owner.

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.

DomainLocality

The city of the DomainOrganization.

DomainName

The domain name portion of the email address. (All characters between the “@” and “.” characters.).

DomainOrganization

The company associated with the domain owner.

DomainPostalCode

The postal code of the DomainOrganization.

DomainPrivateProxy

Check if domain is behind a private proxy.

DomainUpdatedDate

The date the domain was last updated in the YYYY-MM-DDTHH:MM:SS format.

EmailAddress

The email address or domain, including any corrections or updates made by Global Email.

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.

MailboxName

The mailbox or user name portion of the email address (Everything before the “@” in the email address).

MXServer

Premium only. The Mail Exchange (MX) Server used to validate the email.

PrivacyFlag

Is this email affected by additional privacy regulations, such as GDPR. Returns Y for yes and N for no.

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.

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).

/V4/WEB/GlobalEmail/getVersion#

Introduction#

Use the getVersion endpoint to check your Global Email version and ensure you’re up to date.

Try It Now#

  • GET JSON
curl -X GET "https://globalemail.melissadata.net/v4/WEB/GlobalEmail/getVersion" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

Headers#

  • GET JSON
Content-Type: application/json
Accept: application/json

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"
}

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.

Interpreting Results#

We recommend that most clients leverage the Deliverability Confidence Score (DCS) field for a simple way to determine email deliverability and validity. Distilling the result codes and email metadata and signals allow us to generate a simple score that will generally be more accurate than result codes alone.

Though we recommend using DCS for your primary validity criteria, Result Codes are helpful to understand results and give more information where action might be required. While an email may be deliverable, there may still be value in, for example, giving users feedback when typos were corrected or flagging a record in your system when a user registers with a disposable or otherwise malicious domain.

Using DCS#

Using the DeliverabilityConfidenceScore (DCS) can be as simple as a “greater than or equal to” decision.

Our general recommendations for using DCS are:

DCS

Marketing

Point of Entry/Form

0 to 30

Do not send email.

Do not accept email, but consider letting users override this.

31 to 60

Do not send email without additional evidence that the email is currently good.

Accept email conditionally; prompt user to double-check input.

61 to 75

Send email, unless risk tolerance for bounces is low (i.e. building or repairing sender reputation).

Accept email. Very likely to be a good email address.

76 to 100

Send email. Very likely to be a good address.

Accept email. Very likely to be a good email address.

We believe the DCS is a valuable tool to make quick decisions about email deliverability. Marketing campaigns, in particular, are often sensitive to special cases like accept-all email addresses. By themselves, result codes do not always provide a clear indication of deliverability. In such cases, relying purely on result code filters puts the efficacy of a campaign and your sender reputation at risk.

Because the DCS factors in more than just result codes, we recommend using DCS as the primary filter for validation efforts. For an example of how you might implement something like this, see the Pseudocode section below.

Pseudocode#

# Pythonic pseudocode for validating email addresses at point of entry, such as a registration form.

# A "marketing rule" which requires a DCS of 61 allows you to filter emails with a medium-high likelihood of deliverability.
DCS_MARKETING = 61
# A "minimum rule" which requires a DCS of 41 allows you to accept emails from user inputs, even though they may not be good candidates to send marketing materials to.
DCS_MINIMUM = 41

# You may want to check result codes for any special cases you would like to handle.
CORRECTION_CODES = ["ES10","ES11","ES12","ES13"] # returned when certain types of corrections were applied to the output email
ROLE_ADDRESS_CODE = "ES08" # returned for addresses like info@melissadata.com

input_email = "john.doe@melissadata.com"
is_valid = None
is_good_for_marketing = None

# Send the record to the web service and get result codes for the response. In production, be sure you handle HTTP Errors and TransmissionResults in the top level of the response body.
service_response = send_email_request(john.doe@melissadata.com)
response_record = service_response["Records"][0]
corrected_email = response_record["EmailAddress"] # It is important to use the output email since Global Email can correct typos.

# Check validity and deliverability of the email address using the DCS.
if(response_record["DeliverabilityConfidenceScore"] >= DCS_MINIMUM):
  is_valid = True
elif(response_record["DeliverabilityConfidenceScore"] > 0):
  is_valid = True
  prompt_user("This email address appears to be invalid. Are you sure you’d like to use this email address?")
elif(response_record["DeliverabilityConfidenceScore"] == 0):
  is_valid = False
  prompt_user("This email address appears to be invalid. Please enter a valid email address.")

# Check to see if the email was corrected.
# If this is on a registration form, consider prompting your user to accept/reject the correction.
if(response_record["Results"].containsAnyOf(CORRECTION_CODES)):
  corrected_email = service_response["EmailAddress"]
  user_message = f"We detected a likely typo in your email address. Did you mean ${corrected_email}?"
  prompt_user(user_message)

# Check for special codes like Role Addresses depending on use case.

# For example, if you prefer the user's personal address and not an email group, you might choose to reject these or require confirmation from the user.
if(response_record["Results"].contains(ROLE_ADDRESS_CODE)):
  handle_role_address(corrected_email)

# Check if the email address is likely to be deliverable, and thus a good marketing candidate, using the DCS.
if(response_record["DeliverabilityConfidenceScore"] >= DCS_MARKETING):
  is_good_for_marketing = True
  include_in_marketing_campaign(corrected_email)

Interpreting Result Codes#

Result codes yield more granular information about a given email. They are returned as a comma-delimited string of 4-character alpha-numeric codes, e.g. ES01,ES07,ES21 or EE04,ES22.

SE## and GE## Codes#

The SE## and GE## codes (Transmission Service Error and General Transmission Error) are used to signify more general errors, and are returned under the key TransmissionResults in the outermost level of our responses.

ES## and EE## Codes#

The ES## and EE## codes (Email Status and Email Error) are returned alongside each email record in a response.

ES37 - Breach Flag Usage Guidelines#

The ES37 result code enhances both internal and client security by identifying potentially compromised email accounts. However, it’s important to note that the Breach Flag is not intended as an anti-fraud measure. Emails marked with an ES37 code should not be dismissed as fraudulent solely based on this flag. Instead, the code serves as a warning flag, prompting additional monitoring or two-factor authentication (2FA) for the affected email address.

Using Result Codes (Advanced)#

While Deliverability Confidence Score (DCS) can help you understand if an email is “good” to send to, result codes can be used to get more specific information about validation results.

Looking for exact matches between two result code strings could lead to misinterpretations. The same underlying outcome can be expressed through different result code combinations. For example, a valid email might return any of the following: ES01,ES22, ES01,ES10,ES22, or ES01,ES10,ES12,ES22. In each case, the email is valid, but the API made different corrections to the input. Setting up business logic for when only a specific combination is found may result in improper handling.

By using DCS first (described in above sections) and interpreting result codes when more information is needed, implementation is simplified and the addition or removal of any result codes will not affect your processes. While changes in result codes are rare outside of major releases, this is the most future proof approach to handle results.

For example, the result code ES02 was deprecated after Global Email version 3. However, even with version 3, any email that came back with ES02 always had at least one EE## code (e.g. ES02,EE04). Any implementation that was looking for a high DCS score or an EE## code independently of ES02 would have been forward compatible; those relying on specific combinations would have broken.

Result Codes for Validation (Legacy Apps)#

We strongly recommend using DCS instead of interpreting every result code to determine validity. However, if result codes are to be interpreted to determine acceptance criteria, it is often best to use cascading logic.

Since multiple codes can be returned in a single response, it’s important to process them in order of priority to ensure accurate handling. For instance, if an email returns ES01,ES05,ES22, the ES05 should be addressed before ES01 as it indicates a more critical status to check.

How you choose to act on each code will depend on your specific use case. Typically, once you identify that an email is invalid (EE##) or contains a set of undesirable result code(s), then you shouldn’t need to evaluate those results further.

The following table shows the most common result codes seen while using Global Email and our recommendations for how to interpret them. The codes are ordered by priority – meaning you should filter for and handle the codes higher on the list before those lower down.

Code

Description

Recommendation for Marketing

Recommendation for Point of Entry

EE01

Email Syntax Error

Reject

Reject

EE02

Email Domain Not Found

Reject

Reject

EE03

Email Server Not Found

Reject

Reject

EE04

Invalid Email

Reject

Reject

ES04

Mobile Email Address

Reject

Reject

ES05

Disposable Domain

Reject

Caution

ES06

Spamtrap Domain

Reject

Accept

ES36

Spamtrap Mailbox

Reject

Accept

ES08

Role Address

Caution

Accept

ES09

Protected Mailbox Caution

Caution

Accept

ES07

Accept All Server

Caution

Accept

ES31

Suspicious Characters

Caution

Accept

ES03

Unknown Email

Caution

Accept

ES01

Valid Email

Accept

Accept
Contents