Reference Guide#

Introduction #

Email Object will allow your Websites and custom applications to update email addresses in your database files while verifying and correcting misspelled domain names. Email Object also allows for easy customization of domain changes, common misspellings, and suppression of bad domains.

You can use Email Object to:

Check for and remove syntax errors: (@@#$5!..`]>
Verify and optionally correct top-level domain names.
Return the top level domain description
Check for, and optionally correct, misspelled domain names.
Check for, and optionally correct, domains that have changed.
Standardize casing in email addresses.
Parse email addresses into various components: bud, @, 800mail, com

Setup and List of Files #

To see how to set up the Email Object, the list of files that will be downloaded and used, and the system requirements to run the Object, please visit the GitHub Sample Code.

Methods #

Initialize Email Object - Set #

These functions initialize Email Object and connect it to its data files.

InitializeDataFiles #

Syntax:: InitializeDataFiles();
Returns:: Initialization Status
Return Type:: ProgramStatus

The InitializeDataFiles function opens the required data files and prepares Email Object for use.

Before calling this function, the SetPathToEmailFiles function must have been called.

Return Value: This function returns a value of the enumerated data type ProgramStatus. If the initialization is successful, this value will be zero (No Error). If any other value is returned, check the GetInitializeErrorString function to see the reason for the error.

SetLicenseString #

Syntax:: SetLicenseString(String_License);
Returns:: Is License Valid
Return Type:: Boolean

This function sets the license string required to enable Email Object’s complete functionality.

If a valid license string is not set, Email Object will not operate.

Parameters: The SetLicenseString function has one parameter; LicenseString, a string value representing the software license key.
Return Value: The SetLicenseString function returns a Boolean value of 0 (FALSE) or 1 (TRUE). It will return a FALSE Boolean value if the license string provided is incorrect.

SetPathToEmailFiles #

Syntax:: SetPathToEmailFiles(String_DataPath);
Return Type:: Void

This function passes a string value containing the file path to the data files used by Email Object. It must be called prior to calling the InitializeDataFiles function.

The parameter must contain a valid path to the directory that contains the files mdEmail.db3 and mdEmail.cfg.

Initialize Email Object - Get #

The following functions get values related to the initialization process.

GetBuildNumber #

Syntax:: GetBuildNumber();
Returns:: Build Number
Return Type:: String

The GetBuildNumber function returns the current development release build number of Email Object.

GetDatabaseDate #

Syntax:: GetDatabaseDate();
Returns:: Database Date
Return Type:: String

The GetDatabaseDate function returns a string value that represents the date of your Email data files.

GetDatabaseExpirationDate #

Syntax:: GetDatabaseExpirationDate();
Returns:: Database Expiration Date
Return Type:: String

If this date has passed, Email Object will not initialize. You will need to update your copy to continue using it. As long as your subscription is still current, you should receive an undated copy of Email Object before your current database expires.

Return Value: This function returns a string value containing the expiration date for the current mdEmail.db3 file.

GetInitializeErrorString #

Syntax:: GetInitializeErrorString();
Returns:: Error Description
Return Type:: String

This function returns a descriptive string to describe the error from the InitializeDataFiles function.

GetLicenseStringExpirationDate #

Syntax:: GetLicenseStringExpirationDate();
Returns:: License Expiration Date
Return Type:: String

This function returns a date value corresponding to the date when the current license string expires.

License strings issued by Melissa Data are valid a certain period of time. This function returns the date after which the current license string is no longer valid.

Set Email Object Options #

These functions enable or disable the various options of Email Object.

SetCorrectSyntax #

Syntax:: SetCorrectSyntax(bool);
Return Type:: Void

This function enables or disables the syntax correction functionality of Email Object.

If the Boolean value passed to this function is TRUE, Email Object will attempt to correct the syntax of the email address passed to the VerifyEmail function. This process includes:

Removal of any illegal characters from the address. This would include excess “@” characters.
Correction of misspelled top-level domain names. For example, “.con” would be replaced with “.com.”
Mailbox syntax will be corrected to the RFC 5322 specification strict definitions. It allows for usage of special characters in some situations. For example: “very.unusual.@.unusual.com”@example.com is allowed because the additional ‘@’ is surrounded by quotes.

The CorrectSyntax feature is enabled by default.

SetDatabaseLookup #

Syntax:: SetDatabaseLookup(bool);
Return Type:: Void

This function enables or disables the database lookup validation function of Email Object.

If the Boolean value passed to this function is TRUE, Email Object will attempt to validate the email address passed to the VerifyEmail function using its own database of known valid and invalid domain names. Domain names that appear neither on the known valid nor invalid domain lists will return a result code of “ES03” for “unverified.”

The Database Lookup feature is enabled by default.

SetFuzzyLookup #

Syntax:: SetFuzzyLookup(bool);
Return Type:: Void

This function enables or disables Melissa Data’s fuzzy lookup validation function of Email Object.

If the Boolean value passed to this function is TRUE, Email Object will attempt to validate the email address passed to the VerifyEmail function by attempting to apply fuzzy matching algorithms to the input domain. This is slower than a database lookup but potentially more accurate if the domain name contains a common or transposed typo.

The results of this check will set the return value of the GetResults function. Domain names that cannot be verified by a Fuzzy Lookup will return a code for “Unverified email address.”

The Fuzzy Lookup feature is disabled by default, so it must be explicitly enabled for this feature to be used.

SetStandardizeCasing #

Syntax:: SetStandardizeCasing(bool);
Return Type:: Void

This function enables or disables the standardize casing function of Email Object.

If the Boolean value passed to this function is TRUE, Email Object will set the email address passed to the VerifyEmail function to all lowercase letters. For example, “JSmith@MelissaData.com” would become “jsmith@melissadata.com.”

The Standardize Casing feature is enabled by default.

SetUpdateDomain #

Syntax:: SetUpdateDomain(bool);
Return Type:: Void

This function enables or disables the domain update functionality of Email Object.

If the Boolean value passed to this function is set to TRUE, Email Object will attempt to update the domain name of the email address. One domain name can replace another in cases such as a change in corporate ownership. For example, the domain of subscribers to the @Home cable internet service was switched from “home.com” to “cox.net.”

The Update Domain feature is enabled by default.

Verify the Email Address #

The VerifyEmail function passes the submitted email address through Email Object’s verification routines.

VerifyEmail #

Syntax:: VerifyEmail(String_EmailAddress);
Returns:: Is Email Valid
Return Type:: Boolean

Launches Email Object’s verification and correction routines on the submitted email address.

The VerifyEmail function performs some or all of the following processes on the submitted email addresses, based on the settings passed to the SetCorrectSyntax, SetUpdateDomain, SetDatabaseLookup, SetFuzzyLookup, and SetStandardizeCasing functions:

Correct Syntax - Removes illegal characters and corrects misspelled domain names and top-level domain names. This function can be enabled or disabled using the SetCorrectSyntax function.
Update Domain Name - If one domain name has been superseded by another for any reason, VerifyEmail will replace the old name with the new name, if the value passed to the SetUpdateDomain function is TRUE.
Lookup Domain Name - Email object can attempt to validate the domain name of an email address in many ways. Assuming the SetDatabaseLookup function is set to TRUE, it will check the name against Email Object’s own database of known valid and invalid domain names. The object will also attempt to apply a fuzzy algorithm to validate the domain, a Melissa Data web server of compiled domains, and an MX lookup via a DNS Server, if the following options are also set to TRUE - SetFuzzyLookup, SetWSLookup, and SetMXLookup respectively. Check the value returned by the GetResults function to see the results of these attempts to verify the validity of the domain name.
Standardize Casing - Email Object can also switch all alphabetic characters in the email address to lower case, assuming that the value passed to the SetStandardizeCasing function is TRUE.
Result Codes - Check the output of the GetResults function (page 19) after calling VerifyEmail. Result codes indicate the validity of the submitted email address, the reason for any errors, and any changes made to correct the submitted address.
Configuration Files - Email Object’s syntax correction, domain updating, and domain verification routines can be overridden via the mdEmail.cfg file. This is a plain text file, which allows you to add, remove, or override some of Email Object’s default mdEmail.db3 tables.

Input Parameters: This function has one input parameter, a string containing the complete email address that you wish to verify and, optionally, correct and update.
Return Value: This function returns TRUE if the email address, including any corrections, is valid. Returns FALSE if not.

Retrieve the Status Information #

The following functions return general information about the success or failure of the last call to the VerifyEmail function.

GetResults #

Syntax:: GetResults();
Returns:: Result Codes
Return Type:: String

This function returns a comma-delimited string of four-character codes which detail the level of matching found for the current email address and any errors that occurred during the last call to the VerifyEmail function.

This is intended to replace the GetStatusCode (Deprecated) and GetErrorCode (Deprecated) functions, providing a single source of information about the last VerifyEmail call and eliminating the need to call multiple functions to determine if a particular email address was verified.

The function returns one or more of the result codes in a comma-delimited list.

GetResultCodeDescription #

Syntax:: GetResultCodeDescription(String_ResultCode, ResultCdDescOpt);
Returns:: Result Code Description
Return Type:: String

This function returns the description of the inputted Result Code. It can only be used through the Standard DLL.

It requires two values to be passed in, a Result Code and an enumerated option. If a string of Result Codes are inputted, only the first code will be used. The enumerated option will determine whether a short or long description will be returned.

ResultCdDescOp

Enumerated Value	Integer Value	Description
ResultCodeDescriptionLong	0	Returns a detailed description of the inputted result code.
ResultCodeDescriptionShort	1	Returns a brief description of the inputted result code.

Retrieve the Email Address Data #

The following functions return the detailed information on the last email address passed to the VerifyEmail function.

GetDomainName #

Syntax:: GetDomainName();
Returns:: Domain Name
Return Type:: String

This function returns the domain name portion of the email address passed to the VerifyEmail function, excluding the top-level domain, including any changes or corrections that have been made by Email Object. To get the full domain name, combine the results of this function with a “.” character and the return value of the GetTopLevelDomain function.

This 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 function just returns “melissadata.”

GetEmailAddress #

Syntax:: GetEmailAddress();
Returns:: Email Address
Return Type:: String

This function returns the email address passed to the VerifyEmail function, including any changes or corrections that have been made by Email Object.

If the VerifyEmail function returns a FALSE result, indicating an error, this function will contain the original text string passed to that function.

GetMailBoxName #

Syntax:: GetMailBoxName();
Returns:: Mailbox Name
Return Type:: String

This function returns the mailbox or user name portion of the email address passed to the VerifyEmail function, including any changes or corrections that have been made by Email Object.

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

GetTopLevelDomain #

Syntax:: GetTopLevelDomain();
Returns:: Top Level Domain
Return Type:: String

This function returns the top-level domain name portion of the email address passed to the VerifyEmail function, including any changes or corrections that have been made by Email Object.

This 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 function just returns “com.”

GetTopLevelDomainDescription #

Syntax:: GetTopLevelDomainDescription();
Returns:: Top Level Domain Description
Return Type:: String

This function returns the long-form description of the top-level domain name portion of the email address passed to the VerifyEmail function. This description is found in the mdEmail.db3 data file and can be modified in the [Tld] section of the mdEmail.cfg file.

This returns a string value containing the long form description of the top-level domain name portion of the corrected email address.

Deprecated/Obsolete Functions #

The following functions are recorded here for compatability and archiving purposes. Alternative functions should be used in practice.

GetChangeCode (Deprecated)#

Syntax:: GetChangeCode();
Returns:: Changes Made
Return Type:: IntegerValue

This function returns a single integer value which indicates what changes, if any, have been performed on the submitted email address.

This function has been deprecated. You should use the GetResults function instead.

This returns a single integer value to indicate if the submitted email address has been changed and what changes have been made.

To use this function’s value, use an AND operator to compare the value to the table below.

Integer	Indicates	Bit
0	No change
1	Syntax changed	1
2	Top-level domain changed	2
4	Domain changed (spelling correction)	3
8	Domain changed (updated domain)	4

For example, if the expression object.ChangeCode AND 8 evaluates to TRUE, that means the domain name has changed due to the domain itself being updated.

GetErrorCode (Deprecated)#

Syntax:: GetErrorCode();
Returns:: Error Code
Return Type:: String

This function returns the error code, a one-character string value, after an unsuccessful call to the VerifyEmail function.

This function has been deprecated. You should use the GetResults function instead.

Possible return values from the GetErrorCode function are:

Code	Description
Empty	No error
I	Email Object is not initialized
S	Syntax error
T	Top Level domain not found
M	Mail server not found
B	Invalid Mailbox

The “S” code (syntax error) will be returned if:

There is a syntax error in the submitted email address and the Correct Syntax feature is disabled.
There is an error that Email Object cannot correct, such as a missing mail box name, domain or top- level domain or no “@” character.

If the VerifyEmail function has not been called, or resulted in no error, this function will be empty.

GetErrorString (Deprecated)#

Syntax:: GetErrorString();
Returns:: Error Description
Return Type:: String

This function returns a description of any errors after an unsuccessful call to the VerifyEmail function.

This function has been deprecated. You should use the GetResults function instead.

Possible return values from the ErrorString function are:

Code	Description
Empty	No error
I	Email Object is not initialized
S	Syntax error
T	Top Level domain not found
M	Mail server not found
B	Invalid Mailbox

If the VerifyEmail function has not been called, or resulted in no error, this function will be empty.

GetStatusCode (Deprecated)#

Syntax:: GetStatusCode();
Returns:: Status Code
Return Type:: String

This function returns the status code, a one-character string value, after a call to the VerifyEmail function.

This function has been deprecated. You should use the GetResults function instead. See page 13 for documentation on this function.

Possible return values from the GetStatusCode function are:

Code	Definition
V	Verified email address. The domain name of the submitted email address was confirmed as valid by either the DatabaseLookup or MXLookup.
U	Unverified email address. The domain name of the submitted email address was not confirmed as valid by either DatabaseLookup, but was not found on the list of invalid domain names.
X	Bad email address. The domain name of the submitted email address was either not located by MXLookup or was located on the list of invalid domains.
empty	Verification not performed. This usually results when an error has prevented a successful call to the VerifyEmail function.

An “X” value would be returned if neither the SetDatabaseLookup nor the SetMXLookup functions are set to TRUE and the submitted email address contains syntax errors that were not corrected.

A “V” value would be returned if neither the SetDatabaseLookup nor the SetMXLookup functions are set to TRUE and the submitted email address contains no syntax errors.

SetCachePath (Obsolete)#

Syntax:: SetCachePath(string);
Return Type:: Void

This function is obsolete and no longer works.

This function sets the path for the directory where Email Object will write temporary cache files. If this is not set and SetCacheUse is turned on, Email Object will place the cache files in the local folder (Unix) or the default temporary folder (Windows).

SetCacheUse (Obsolete)#

Syntax:: SetCacheUse(int);
Return Type:: Void

This function is obsolete and no longer works.

This function enables or disables the use of temporary cache files within Email Object. These cache files are used to store domains that have already been checked to speed up processing time. It is highly recommended that this feature it turned on.

There are also two other ways to turn off or on cache files:

You may also turn off the cache files by using the environment variable SUPPRESS_MDEMAIL_CACHE and setting its value to 1. This will override whatever is set by SetCacheUse and the CachePath setting.

The default value for this method is 1.

If the integer value passed to this function is 1, Email Object will use the cache files.

If the integer value passed to this function is 0, Email Object will not use the cache files.

SetMXLookup (Obsolete)#

Syntax:: SetMXLookup(bool);
Return Type:: Void

This function is obsolete and no longer works.

This function enables or disables the DNS lookup validation function of Email Object.

If the Boolean value passed to this function is TRUE, Email Object will attempt to validate the email address passed to the VerifyEmail function by attempting to locate an MX (Mail Exchange) record or an A (Address Name) record for the domain on a DNS server. This is slower than a database lookup but potentially more accurate if the domain name is either obscure or new.

The results of this check will set the return value of the GetResults function. Domain names that cannot be verified by an MX Lookup will return a code for “bad email address.”

The MX Lookup feature is disabled by default, so it must be explicitly enabled for this feature to be used.

SetWSLookup (Obsolete)#

Syntax:: SetWSLookup(bool);
Return Type:: Void

This function is obsolete and no longer works.

This function enables or disables the Melissa Data server lookup validation function of Email Object.

If the Boolean value passed to this function is TRUE, Email Object will attempt to validate the email address passed to the VerifyEmail function by attempting to locate the domain from a compiled and continuously updated list of valid domains. This is slower than a database lookup but potentially more accurate if the domain name is either obscure, new, or no longer valid.

The results of this check will set the return value of the GetResults function. Domain names that cannot be verified by an WS Lookup will return a code for “Unverified email address.”

The WS Lookup feature is disabled by default, so it must be explicitly enabled for this feature to be used.

SetWSMailboxLookup (Obsolete)#

Syntax:: SetWSMailboxLookup(bool);
Return Type:: Void

This function is obsolete and no longer works.

This function enables or disables the mailbox validation functionality of Email Object. With this option, the Email Object will make a call to our Global Email Web Service to verify the email address in its entirety (mailbox, domain, top-level domain).

There are three available enums to set this option to:

Enumerated Value	Int Value	Definition
None (Default)	0	This will disable mailbox validation. Domain and top-level domain check still enabled.
MailboxExpress	1	This will quickly validate against a database of known email addresses.
MailboxPremium	2	This will perform a real-time, live validation of the email address.

The WS MailboxLookup feature requires access to the Melissa Data web services. If you are under a firewall or have limited internet access, you may need to contact your IT department in order to get this feature working.

This functionality also requires a license string that is enabled for web service calls. Please contact your Melissa Data Sales Representative to enable or confirm your service subscriptions.

Result Codes #

For details of all result codes please visit here

ES - Email Status #

Code	Short Description	Long Description
`ES01`	Valid Email	This email was confirmed to be a valid email.
`ES02`	Invalid Email	This email was confirmed to be a invalid email.
`ES03`	Unknown Email	This email’s status is unknown due to unknown external factors. Please try again another time.
`ES04`	Mobile Email Address	The domain name was identified as a mobile email address and classified as not deliverable by the FCC.
`ES05`	Disposable Domain	The domain name of the submitted email was identified as a disposable domain.
`ES06`	Spamtrap Domain	The domain name of the submitted email was identified as a spamtrap. Mailing to this domain could result in the sender being blacklisted.
`ES10`	Syntax Changed	The syntax of the submitted email address was changed.
`ES11`	Top Level Domain Changed	The top level domain of the submitted email address was changed.
`ES12`	Domain Changed (Spelling)	The domain of the submitted email address was corrected for spelling.
`ES13`	Domain Changed (Update)	The domain of the submitted email address was updated due to a domain name change.

EE - Email Error #

Code	Short Description	Long Description
`EE01`	Email Syntax Error	There is a syntax error in the submitted email address.
`EE02`	Email Domain Not Found	A Domain of the submitted email address was not found.
`EE03`	Email Server Not Found	The mail server of the submitted email address was not found.
`EE04`	Invalid Email	An invalid mailbox was detected (i.e. noreply).
`EE05`	Email Object not Initialized	Email Object was not initialized properly. Please review your code and data files.

GW - General Transmission Warning #

Code	Short Description	Long Description
`GW01`	Expiring License	Your License Key is expiring soon. Please contact your sales representative for a new License Key.
`GW02`	Usage Report Warning	Unable to report usage. Object will still continue to operate.
`GW03`	Usage Report Error	Unable to report usage. Warning time exceeded. Object will not continue to operate.
`GW04`	Web Service Communication Error	Unable to communicate with the web service to complete the requested call. Please double check any connections issues (e.g. proxy, firewall) and try again.
`GW05`	Web Service Subscription Inactive	An active web service subscription is required to complete the request call but could not be found. Please contact your sales representative to activate.

Reference Guide

Contents

Reference Guide#