LOGIN NAME:

PASSWORD:

:: XWebEmailValidation :: Implementation Guides ::

Validate Email Addresses In Real-Time on a Web Form

The procedures in this implementation guide require that you have some knowledge of ASP.NET web development with the Microsoft Visual Basic.NET development tool.

***Note: This implementation guide applies to Version 1 of the Web Service.

The steps in this "how-to" implementation guide are:

• Add a "Web Reference" to the XWebEmailValidation Web Service
• Add a "Web Form" to the web application
• Write code in the "Codebehind" of the web form to perform the real-time Email validation by consuming the XWebEmailValidation Web Service
• Implement an ASP.NET Form to submit the Email to be validated and display the validation result

To download the source code for this "how-to" implementation guide, as well as for additional hints and tips, please read our Final Notes.

Add a "Web Reference" to the XWebEmailValidation Web Service

• In your web project, add a Web Reference to the XWebEmailValidation Web Service. Here are 2 ways you can accomplish this:

  • Browse the Solution Explorer, right click on References and select Add Web Reference... from the drop down menu.
  • From the File Menu, select Project - Add Web Reference....

• The Add Web Reference pop-up window will open. In the URL textbox, enter the following URI:

  http://ws.xwebservices.com/XWebEmailValidation/XWebEmailValidation.asmx?wsdl

• Hit the Enter key or click the Go button located to the right of the URL textbox.
• Change the Web reference name to XWebEmailValidation for easier reference.
• Click the Add Reference button to complete this step.

Add a "Web Form" to the Web Application

• In your web project, add a Web Form. This Web Form will display validate the Email address in real-time and displaying the result. Here are 2 ways you can accomplish this:

  • Browse the Solution Explorer, right click the name of your project, and select Add - Add Web Form....
  • From the File Menu, select Project - Add Web Form....
• Change the Name textbox in the Add New Item pop-up provided to validate_email.aspx.

Write code in the "Codebehind" of the web form to perform the real-time Email validation by consuming the XWebEmailValidation Web Service

Based on the documentation for the XWebEmailValidation Web Service, in order to successfully consume the Web Service, we will need to authenticate first using SOAP Headers. Here's how:

• Open the "Codebehind" of the validate_email.aspx web form we added to the web project in the previous step.

• Since the Web Service requires SOAP Headers for authentication purposes, we must first create a new instance of the class representing the SOAP Header and then populate the SOAP Header values:

  ' handle authentication
  Dim objAuth As New XWebEmailValidation.AuthHeader
  objAuth.LoginName = "<my_login_name>"
  objAuth.Password = "<my_password>"

  NOTE***: Instead of hard-coding the LoginName and Password values, you may want to dynamically read them from the web.config file (LOGIN_NAME and PASSWORD must be added to the <AppSettings> section of the web.config file):

  objAuth.LoginName = System.Configuration.ConfigurationSettings.AppSettings("LOGIN_NAME")
  objAuth.Password = System.Configuration.ConfigurationSettings.AppSettings("PASSWORD")

• Next, we need to create a new instance of the proxy class and assign the SOAP Header object to the member variable of the proxy class representing the SOAP Header:

  'create the XWebEmailValidation Web Service proxy
  Dim objEV As New XWebEmailValidation.XWebEmailValidation
  objEV.AuthHeaderValue = objAuth

• We are now ready to call the method on the proxy class that communicates with the Web Service SOAP method, performs the real-time Email validation and returns the status we want displayed on the web page.

  'the Email to be validated is entered into a txtEmail textbox (see next step)
  'store the result in a variable
  Dim intResult As Integer = objEV.ValidateEmail(txtEmail.Text)

Implement an ASP.NET Form to submit the Email to be validated and display the validation result

In the Codebehind:

• Declare an ASP.NET textbox, an ASP.NET label and an ASP.NET button - the Email address will be entered into the textbox and the status result from the SOAP method will be displayed in the label when the button is clicked:

  Protected txtEmail As System.Web.UI.WebControls.TextBox
  Protected lblResult As System.Web.UI.WebControls.Label
  Protected WithEvents btnValidate As System.Web.UI.WebControls.Button

• In the previous step we passed the Email entered into the ASP.NET textbox as the input parameter to the SOAP method. The SOAP method result was stored in a variable, intResult. Since the result can only be one of five values, a simple Select Case will work just fine to display the result:

  Select Case intResult
    Case 1
      lblResult.Text = "1 - Email address is valid"
    Case 0
      lblResult.Text = "0 - Email address is not valid"
    Case -101
      lblResult.Text = "-101 - unable to establish communication with the Email server."
    Case -201
      lblResult.Text = "-201 - invalid domain / no Email server found for the domain."
    Case Else
      lblResult.Text = "-999 - system error."
  End Select

In the HTML Editor, we define an ASP.NET form, an ASP.NET textbox, an ASP.NET label and an ASP.NET button. Here is the code:

<Form Runat="server">
  <asp:TextBox ID="txtEmail" Runat="server" />
  <asp:Label ID="lblResult" Runat="server" />
  <asp:Button ID="btnValidate" Text="Validate" Runat="server" />
</Form>

Final Notes

The source code for this "how-to" implementation guide can be downloaded by clicking the link below (zip file)

XWebEmailValidationClient.zip

It's always good practice to implement a Try...Catch... error handling technique to handle some or all possible errors that may occur while the code is executing. We strongly recommend that you implement such a technique.