Official Dymo API Library for Zod

This library extends Zod with Dymo API validators for emails, IPs, phones, passwords, and more. You can see the original library documentation here.

---

Installation

Install the library in your project:

npm i @dymo-api/zod

# or

pnpm i @dymo-api/zod

# or

yarn add @dymo-api/zod

---

Authenticating the Client with API Key

Get your free API Key

import DymoAPIZod from "@dymo-api/zod";

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

---

Validating Email Using Zod Schema

With @dymo-api/zod, your email validation can now be used directly in a Zod object, including async validation with automatic normalization:

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

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

const userSchema = z.object({
    email: dymoClient.emailSchema(),  // Dymo API validation + normalization
    username: z.string().min(3),
    age: z.number().int().min(0)
});

(async () => {
    const userData = {
        email: "[email protected]",
        username: "build",
        age: 10
    };

    const validatedUser = await userSchema.parseAsync(userData);

    console.log(validatedUser);
    /*
    {
      email: "build-10-28-2025@tpeoficial.com", // normalized by Dymo API
      username: "build",
      age: 10
    }
    */
})();

---

Handling Invalid Emails

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

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

---

Async Validation Functions (Optional)

If you prefer not to use Zod, you can validate emails directly with async functions:

const result = await dymoClient.validateEmail("[email protected]");

if (!result.allow) {
    console.error("Email rejected by Dymo API:", result.reasons);
}

---

Combining 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 query the Dymo API.

---

💡 Tip: Using DymoAPIZod with Zod allows you to combine real-time fraud checks with normal Zod validations in a single schema.