Difference between revisions of "Global Email:Best Practices"

From Melissa Data Wiki
Jump to navigation Jump to search
(Created page with "← Global Email V4 ==Accessing Melissa cloud services and staying up to date== Melissa Cloud Services are authenticated using a License Key. The Licens...")
 
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[Global Email V4|← Global Email V4]]
{{GlobalEmailV4Nav
==Accessing Melissa cloud services and staying up to date==
|BasicsCollapse=
Melissa Cloud Services are authenticated using a License Key. The License Key is provided to you by your customer service representative or through an automatically generated email after signing up for a promotional demo.
}}


{{CustomTOC}}


Due to the nature of our business and our commitment to improving our services, sometimes there will be changes. We strongly recommend you create an email distribution group address for several technical users in your organization, that will be responsible for consuming our services, and convey that email address to your Melissa customer service representative. This email address will be used in case we need to notify you of upcoming change either to the service, the data or the network infrastructure. Also kindly add melissadata.com to your domain whitelist so this vital communication is not blocked.
==Watch your email reputation==
Email marketing campaign servers with a low email reputation score will typically experience aggressive algorithms that will filter every email coming from that specific IP address. On the other hand, maintaining a high reputation score will see less intrusive filtering only applied to individual emails and email campaigns instead of blanket IP addresses. It would be definitely beneficial to not let other users to influence your email reputation. For example, if you are on a shared server  – other companies/users could be sending out their own campaigns without filtering emails through our service. It would be a waste if you spent all the time and investment controlling your email campaigns and someone else is just email blasting causing the entire IP to be affected.


==Improve your email reputation==
After using our service to filter out emails, if the scores are already terrible for your current email campaign server IPs, it might benefit to do email campaigns on a new or more reputable IP to see better ROI. This would start your email reputation on a clean slate. As a disclaimer, we are not sure how feasible this would be for everybody but your team will need to discuss internally. However, using our service on existing IP should raise the reputation score for that specific IP. On IPs with existing completed high volume campaigns, the scores will be slow to change.


==Single Record vs Batch Processing==
==Result Code Best Practices==
Melissa cloud services are capable of both single record real-time processing and batch processing. The difference is simply in the number of records sent in each request. Melissa cloud services take an array of records. This array can contain a single record or 100 records. For a real time process like a web form entry or a call center application, send in a request with one record. For batch processing scenario like a database, send requests of up to 100 records until all the records are processed.  
There are two main use cases for Global Email result codes.


#Validating emails at the point of entry on a web entry form
#Sending bulk emails in a marketing campaign.


==Error Handling==
Each case will require their own set of standards, and a different approach. Provided below is our recommendation on how to treat specific result codes.
Since Melissa uses multiple clustered servers, in the unlikely event that one server is temporarily overloaded or down, it is very likely that another server is up and running. For this reason, it is best to catch any errors returned by the service and retry. We recommend retrying up to 5 times.


<pre>
:'''Accept''' – Send mail. There is a high chance of email delivery success.
int Retry = 0;
:'''Caution''' – Email delivery not guaranteed.
Boolean ReqRet = false;
:'''Reject''' – Do not send.
do
{
  try
  {
    // Perform Phone Lookup and store results to the Response
    ResPhone = PhoneClient.doPhoneCheck(ReqPhone);
    ReqRet = true;
  }
  catch (Exception ex)
  {
    MessageBox.Show(ex.ToString());
    Retry++;
  }
} while ((ReqRet == false) && (Retry < 5));2
</pre>


These recommendations are to be used as a reference, and each case may vary from user to user.


==Network Layer Considerations==
{| class="alternate01 sortable"
===IP Addresses===
!Code!!Meaning!!Detail!!colspan="2"|Melissa Recommendation
If your company uses a firewall for security, you will need to add our IP address ranges to your list of allowable IP addresses in order to communicate with our cloud services. Please see this page:
|-
 
!colspan="3" style="background-color:#c3c3c3;"|ES-Email Status!!style="background-color:#c3c3c3;"|Email Marketing Campaign!!style="background-color:#c3c3c3;"|Point of Entry
<pre>
|-
http://www.melissadata.com/tech/webservices-ip-information.htm
|ES01||Valid Email||This email was confirmed to be a valid email.||style="background-color:#c6e0b4;"|Accept||style="background-color:#c6e0b4;"|Accept
</pre>
 
We give out best effort to plan ahead and allocated IP ranges for the future, however, it is possible that we will need to add IP ranges as we expand and upgrade or infrastructure. We will send out multiple notifications of any impending update. This is a reason to make sure you have your technical contacts registered with Melissa.
(See [[#Accessing Melissa cloud services and staying up to date|Accessing Melissa Cloud Services]]).
 
===Ports===
We use the default ports of 80 for http and 443 for https.
 
===Using specific IP’s===
We do not allow you to access our services using direct IP addresses. We have multiple server clusters and use a load balancing system to distribute incoming traffic. To update our servers, we have to periodically need to take them down and redistribute traffic to available servers.
 
===TTL===
To update a server, we take it off of our load balancer and let it drain of traffic. Then, we stop the cloud service and update the server. People accessing the service using our domain name will automatically be directed to available servers only. However, if your DNS caches the resolved IP address for a significant length of time, it is possible the cached server will be down when you try to hit it. For this reason, if you have access to your DNS TTL (time to live) option, please set it to a value of 10 minutes or less.
 
 
==Speed Considerations==
If speed is a top concern for you, there are a few strategies that can be employed to increase the normal speed of using the service. They are ranked in terms of least effective to most effective.
 
===Use batch instead of single===
Processing <span style="color:red;">**</span>100 records at a time will always have a faster per record speed than a single record.
 
<span style="color:red;"><nowiki>**</nowiki></span>The exception to this rule is Global Email. If you are using Global Email in Premium Mode, we recommend a max of 10 records. If you attempt to do 100 records at a time with Global Email in Premium mode, it will break apart the records and in effect slow down the process.
 
===Order by Zip code===
Ordering the records by zip code within each request can have a small increase the speed of the request.
 
===Compression===
For our services that allow GZip compression, turning it on can have up to a 10% increase in speed. GZip is usually built into a programming language and turned on simply by a flag.
 
===Multi-Threading===
Increasing the number of threads is an effective way to quickly increase the speed of using our services. We recommend having between 3-5 threads for batch processing.
 
===Contact Verification Server===
For our enterprise customers with speed and/or privacy concerns, we can make available a local server hosting our cloud services. This server is dedicated to you so that you are not sharing server resources with anyone else. Additionally, since the server is located within your organization, the data does not have to travel over long distances. Also, authentication is turned off to further increase speed. Contact your sales representative if you are interested in this solution.
 
 
==Understanding the different protocols XML vs REST vs JSON==
Our cloud services are available in multiple protocols in order to provide our customers a wide range of technologies to fit into their current architecture. The terminologies used above (XML, REST, JSON) are not strictly technologically accurate, but used to differentiate the different options available. In the end, all the protocols return the same data, so the choice is really one of programming preference.
 
===XML===
XML is a HTTP POST call where you send in a request in xml format and receive a response in xml format. The format of the request must follow the structure defined in our documentation for each specific service.
 
===JSON===
JSON is also a HTTP POST call just like XML. The only difference is that the request and response uses the JSON format instead of XML format.
 
===REST===
REST is a HTTP GET call. This allows you to quickly formulate a call within the URL and submit it through a browser. An example of a REST call:
 
<pre>
https://personator.melissadata.net/v3/WEB/ContactVerify/
doContactVerify?&id=123456&act=Check&a1=22382%20avenida
%20empresa&postal=92688
</pre>
 
The returned response is in XML and is identical to what is returned by the XML HTTP POST call.
 
Only one record can use sent using a REST call so it is ideal for real time single record processing.
 
 
==Special Character Handling==
The XML and REST protocols require special character handling when creating your request and interpreting the response. This is because certain special characters are reserved within the XML language.
 
===XML Encoding===
The following XML encoding should be implemented to correctly handle reserved special characters:
{|class="alternate01" cellspacing="0"
!Character
!style="border-right:0px;"|Encoding
|-
|-
|&
|ES02||Invalid Email||This email was confirmed to be a invalid email.||style="background-color:#ff9999;"|Reject||style="background-color:#ff9999;"|Reject
|&amp; (ampersand)
|-
|-
|“
|ES03||Unknown Email||This email's status is unknown due to unknown external factors. Please try again another time.||style="background-color:#ff9999;"|Reject||style="background-color:#ffffcc;"|Caution
|" (left/right quotes should be replaced with straight quotes)
|-
|-
|‘
|ES04||Mobile Email Address||The domain name was identified as a mobile email address and classified as not deliverable by the FCC.||style="background-color:#ff9999;"|Reject||style="background-color:#c6e0b4;"|Accept
|&apos; (apostrophe)
|-
|-
|<
|ES05||Disposable Domain||The domain name of the submitted email was identified as a disposable domain.||style="background-color:#ff9999;"|Reject||style="background-color:#ffffcc;"|Caution
|&lt; (less-than)
|-
|-
|>
|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.||style="background-color:#ff9999;"|Reject||style="background-color:#ffffcc;"|Caution
|&gt; (greater-than)
|}
 
 
===URL Encoding===
The following URL encoding should be implemented when using REST to correctly handle reserved special characters:
{|class="alternate01" cellspacing="0"
!Character
!style="border-right:0px;"|Encoding
|-
|-
|[Space]
|ES07||Accept All Server||The mail server is an accept all server. Accept-All domains is set in a way that makes all emails seem valid.||style="background-color:#ffffcc;"|Caution||style="background-color:#c6e0b4;"|Accept
|%20 or +
|-
|-
|*
|ES08||Role Address||This Email address was created as a group, ex: sales@, support@, or postmaster@.||style="background-color:#ffffcc;"|Caution||style="background-color:#c6e0b4;"|Accept
|%2A
|-
|-
|#
|ES09||Protected Mailbox Caution||The mail provider for this email address may be quick to classify senders as spam and will not respond to our requests. Mailbox validation is not possible at this time and the mailbox may or may not exist. We recommend proceeding with caution if emailing numerous records to this mail domain.||style="background-color:#ffffcc;"|Caution||style="background-color:#c6e0b4;"|Accept
|%23
|-
|-
|&
|ES10||Syntax Changed||The syntax of the submitted email address was changed.||style="background-color:#c6e0b4;"|Accept||style="background-color:#c6e0b4;"|Accept
|%26
|-
|-
|%
|ES11||Top Level Domain Changed||The top level domain of the submitted email address was changed.||style="background-color:#c6e0b4;"|Accept||style="background-color:#c6e0b4;"|Accept
|%25
|-
|-
|$
|ES12||Domain Changed (Spelling)||The domain of the submitted email address was corrected for spelling.||style="background-color:#c6e0b4;"|Accept||style="background-color:#c6e0b4;"|Accept
|%28
|-
|-
|`
|ES13||Domain Changed (Update)||The domain of the submitted email address was updated due to a domain name change.||style="background-color:#c6e0b4;"|Accept||style="background-color:#c6e0b4;"|Accept
|%60
|-
|-
|:
|ES20||Verify (Precision: Domain Result)||The email is considered valid, but did not have the mailbox verified and not found in our mailbox database.||style="background-color:#ffffcc;"|Caution||style="background-color:#c6e0b4;"|Accept
|%3A
|-
|-
|<
|ES21||Verify (Precision: Cached Mailbox Result)||The email status was found in our database of cached emails.||style="background-color:#c6e0b4;"|Accept||style="background-color:#c6e0b4;"|Accept
|%3C
|-
|-
|>
|ES22||Verify (Precision: Real-time Mailbox Result)||The mailbox validation was performed in real-time.||style="background-color:#c6e0b4;"|Accept||style="background-color:#c6e0b4;"|Accept
|%3E
|-
|-
|[
|ES23||Verify (Precision: Unicode Result)||Unicode Detected: We do not support Unicode at this time for realtime mailbox validation. Domain and cache check only.||style="background-color:#ffffcc;"|Caution||style="background-color:#c6e0b4;"|Accept
|%5B
|-
|-
|]
|ES24||Verify (Precision: Pending Mailbox Result)||The mail provider has been known to send a delayed response so it is possible that the pending status will change within the next 24 hours. You may want to resubmit this input at a later time as an update may be possible.||style="background-color:#ffffcc;"|Caution||style="background-color:#c6e0b4;"|Accept
|%5D
|-
|-
|{
!colspan="5" style="background-color:#c3c3c3;"|EE - Email Error
|%7B
|-
|-
|<nowiki>}</nowiki>
|EE01||Syntax Error||There is a syntax error in the submitted email address.||style="background-color:#ff9999;"|Reject||style="background-color:#ff9999;"|Reject
|%7D
|-
|-
|“
|EE02||A Domain Not Found||A Domain of the submitted email address was not found.||style="background-color:#ff9999;"|Reject||style="background-color:#ff9999;"|Reject
|%22
|-
|-
|<nowiki>+</nowiki>
|EE03||Mail Server Not Found||The mail server of the submitted email address was not found.||style="background-color:#ff9999;"|Reject||style="background-color:#ff9999;"|Reject
|%2B
|-
|-
|(
|EE04||Invalid Mailbox||An invalid mailbox was detected (i.e. noreply).||style="background-color:#ff9999;"|Reject||style="background-color:#ff9999;"|Reject
|%28
|-
|-
|)
!colspan="5" style="background-color:#c3c3c3;"|SE - Transmission Service Error
|%29
|-
|-
|.
|SE01||Cloud Service Internal Error||The cloud service experienced an internal error.||style="background-color:#ff9999;"|Reject||style="background-color:#ff9999;"|Reject
|%2E
|-
|-
|!
!colspan="5" style="background-color:#c3c3c3;"|GE - General Transmission Error
|%21
|-
|-
|@
|GE01||Empty Request Structure||The SOAP, JSON, or XML request structure is empty. Not to be confused with the GE01 GeoCode result code.||style="background-color:#ff9999;"|Reject||style="background-color:#ff9999;"|Reject
|%40
|-
|-
|/
|GE02||Empty Request Record Structure||The SOAP, JSON, or XML request record structure is empty. Not to be confused with the GE02 GeoCode result code.||style="background-color:#ff9999;"|Reject||style="background-color:#ff9999;"|Reject
|%2F
|-
|-
|;
|GE03||Records Per Request Exceeded||The counted records sent more than the number of records allowed per request.||style="background-color:#ff9999;"|Reject||style="background-color:#ff9999;"|Reject
|%3B
|-
|-
|=
|GE04||Empty License Key||The License Key is empty.||style="background-color:#ff9999;"|Reject||style="background-color:#ff9999;"|Reject
|%3D
|-
|-
|?
|GE05||Invalid License Key||The License Key is invalid.||style="background-color:#ff9999;"|Reject||style="background-color:#ff9999;"|Reject
|%3F
|-
|-
|\
|GE06||Disabled License Key||The License Key is disabled.||style="background-color:#ff9999;"|Reject||style="background-color:#ff9999;"|Reject
|%5C
|-
|-
|^
|GE07||Invalid Request||The SOAP, JSON, or XML request is invalid.||style="background-color:#ff9999;"|Reject||style="background-color:#ff9999;"|Reject
|%5E
|-
|-
|<nowiki>|</nowiki>
|GE08||Product/Level Not Enabled||The License Key is invalid for this product or level.||style="background-color:#ff9999;"|Reject||style="background-color:#ff9999;"|Reject
|%7C
|-
|-
|~
|GE09||Customer Does Not Exist||The Customer ID is not in our system.||style="background-color:#ff9999;"|Reject||style="background-color:#ff9999;"|Reject
|%7E
|-
|-
|‘
|GE10||Customer License Disabled||The encrypted license is on the ban list.||style="background-color:#ff9999;"|Reject||style="background-color:#ff9999;"|Reject
|%27
|-
|-
|,
|GE11||Customer Disabled||The Customer ID is disabled.||style="background-color:#ff9999;"|Reject||style="background-color:#ff9999;"|Reject
|%2C
|-
|-
|<nowiki>-</nowiki>
|GE12||IP Blacklisted||The IP Address is on the global ban list.||style="background-color:#ff9999;"|Reject||style="background-color:#ff9999;"|Reject
|%2D
|-
|-
|_
|GE13||IP Not Whitelisted||The IP Address is not on the customer's whitelist.||style="background-color:#ff9999;"|Reject||style="background-color:#ff9999;"|Reject
|%5F
|}
|}




==Reporting Errors==
[[Category:Global Email V4]]
If you are experiencing errors trying to connect to our cloud services or interruptions to the service, you can:
 
#Submit a support ticket at support.melissadata.com.
#Call Tech Support at 1-800-800-6245 ext 4.
 
 
If you are experiencing a sudden loss of service, please be ready to provide us with as much of the following pieces of information so that we can assist you promptly and investigate thoroughly.
*Your License Key
*The location of your server accessing the cloud service
*The URL of the cloud service you are using
*The type of error you are experiencing in detail
*Any error messages or logs you may have
*Date and time of occurrences
*Behavior of the incidents (is it all the time or periodic. If peridoc, what percentage of requests are affect).
*What is your IP Address?
*Are you using a proxy or firewall?
*Any other information you think may be relevant
 
 
==Output Considerations==
Melissa Cloud Services are constantly undergoing improvements and additions. As the products evolve, the format of the output may change as features are added to each of the services. This does not mean that the current elements or element names will be subject to sudden change, as this is considered bad practice, but that additional possible elements may be added to the products. We reserve the right to add these additional features in order to improve and advance our products to meet customer needs.
 
In terms of cloud services, many of our services tend to offer an option to return back all available outputs, usually denoted with something like a “GrpAll” option. As a result of this option, certain problems in handling the output of may arise. When a new field might be added to the service, the response would contain this new field when all the elements are called to return. This could conflict with the often static schema in which outputs are generally parsed - for all formats, be it JSON, or XML. Our services require that the parsing of the response can be dynamic in its allocation of the output, in order to avoid this error. In order to have true static output and avoid the possibility of this error, we recommend that each of the desired output columns is listed in the request individually.
 
 
[[Category:Cloud Services]]
[[Category:Best Practices]]
[[Category:Best Practices]]

Latest revision as of 16:51, 26 August 2020

← Global Email

Global Email Navigation
Basics
Introduction
Licensing
Domain-Only Verification
Privacy and Global Email
Best Practices
FAQ
Service URLs
Input/Output
Request Fields
Response Fields
Examples
REST JSON
REST JSONP
REST XML
Batch XML
Batch JSON
Interpreting Results
Deliverability Confidence Score (Basic)
Result Codes (Advanced)
Global Email Result Codes
Sample Code



Watch your email reputation

Email marketing campaign servers with a low email reputation score will typically experience aggressive algorithms that will filter every email coming from that specific IP address. On the other hand, maintaining a high reputation score will see less intrusive filtering only applied to individual emails and email campaigns instead of blanket IP addresses. It would be definitely beneficial to not let other users to influence your email reputation. For example, if you are on a shared server – other companies/users could be sending out their own campaigns without filtering emails through our service. It would be a waste if you spent all the time and investment controlling your email campaigns and someone else is just email blasting causing the entire IP to be affected.

Improve your email reputation

After using our service to filter out emails, if the scores are already terrible for your current email campaign server IPs, it might benefit to do email campaigns on a new or more reputable IP to see better ROI. This would start your email reputation on a clean slate. As a disclaimer, we are not sure how feasible this would be for everybody but your team will need to discuss internally. However, using our service on existing IP should raise the reputation score for that specific IP. On IPs with existing completed high volume campaigns, the scores will be slow to change.

Result Code Best Practices

There are two main use cases for Global Email result codes.

  1. Validating emails at the point of entry on a web entry form
  2. Sending bulk emails in a marketing campaign.

Each case will require their own set of standards, and a different approach. Provided below is our recommendation on how to treat specific result codes.

Accept – Send mail. There is a high chance of email delivery success.
Caution – Email delivery not guaranteed.
Reject – Do not send.

These recommendations are to be used as a reference, and each case may vary from user to user.

Code Meaning Detail Melissa Recommendation
ES-Email Status Email Marketing Campaign Point of Entry
ES01 Valid Email This email was confirmed to be a valid email. Accept Accept
ES02 Invalid Email This email was confirmed to be a invalid email. Reject Reject
ES03 Unknown Email This email's status is unknown due to unknown external factors. Please try again another time. Reject Caution
ES04 Mobile Email Address The domain name was identified as a mobile email address and classified as not deliverable by the FCC. Reject Accept
ES05 Disposable Domain The domain name of the submitted email was identified as a disposable domain. Reject Caution
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. Reject Caution
ES07 Accept All Server The mail server is an accept all server. Accept-All domains is set in a way that makes all emails seem valid. Caution Accept
ES08 Role Address This Email address was created as a group, ex: sales@, support@, or postmaster@. Caution Accept
ES09 Protected Mailbox Caution The mail provider for this email address may be quick to classify senders as spam and will not respond to our requests. Mailbox validation is not possible at this time and the mailbox may or may not exist. We recommend proceeding with caution if emailing numerous records to this mail domain. Caution Accept
ES10 Syntax Changed The syntax of the submitted email address was changed. Accept Accept
ES11 Top Level Domain Changed The top level domain of the submitted email address was changed. Accept Accept
ES12 Domain Changed (Spelling) The domain of the submitted email address was corrected for spelling. Accept Accept
ES13 Domain Changed (Update) The domain of the submitted email address was updated due to a domain name change. Accept Accept
ES20 Verify (Precision: Domain Result) The email is considered valid, but did not have the mailbox verified and not found in our mailbox database. Caution Accept
ES21 Verify (Precision: Cached Mailbox Result) The email status was found in our database of cached emails. Accept Accept
ES22 Verify (Precision: Real-time Mailbox Result) The mailbox validation was performed in real-time. Accept Accept
ES23 Verify (Precision: Unicode Result) Unicode Detected: We do not support Unicode at this time for realtime mailbox validation. Domain and cache check only. Caution Accept
ES24 Verify (Precision: Pending Mailbox Result) The mail provider has been known to send a delayed response so it is possible that the pending status will change within the next 24 hours. You may want to resubmit this input at a later time as an update may be possible. Caution Accept
EE - Email Error
EE01 Syntax Error There is a syntax error in the submitted email address. Reject Reject
EE02 A Domain Not Found A Domain of the submitted email address was not found. Reject Reject
EE03 Mail Server Not Found The mail server of the submitted email address was not found. Reject Reject
EE04 Invalid Mailbox An invalid mailbox was detected (i.e. noreply). Reject Reject
SE - Transmission Service Error
SE01 Cloud Service Internal Error The cloud service experienced an internal error. Reject Reject
GE - General Transmission Error
GE01 Empty Request Structure The SOAP, JSON, or XML request structure is empty. Not to be confused with the GE01 GeoCode result code. Reject Reject
GE02 Empty Request Record Structure The SOAP, JSON, or XML request record structure is empty. Not to be confused with the GE02 GeoCode result code. Reject Reject
GE03 Records Per Request Exceeded The counted records sent more than the number of records allowed per request. Reject Reject
GE04 Empty License Key The License Key is empty. Reject Reject
GE05 Invalid License Key The License Key is invalid. Reject Reject
GE06 Disabled License Key The License Key is disabled. Reject Reject
GE07 Invalid Request The SOAP, JSON, or XML request is invalid. Reject Reject
GE08 Product/Level Not Enabled The License Key is invalid for this product or level. Reject Reject
GE09 Customer Does Not Exist The Customer ID is not in our system. Reject Reject
GE10 Customer License Disabled The encrypted license is on the ban list. Reject Reject
GE11 Customer Disabled The Customer ID is disabled. Reject Reject
GE12 IP Blacklisted The IP Address is on the global ban list. Reject Reject
GE13 IP Not Whitelisted The IP Address is not on the customer's whitelist. Reject Reject
Retrieved from "http://wiki.melissadata.com/index.php?title=Global_Email:Best_Practices&oldid=17313"