Email Validation API: A Practical DataSoap Integration Guide

An email validation API lets your application check an address during a workflow, instead of exporting a spreadsheet for a manual clean-up. It is useful when an address enters a form, before a CRM import completes or when an older record is about to be used.

This guide explains a server-side integration with DataSoap: choose the check, authenticate, interpret the response and decide how to handle uncertain results. It complements the Validation API reference; use that reference for the current contract before deploying code.

Choose where the check belongs

Start with the business decision. On a quotation form, you may want to flag a likely typo while the person is still present. In an import process, you may prefer to save all records and route questionable addresses to review. Before a campaign, you may need a dated assessment of the exact segment.

Those workflows need different responses to a timeout. Losing a valuable enquiry because a remote mail server is temporarily unavailable is rarely a sensible default.

1. Keep credentials on your server

Create an API token using the API Authentication area of your DataSoap account. Store the private token in your server’s secret configuration. The documented authentication header uses a Bearer token.

Do not put a private key in browser JavaScript, a public repository or a form’s page source. Your web page should submit to your own server, which performs the authenticated lookup and returns only the information the form needs.

Keep credentials and unnecessary personal data out of application logs. Restrict access to operational logs and decide how long lookup results need to be retained.

2. Send the email check

The following illustrates the request shape. The example address is a placeholder; it is not a live test result. Supply your token through your normal secure configuration.

POST https://api.datasoap.co.uk/v2
Authorization: Bearer YOUR_PRIVATE_TOKEN
Content-Type: application/json

{
  "lookup": "[email protected]",
  "checks": ["Email"]
}

Make the request from the server with a bounded timeout. Validate that the response is successful and matches the expected structure before using its fields. A network success alone does not mean that the address has passed validation.

3. Read the email result in context

The documented email response includes a validity result, a reason and flags covering disposable, role-based, free-provider and accepts-all addresses. Use the reason with those signals rather than building your whole decision around one flag.

• Disposable: relevant if your service needs a lasting contact address.
• Role-based: relevant where you need an individual, but potentially appropriate for accounts or sales enquiries.
• Free provider: not proof that a customer is invalid or fraudulent.
• Accepts all: the server may accept mail irrespective of the mailbox, so individual mailbox certainty is limited.

For a business quotation form, an accounts inbox may be useful. For an individual’s login, it may need different treatment. Define the policy around the purpose of the form, not a universal ban on a category.

4. Separate validation outcomes from service failures

A permanent rejection and a failed technical lookup are different events. If the check cannot finish, keep an explicit “needs review” state in your own system.

Situation	Suggested application behaviour
Definite formatting problem	Ask the user to review the address, preserving the rest of the form.
Technical result supports acceptance	Continue the workflow and record the check date.
Ambiguous or policy-sensitive result	Accept provisionally or route for review, depending on the use case.
Temporary lookup failure	Use a bounded retry or deferred queue; do not label the person’s address fake.
Authentication or balance problem	Alert the service owner and apply the documented fallback workflow.

This table describes application design choices rather than DataSoap response labels. Match the current error codes in the API reference and keep permanent and temporary outcomes distinct.

5. Design helpful form feedback

Use a message such as “Please check your email address” when a correction is needed. Avoid telling someone that their identity is fraudulent simply because an address check was inconclusive.

Preserve the other completed fields, explain what needs attention and make keyboard navigation work. If your process allows provisional submissions, show a clear success state and keep the review work behind the scenes.

Do not repeat chargeable lookups on every keystroke. Submit a complete address at an appropriate point, prevent accidental duplicate requests and give retries a sensible limit.

6. Test the decisions as well as the connection

Before launch, test the workflow with controlled fixtures and mocked responses. Include an accepted result, an obvious formatting error, a shared inbox flag, a catch-all flag, a timeout and an unavailable account balance.

Check that a failed lookup does not lose the enquiry, that the token never reaches the browser and that an uncertain result stays distinguishable from a confirmed rejection. Use authorised test addresses for any live checks and account for the charges involved.

Monitor what happens after launch

Track completion rates, rejected submissions, provisional records, retry counts and later bounce reports. A policy that rejects many genuine customers needs attention even if the integration is technically working.

Revisit checks when the form’s purpose changes. A mailing-list signup and an urgent service request may justify different handling of uncertainty.

Frequently asked questions

Does email validation replace confirmation emails?

No. Technical validation and a confirmation link answer different questions. A confirmation link can show that someone can access the inbox; validation assesses technical address signals.

Can validation establish marketing consent?

No. Keep consent, objections and channel permissions as separate decisions. A technically usable address is not automatically appropriate for marketing.

What if we only need occasional list checks?

The DataSoap portal may suit occasional file-based jobs better than a custom integration. Use the API when the check belongs inside a repeatable application workflow.

Build the integration around a clear decision

Start with one workflow and a written policy for uncertainty. Review the API documentation, check current pricing and contact DataSoap if you need help choosing the checks.