Fieldpine Logo Documentation Home  

email.validate

This API verifies that an entered email is correct and can increase the success rate of data entry. It is designed to be called while the user is typing, but can also be called in onBlur or KillFocus routines to validate an entire string.


Validation performed by this API includes both static syntax conformance (is the structure correct to RFC requirements) and dynamic checks (does the mail server actually exist). It is intended to validate email addresses for the internet not in house email systems if they use dot less domains.

A valid email address only defines that the address is correct and can be used. It does not guarantee the person will actually receive the email. The complication with email is that only the final users machine can accurately say if an address is valid or not, and the only way to reliably do that check is to send the user an email. So unless you actually send the user an email there are no absolute guarantees that an email address is both valid and the user will receive the email

This validation API checks for conformance to RFC2822, but warns that some entered addresses may be invalid even if they are syntactically correct. The RFC supports a number of historic formats but these addresses are almost never seen in retail operation, so this API leans towards treating them as errors as the they are probably more typing mistakes. Overall the checks performed by this API are more detailed than simple regex checks.

Fieldpine Retailers are welcome to use fieldpine.com to perform realtime email address checking from their websites, but the availability of this service is not guaranteed or covered under support. Fieldpine.com servers may also impose rate limits and slow response times if high load is experienced.

Try it now

  

Request

Response


Input Specification

f100
Input email to validate.
f111
Input mask of tests to perform. When a mask is supplied, the missing tests may still be returned in the results, but the values are undefined
f121
Space representation. A flag to indicate that space characters in RedGreen field should be replaced by a different character set.

Examples:
Validate an email, return response in JSON

http://www.fieldpine.com/gnap/J/buck?3=email.validate&100=email@example.com

Validate email, return response in XML, and only perform a subset of tests

http://www.fieldpine.com/gnap/M/buck?3=email.validate&100=email@exampl&111=991

Output Specification

The response packet from the server may include the following fields

RootType
Indicates what is contained in this packet. This will be "DATS" if a valid reesponse is present, "QERR" if there is an error with the API call, or "ARAY" if multiple addresses where submitted
Email
The email address supplied to be checked
SyntaxOk
A 0 (false) or 1 (true) indicator showing if the email is of valid structure
DNSOk
A 0 (false) or 1 (true) indicator reporting if the domain name appears to be valid. This is performed by querying the DNS MX records, but does involve contacting the mail server directly.
ErrorText
A technical brief description of each error code
ErrorMask
Error codes returned as a bitmask. The same values are used as the ErrorList
ErrorList
Pipe seperated list of error codes.
RareSyntax
Set to 1 if the email contains characters or structure that is syntactically correct but rarely used. If this is set the user has probably made a typing mistake, but may have entered a valid address
TopDomainOk
Set to 1 if the top level domain is a valid ICANN domain.
SecondDomainOk
Set to 1 of the second level domain is valid for the first level. This check is not performed for all second level domains, only those were there is a published list. Most second level registrars do not supply this information in a useable format
OnBounceList
If set to 1, indicates we have tried to send to this email address already and received some form of bounce message. The email address should be double checked for correctness, especially the first part before the @ sign.
RedGreen
An array of strings in pairs designed to provide visual feedback to the user as they type. This shows them where the problems are precisely with what they have typed.

Example(s):

	["green","bob@example.com"]
	["green","bob","red","@","green","smith@example.com"]

See below for futher information on using this field

Message
A text message to be associated with the RedGreen field and providing additional detail. If multiple problem exist, this message field will only contain one problems message

RedGreen Field

This field is designed to make realtime feedback easy for client systems to implement. The RedGreen field contains a number of pairs in the form "Color|Text".

Example of how field might be used in Javascript. In this example, we convert the requested color "yellow" to be "orange", as yellow on white background can be hard to read

var rg = Reply.RedGreen;
var rga = new Array;
if (rg.length > 0) {

  // Loop for each pair (note how loop increases by 2)
  for (var ndx=0; ndx < rg.length; ndx+=2) {

    // Convert the requested color to what we wish to display
    var color = rg[ndx];
    if (color=='red') rga.push("<span style='color:red'>");
    if (color=='green') rga.push("<span style='color:green'>");
    if (color=='yellow') rga.push("<span style='color:orange'>");

    // Add the text
    rga.push(rg[ndx+1]);
    rga.push("</span>");
  }
}

// Display the HTML string, if any
document.getElementById("redgreen").innerHTML = rga.join("");
document.getElementById("redgreenmessage").innerHTML = eLink_ExtractStr(Reply, "Message", "");