fastify-xemail
validate
Validate an email address using the SendGrid Email Validation API.
validate
Validate an email address using the SendGrid Email Validation API. Returns a soft result — API errors are caught and returned as { valid: false, verdict: "Unknown", error: "..." } rather than thrown.
Note: The SendGrid Email Validation API is a paid add-on. Ensure your API key has Email Validation permissions.
Signature
fastify.xEmail.validate(
email: string
): Promise<ValidationResult>
interface ValidationResult {
email: string;
valid: boolean;
verdict: string; // "Valid" | "Risky" | "Invalid" | "Unknown"
score?: number; // 0–1 confidence score (present on success)
result?: object; // full SendGrid validation result object
error?: string; // present only on API failure
}
Params
| Name | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Email address to validate. |
Returns
Promise<ValidationResult> — never throws (API errors are caught and returned in the error field).
| Property | Type | Description |
|---|---|---|
email | string | The input email address. |
valid | boolean | true if verdict is "Valid". |
verdict | string | "Valid", "Risky", "Invalid", or "Unknown". |
score | number | Confidence score from 0 to 1 (higher is better). |
result | object | Full SendGrid validation result with sub-checks. |
error | string | Error message if the API call failed. |
Throws
[xEmail] 'email' (string) is required for validate().— missing or non-string input (thrown before API call).
Examples
Basic — validate on registration
fastify.post("/auth/register", async (request, reply) => {
const { email, password } = request.body;
const validation = await fastify.xEmail.validate(email);
if (!validation.valid) {
return reply.code(400).send({
error: "Invalid email address",
verdict: validation.verdict,
});
}
const user = await createUser({ email, password });
return { userId: user.id };
});
Realistic — warn on risky, block on invalid
fastify.post("/contacts/import", async (request) => {
const { contacts } = request.body;
const results = [];
for (const contact of contacts) {
const v = await fastify.xEmail.validate(contact.email);
results.push({
email: contact.email,
status: v.valid ? "ok" : v.verdict === "Risky" ? "warn" : "rejected",
score: v.score,
});
}
const importable = results.filter((r) => r.status !== "rejected");
await db.contacts.bulkInsert(importable);
return {
imported: importable.length,
rejected: results.filter((r) => r.status === "rejected").length,
results,
};
});
See Also
- contacts-add — Add a validated contact to SendGrid Marketing
- send — Send an email after validation
AI Context
package: "@xenterprises/fastify-xemail"
method: fastify.xEmail.validate(email)
use-when: Validate an email address using SendGrid Email Validation API — returns soft result, does not throw on invalid
returns: { valid: boolean, verdict, score, checks }