Skip to content
Get your API key

JavaScript SDK

View as Markdown

Installation

Terminal window
npm install @syvel/js
# or
yarn add @syvel/js

Basic usage

import { Syvel } from "@syvel/js";


const syvel = new Syvel({
  apiKey: "sv_your_key",
});


try {
  // Check a domain
  const result = await syvel.check("yopmail.com");


  console.log(result.risk_score);  // 100
  console.log(result.is_risky);    // true
  console.log(result.reason);      // "disposable"


  // Check from a full email address
  const emailResult = await syvel.checkEmail("[email protected]");
} catch {
  // API unavailable — continue normally
}

HTML form validation

<form id="signup-form">
  <input type="email" id="email" name="email" placeholder="[email protected]" />
  <p id="email-error" style="color: red; display: none;"></p>
  <button type="submit">Sign up</button>
</form>


<script type="module">
  import { Syvel } from "https://cdn.jsdelivr.net/npm/@syvel/js";


  const syvel = new Syvel({ apiKey: "sv_your_key" });
  const emailInput = document.getElementById("email");
  const emailError = document.getElementById("email-error");


  let debounceTimer;


  emailInput.addEventListener("input", () => {
    clearTimeout(debounceTimer);
    debounceTimer = setTimeout(async () => {
      const email = emailInput.value;
      if (!email.includes("@")) return;


      try {
        const result = await syvel.checkEmail(email);
        if (result?.is_risky) {
          emailError.textContent = "Please use a professional email address.";
          emailError.style.display = "block";
        } else {
          emailError.style.display = "none";
        }
      } catch {
        emailError.style.display = "none"; // fail open
      }
    }, 500);
  });
</script>

React Hook

import { useState, useCallback } from "react";
import { Syvel } from "@syvel/js";


const syvel = new Syvel({ apiKey: import.meta.env.VITE_SYVEL_API_KEY });


export function useEmailCheck() {
  const [result, setResult] = useState(null);
  const [loading, setLoading] = useState(false);


  const check = useCallback(async (email: string) => {
    if (!email.includes("@")) return;


    setLoading(true);
    try {
      const data = await syvel.checkEmail(email);
      setResult(data);
    } catch {
      setResult(null); // fail open — treat as safe if API unavailable
    } finally {
      setLoading(false);
    }
  }, []);


  return { result, loading, check };
}

Advanced configuration

const syvel = new Syvel({
  apiKey: "sv_your_key",
  // Timeout in ms (default: 3000) — keep it low to avoid blocking the user
  timeout: 3000,
  // Silent mode (does not throw on error, returns null instead)
  silent: true,
});

Integration with React Hook Form

import { useForm } from "react-hook-form";
import { Syvel } from "@syvel/js";


const syvel = new Syvel({ apiKey: "sv_your_key" });


function SignupForm() {
  const { register, handleSubmit, setError, formState: { errors } } = useForm();


  const onSubmit = async (data) => {
    try {
      const result = await syvel.checkEmail(data.email);
      if (result.is_risky) {
        setError("email", { type: "manual", message: "Please use a valid email address." });
        return;
      }
    } catch {
      // Syvel unavailable — fail open and allow registration
    }
    // Continue with registration...
  };


  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("email")} type="email" />
      {errors.email && <p>{errors.email.message}</p>}
      <button type="submit">Sign up</button>
    </form>
  );
}

Resources

Last updated: