Add an email delivery check to your app

Check a submitted email on your Node server and use format, domain and delivery results to give useful feedback.

Last tested

Working example

ParseAPI
Node

Set up ParseAPI

Install the SDK in your application and set PARSEAPI_KEY in your server environment.

Terminal
npm install @parseapi/sdk@1.15.1
export PARSEAPI_KEY='YOUR_SECRET_API_KEY'

Create a client and reuse it for the calls below:

JavaScript
import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI();
Get an API key ↗

Check the address before your app uses it

Add an email check to an existing contact, signup, or invitation form. Your server receives the submitted address, asks ParseAPI for the facts your workflow needs, and sends useful feedback back to the form.

Use parse.email for format and domain checks. When your feature also needs a mailbox delivery check, request it explicitly with parse.email.verify.

1. Receive the submitted address

Read email from your existing server-side form handler, trim it, and require one nonempty address before making a request. The complete example also rejects line breaks and inputs longer than 254 characters.

2. Give feedback on format and domain

Pass the submitted address to parse.email:

JavaScript
const validation = await parse.email(email, { retries: 0 });

Use validation.valid to flag an invalid format next to the email field. If validation.domain_valid is false, ask the person to check the domain. A null domain result is unknown.

validation.didyoumean can suggest a spelling correction. Offer it as a choice and check the confirmed address after an edit. Keep the person's entered address until they accept a correction.

This call does not test whether the mailbox accepts mail.

3. Request delivery verification when needed

Call parse.email.verify only when your workflow is meant to request a delivery check:

JavaScript
const verification = await parse.email.verify(email, {
  retries: 0,
  timeoutMs: 30000
});

This sends GET /email/verify and includes basic validation in the same response. You can start with this call when delivery is the task. No preliminary validation request is needed.

A completed verification uses one metered delivery check. Review the Email reference for allowances and billing. The example disables retries and uses a 30-second timeout. A timeout can follow a completed check, so another attempt is an explicit decision and may consume another unit.

4. Turn the delivery facts into an app state

JavaScript
const { deliverable = null, catchall = null } = verification;

Use the two flags together when deciding what the form should say:

  • catchall: true: the domain accepts arbitrary recipients, so this mailbox remains uncertain.
  • Otherwise, deliverable: false: the check rejected delivery.
  • deliverable: true with catchall: false: a conclusive positive answer from this check.
  • Other combinations or missing delivery data: no conclusive answer. Keep unknown flags as null rather than converting them to false.

Map those facts to the state your form displays:

JavaScript
const status = catchall === true ? 'catchall'
  : deliverable === false ? 'undeliverable'
  : deliverable === true && catchall === false ? 'deliverable' : 'unknown';

Show an invalid-address message for a completed rejection. Give catch-all or unknown results an uncertain state, so your workflow can ask for confirmation or leave the address for review. A request error, including HTTP 400 for malformed input, should let the person correct or retry the input. It is not a mailbox verdict.

Return the validation fields and, when requested, the delivery state from your existing server handler. Use them to show field feedback beside the submitted address. Keep a request failure separate from an invalid address so the person can edit or retry.

Attach the result to the exact submitted address and clear it when that address changes. Deliverability is not ownership verification or a guarantee of future inbox placement. The signup email tutorial covers email feedback in the browser.

Complete example

Use the complete implementation as a reference when adding this feature to your app. It includes the validation and failure handling around the calls above.

View and copy the complete source
verify-email-server.node.mjs
import { pathToFileURL } from 'node:url';
// example:imports
import { parseAPI, ParseAPIError } from '@parseapi/sdk';
// /example:imports

function errorResult(error) {
  return error instanceof ParseAPIError
    ? { code: error.code, status: error.status, request_id: error.requestId }
    : { code: 'request_failed', status: null, request_id: null };
}

function readCore(data, input) {
  if (!data || typeof data.valid !== 'boolean' || typeof data.email !== 'string' ||
      data.email.toLowerCase() !== input.toLowerCase()) throw new Error('Unexpected email response.');
  for (const field of ['domain_valid', 'disposable', 'role']) {
    if (data[field] != null && typeof data[field] !== 'boolean') throw new Error('Unexpected email flag.');
  }
  return {
    email: data.email, valid: data.valid, domain_valid: data.domain_valid ?? null,
    disposable: data.disposable ?? null, role: data.role ?? null,
    suggestion: typeof data.didyoumean === 'string' ? data.didyoumean : null
  };
}

export function readVerification(verification) {
  if (!verification || typeof verification !== 'object' || Array.isArray(verification)) throw new Error('Unexpected verification response.');
  if (!Object.hasOwn(verification, 'deliverable') && !Object.hasOwn(verification, 'catchall')) {
    return { status: 'unavailable', deliverable: null, catchall: null };
  }
  // example:result
  const { deliverable = null, catchall = null } = verification;
  // /example:result
  if (![deliverable, catchall].every(value => value === null || typeof value === 'boolean')) {
    throw new Error('Unexpected verification flag.');
  }
  // example:decision
  const status = catchall === true ? 'catchall'
    : deliverable === false ? 'undeliverable'
    : deliverable === true && catchall === false ? 'deliverable' : 'unknown';
  // /example:decision
  return { status, deliverable, catchall };
}

export async function verifyEmail(input, parse, verify = false) {
  if (typeof verify !== 'boolean') throw new Error('Verification must be explicitly true or false.');
  if (typeof input !== 'string' || !input.trim() || input.trim().length > 254 || /[\r\n]/.test(input)) {
    throw new Error('Provide one email address of at most 254 characters.');
  }
  const email = input.trim();
  const result = {
    input, email: null, valid: null, domain_valid: null, disposable: null, role: null,
    suggestion: null, verification: { status: 'not_requested', deliverable: null, catchall: null }, error: null
  };
  try {
    if (verify !== true) {
      // example:core
      const validation = await parse.email(email, { retries: 0 });
      // /example:core
      const core = readCore(validation, email);
      Object.assign(result, core);
      if (!core.valid) result.verification.status = 'skipped_invalid';
      return result;
    }

    // Verification includes basic validation in the same response.
    // example:request
    const verification = await parse.email.verify(email, {
      retries: 0,
      timeoutMs: 30000
    });
    // /example:request
    Object.assign(result, readCore(verification, email));
    if (verification.valid !== true) {
      result.verification = { status: 'skipped_invalid', deliverable: null, catchall: null };
    } else {
      result.verification = readVerification(verification);
    }
  } catch (error) {
    if (verify) result.verification = { status: 'request_failed', deliverable: null, catchall: null };
    result.error = errorResult(error);
    // A timeout can follow a completed check. Let the caller decide about another attempt.
  }
  return result;
}

async function main() {
  const args = process.argv.slice(2);
  if (args.includes('--help')) {
    console.log('Use: node verify-email-server.node.mjs [email] [--verify]\nDefault: core validation of hello@example.com. --verify requests a metered check.');
    return;
  }
  const verify = args.includes('--verify');
  const values = args.filter(value => value !== '--verify');
  if (values.length > 1 || args.filter(value => value === '--verify').length > 1 || values.some(value => value.startsWith('--'))) {
    throw new Error('Use: node verify-email-server.node.mjs [email] [--verify]');
  }
  // Reads PARSEAPI_KEY. Keep the secret key in your server environment.
  // example:client
  const parse = parseAPI(undefined, { timeoutMs: 10000, retries: 0 });
  // /example:client
  const email = values[0] ?? 'hello@example.com';
  // example:integration
  const result = await verifyEmail(email, parse, verify);
  // /example:integration
  console.log(JSON.stringify(result, null, 2));
  if (result.error || ['unavailable', 'unknown', 'catchall'].includes(result.verification.status)) process.exitCode = 2;
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  main().catch(error => { console.error(error instanceof ParseAPIError ? 'Could not initialize the API client.' : error.message); process.exitCode = 1; });
}
Try the complete example on your computer

After completing the setup above, save the source in your application folder and run its sample:

Terminal
node verify-email-server.node.mjs

For every field and parameter, see Email API reference.

Build something else

All tutorials →