📱 Phone Validation in Zod

Easily validate phones in your project with Dymo API integrated with Zod.

A better, simpler way to validate emails with Dymo API + Zod in a single line of code!

About Phone Validation

What is Phone Validation?

Phone validation uses Dymo API to check for fraud, invalid phone numbers, and more. All async validations require parseAsync().

Usage

To start validating emails in your project with Zod, create a schema using dymoClient.phoneSchema():

import { z } from "zod";
import DymoAPIZod from "@dymo-api/zod";

const dymoClient = new DymoAPIZod({ apiKey: "" });

const userSchema = z.object({
    phone: dymoClient.phoneSchema(),
    email: dymoClient.emailSchema(),
    username: z.string().min(3),
    age: z.number().int().min(0)
});

Validating Data

(async () => {
    const validatedUser = await userSchema.parseAsync({
        phone: "+34617509462",
        email: "[email protected]",
        username: "build",
        age: 10
    });

    console.log(validatedUser);
    /*
    {
      phone: "+34617509462",
      email: "[email protected]", // normalized by Dymo API
      username: "build",
      age: 10
    }
    */
})();

Handling Invalid Emails

The schema will automatically throw an error if the email is fraudulent or invalid:

try {
    await userSchema.parseAsync({
        phone: "+34602322057",
        email: "[email protected]",
        username: "build",
        age: 10
    });
} catch (err) {
    console.error("Validation failed:", err.errors);
    /*
    [
        { path: ["phone"], message: "Invalid phone" }
    ]
    */
}

Optional Flags (for direct plugin-style usage)

You can pass options when creating the DymoAPIZod instance to customize behavior:

const dymoClient = new DymoAPIZod({
    apiKey: "",
    rules: {
        phone: {
            deny: ["FRAUD", "INVALID"]
        }
    }
});
  • rules: Customize which phone rules to apply.
  • parseAsync() must be used because the validator queries the Dymo API.

Examples with Other Validators

You can also create schemas for IPs, phones, and passwords:

const userSchema = z.object({
    email: dymoClient.emailSchema(),
    ip: dymoClient.ipSchema(),
    phone: dymoClient.phoneSchema(),

    // Coming Soon.
    password: dymoClient.passwordSchema()
});

Important: All async validators require parseAsync() because they make API requests.

Phone Rules

RuleDefaultPremiumDescription
FRAUD✅❌Email flagged as fraudulent
INVALID✅❌Invalid email format
COUNTRY:<COUNTRY_CODE>❌❌Block an phone based on its country; you must use ISO 3166-1 alpha-2.
HIGH_RISK_SCORE❌✅High risk email score

Parameters

ParameterTypeRequiredDescription
apiKeyString✅Your Dymo API key
rulesRules❌Customize which rules to apply
parseAsync()Function✅Must be called to validate async phone rules

💡 Tip: Using DymoAPIZod with Zod lets you combine real-time fraud checks with normal Zod validations in a single schema for secure, consistent, and easy-to-maintain validation.