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
ParseAPISet up ParseAPI
Install the SDK in your application and set PARSEAPI_KEY in your server environment.
npm install @parseapi/sdk@1.15.1
export PARSEAPI_KEY='YOUR_SECRET_API_KEY'Create a client and reuse it for the calls below:
import { parseAPI } from '@parseapi/sdk';
const parse = parseAPI();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:
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:
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
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: truewithcatchall: false: a conclusive positive answer from this check.- Other combinations or missing delivery data: no conclusive answer. Keep unknown flags as
nullrather than converting them tofalse.
Map those facts to the state your form displays:
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
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:
node verify-email-server.node.mjsFor every field and parameter, see Email API reference.
Build something else
- Check an email as someone types
- Build a contact review step for inbound emails
- Build a PHP contact form