EmailVerify LogoEmailVerify
整合指南Web 框架

React

Email checker for React. Real-time email verification in React forms and components.

為您的 React 應用添加即時電子郵件驗證。在用戶輸入時驗證電子郵件,防止無效提交,提升表單用戶體驗。

安裝

npm install @emailverify/react @emailverify/node
yarn add @emailverify/react @emailverify/node
pnpm add @emailverify/react @emailverify/node

快速開始

帶驗證的基本郵箱輸入

import { useState } from 'react';
import { useEmailVerification } from '@emailverify/react';

function SignupForm() {
  const [email, setEmail] = useState('');
  const { verify, result, isLoading, error } = useEmailVerification();

  const handleEmailBlur = async () => {
    if (email) {
      await verify(email);
    }
  };

  return (
    <form>
      <div className="form-group">
        <label htmlFor="email">電子郵件</label>
        <input
          id="email"
          type="email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          onBlur={handleEmailBlur}
          className={result?.status === 'invalid' ? 'error' : ''}
        />

        {isLoading && <span className="loading">驗證中...</span>}

        {result?.status === 'invalid' && (
          <span className="error-message">
            請輸入有效的電子郵件地址
          </span>
        )}

        {result?.status === 'valid' && (
          <span className="success-message">✓ 電子郵件已驗證</span>
        )}

        {result?.result?.disposable && (
          <span className="warning-message">
            請使用永久電子郵件地址
          </span>
        )}
      </div>

      <button type="submit" disabled={result?.status !== 'valid'}>
        註冊
      </button>
    </form>
  );
}

Provider 設定

使用 EmailVerify provider 包裝您的應用:

// App.jsx or main.jsx
import { EmailVerifyProvider } from '@emailverify/react';

function App() {
  return (
    <EmailVerifyProvider
      config={{
        // API 請求通过您的後端
        apiEndpoint: '/api/verify-email',
      }}
    >
      <YourApp />
    </EmailVerifyProvider>
  );
}

永远不要在客戶端代码中暴露您的 API 金鑰。始終通过後端驗證郵箱。

後端 API 路由

创建安全的郵箱驗證 API 端点:

// pages/api/verify-email.js (Next.js) or your Express route
import { EmailVerify } from '@emailverify/node';

const client = new EmailVerify({
  apiKey: process.env.EMAILVERIFY_API_KEY,
});

export default async function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' });
  }

  const { email } = req.body;

  if (!email) {
    return res.status(400).json({ error: 'Email is required' });
  }

  try {
    const result = await client.verify(email);
    return res.json(result);
  } catch (error) {
    console.error('Verification error:', error);
    return res.status(500).json({ error: 'Verification failed' });
  }
}

Hooks 參考

useEmailVerification

郵箱驗證的主要 hook:

const {
  verify,      // 驗證電子郵件的函数
  result,      // 驗證結果对象
  isLoading,   // 加载状态
  error,       // 驗證失敗時的錯誤对象
  reset,       // 重置状态
} = useEmailVerification(options);

选項：

interface UseEmailVerificationOptions {
  // 防抖延迟（毫秒，默认：500）
  debounceMs?: number;

  // 值更改時自动驗證
  autoVerify?: boolean;

  // 快取結果的持續時间（毫秒）
  cacheDuration?: number;

  // 自定義 API 端点
  apiEndpoint?: string;
}

useEmailInput

将輸入状态與驗證結合的便捷 hook:

import { useEmailInput } from '@emailverify/react';

function EmailField() {
  const {
    value,
    onChange,
    onBlur,
    verification,
    isValid,
    errorMessage,
  } = useEmailInput({
    debounceMs: 300,
    validateOnBlur: true,
  });

  return (
    <div>
      <input
        type="email"
        value={value}
        onChange={onChange}
        onBlur={onBlur}
      />
      {errorMessage && <span className="error">{errorMessage}</span>}
    </div>
  );
}

元件

EmailInput 元件

预建構的帶驗證的郵箱輸入:

import { EmailInput } from '@emailverify/react';

function MyForm() {
  const handleVerified = (result) => {
    console.log('Verification result:', result);
  };

  return (
    <EmailInput
      name="email"
      label="Email Address"
      placeholder="you@example.com"
      onVerified={handleVerified}
      showValidationStatus
      blockDisposable
      blockRoleBased={false}
      className="custom-input"
    />
  );
}

Props:

PropTypeDefaultDescription
onVerifiedfunction-Callback when verification completes
showValidationStatusbooleantrueShow validation indicators
blockDisposablebooleantrueShow error for disposable emails
blockRoleBasedbooleanfalseShow error for role-based emails
verifyOnBlurbooleantrueVerify when field loses focus
debounceMsnumber500Debounce delay

表單函式庫整合

React Hook Form

import { useForm } from 'react-hook-form';
import { useEmailVerification } from '@emailverify/react';

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

  const { verify, isLoading } = useEmailVerification();

  const validateEmail = async (email) => {
    const result = await verify(email);

    if (result.status === 'invalid') {
      setError('email', {
        type: 'validation',
        message: '請輸入有效的電子郵件地址',
      });
      return false;
    }

    if (result.result?.disposable) {
      setError('email', {
        type: 'validation',
        message: '不允许使用一次性電子郵件地址',
      });
      return false;
    }

    clearErrors('email');
    return true;
  };

  const onSubmit = async (data) => {
    const isValid = await validateEmail(data.email);
    if (!isValid) return;

    // 繼續提交表單
    console.log('提交:', data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input
        type="email"
        {...register('email', {
          required: '電子郵件是必需的',
          pattern: {
            value: /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i,
            message: '無效的電子郵件格式',
          },
        })}
        onBlur={(e) => validateEmail(e.target.value)}
      />
      {errors.email && <span>{errors.email.message}</span>}
      {isLoading && <span>驗證中...</span>}

      <button type="submit">提交</button>
    </form>
  );
}

Formik

import { Formik, Form, Field, ErrorMessage } from 'formik';
import * as Yup from 'yup';
import { useEmailVerification } from '@emailverify/react';

function SignupForm() {
  const { verify } = useEmailVerification();

  const validationSchema = Yup.object({
    email: Yup.string()
      .email('Invalid email format')
      .required('Email is required')
      .test('email-verification', 'Invalid email address', async (value) => {
        if (!value) return false;
        const result = await verify(value);
        return result.status === 'valid';
      }),
  });

  return (
    <Formik
      initialValues={{ email: '' }}
      validationSchema={validationSchema}
      onSubmit={(values) => console.log(values)}
    >
      {({ isSubmitting, isValidating }) => (
        <Form>
          <Field type="email" name="email" />
          <ErrorMessage name="email" component="span" className="error" />
          {isValidating && <span>驗證中...</span>}

          <button type="submit" disabled={isSubmitting || isValidating}>
            提交
          </button>
        </Form>
      )}
    </Formik>
  );
}

Zod + React Hook Form

import { z } from 'zod';
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { useEmailVerification } from '@emailverify/react';

const schema = z.object({
  email: z.string().email('無效的電子郵件格式'),
  name: z.string().min(2, '名称至少需要 2 個字符'),
});

type FormData = z.infer<typeof schema>;

function SignupForm() {
  const { verify, result } = useEmailVerification();

  const {
    register,
    handleSubmit,
    formState: { errors },
    setError,
  } = useForm<FormData>({
    resolver: zodResolver(schema),
  });

  const onSubmit = async (data: FormData) => {
    // Verify email before submission
    const verification = await verify(data.email);

    if (verification.status !== 'valid') {
      setError('email', {
        type: 'manual',
        message: 'Please enter a valid email address',
      });
      return;
    }

    // Submit form
    console.log('Submitting:', data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input type="email" {...register('email')} />
      {errors.email && <span>{errors.email.message}</span>}

      <input type="text" {...register('name')} />
      {errors.name && <span>{errors.name.message}</span>}

      <button type="submit">Submit</button>
    </form>
  );
}

防抖和性能

内置防抖

The hook includes debouncing by default:

const { verify } = useEmailVerification({
  debounceMs: 500, // Wait 500ms after user stops typing
});

// Verify on every keystroke (debounced internally)
<input
  type="email"
  onChange={(e) => verify(e.target.value)}
/>

手动防抖

For more control, use your own debouncing:

import { useDeferredValue, useEffect } from 'react';

function EmailField() {
  const [email, setEmail] = useState('');
  const deferredEmail = useDeferredValue(email);
  const { verify, result } = useEmailVerification();

  useEffect(() => {
    if (deferredEmail && deferredEmail.includes('@')) {
      verify(deferredEmail);
    }
  }, [deferredEmail]);

  return (
    <input
      type="email"
      value={email}
      onChange={(e) => setEmail(e.target.value)}
    />
  );
}

快取結果

快取驗證結果以避免冗餘 API 呼叫：

const { verify } = useEmailVerification({
  cacheDuration: 3600000, // 快取 1 小時
});

樣式

CSS 类

EmailInput 元件應用这些类：

/* 容器 */
.bv-email-input { }

/* 輸入字段 */
.bv-email-input__field { }
.bv-email-input__field--valid { }
.bv-email-input__field--invalid { }
.bv-email-input__field--loading { }

/* 状态指示器 */
.bv-email-input__status { }
.bv-email-input__status--valid { }
.bv-email-input__status--invalid { }
.bv-email-input__status--warning { }

/* 錯誤消息 */
.bv-email-input__error { }

自定義樣式示例

.bv-email-input__field {
  padding: 12px 16px;
  border: 2px solid #e2e8f0;
  border-radius: 8px;
  font-size: 16px;
  transition: border-color 0.2s;
}

.bv-email-input__field:focus {
  outline: none;
  border-color: #3182ce;
}

.bv-email-input__field--valid {
  border-color: #48bb78;
}

.bv-email-input__field--invalid {
  border-color: #f56565;
}

.bv-email-input__status {
  display: flex;
  align-items: center;
  gap: 4px;
  font-size: 14px;
  margin-top: 4px;
}

.bv-email-input__status--valid {
  color: #48bb78;
}

.bv-email-input__status--invalid {
  color: #f56565;
}

Tailwind CSS

<EmailInput
  className="w-full px-4 py-3 border-2 rounded-lg focus:ring-2 focus:ring-blue-500"
  inputClassName="data-[valid]:border-green-500 data-[invalid]:border-red-500"
  statusClassName="text-sm mt-1"
/>

TypeScript 支持

完整的 TypeScript 支持和匯出类型:

import type {
  VerificationResult,
  EmailVerificationOptions,
  UseEmailVerificationReturn,
} from '@emailverify/react';

interface FormState {
  email: string;
  verification: VerificationResult | null;
}

function useSignupForm(): FormState {
  const [email, setEmail] = useState('');
  const { result } = useEmailVerification();

  return {
    email,
    verification: result,
  };
}

类型定義

interface VerificationResult {
  email: string;
  status: 'valid' | 'invalid' | 'unknown' | 'accept_all';
  result: {
    deliverable: boolean;
    valid_format: boolean;
    valid_domain: boolean;
    valid_mx: boolean;
    disposable: boolean;
    role: boolean;
    catchall: boolean;
    free: boolean;
    smtp_valid: boolean;
  };
  score: number;
  reason: string | null;
}

interface UseEmailVerificationReturn {
  verify: (email: string) => Promise<VerificationResult>;
  result: VerificationResult | null;
  isLoading: boolean;
  error: Error | null;
  reset: () => void;
}

最佳实践

1. 在失焦時驗證，而不是每次按鍵

// ✅ 好的 - 在用戶完成輸入時驗證
<input
  type="email"
  onBlur={(e) => verify(e.target.value)}
/>

// ❌ 避免 - 过多的 API 呼叫
<input
  type="email"
  onChange={(e) => verify(e.target.value)} // 没有防抖
/>

2. 显示清晰的反馈

function EmailStatus({ result, isLoading }) {
  if (isLoading) {
    return <span className="text-gray-500">檢查電子郵件...</span>;
  }

  if (!result) return null;

  const messages = {
    valid: { text: '✓ 有效的電子郵件', className: 'text-green-600' },
    invalid: { text: '✗ 無效的電子郵件', className: 'text-red-600' },
    unknown: { text: '? 无法驗證', className: 'text-yellow-600' },
  };

  const { text, className } = messages[result.status] || {};

  return <span className={className}>{text}</span>;
}

3. 不要阻止表單提交

允许提交，即使驗證仍在進行中：

function handleSubmit(data) {
  if (verificationResult?.status === 'invalid') {
    // 显示錯誤但不阻止
    showWarning('電子郵件可能無效');
  }

  // 繼續提交
  submitForm(data);
}

4. 處理网絡錯誤

function EmailField() {
  const { verify, result, error, isLoading } = useEmailVerification();

  return (
    <div>
      <input type="email" onBlur={(e) => verify(e.target.value)} />

      {error && (
        <span className="text-yellow-600">
          无法驗證電子郵件。繼續提交。
        </span>
      )}
    </div>
  );
}

相关資源

Next.js 整合

使用 Next.js 進行服务器端驗證

TypeScript SDK

完整的 TypeScript 支持

Node.js SDK

後端整合

Web Frameworks

Email checker for web frameworks. React, Next.js, Vue, Django, Laravel, Go integration guides.

Next.js

Email checker for Next.js. Server-side and client-side email verification in React.

On this page

安裝快速開始帶驗證的基本郵箱輸入Provider 設定後端 API 路由Hooks 參考useEmailVerificationuseEmailInput元件EmailInput 元件表單函式庫整合React Hook FormFormikZod + React Hook Form防抖和性能内置防抖手动防抖快取結果樣式CSS 类自定義樣式示例Tailwind CSSTypeScript 支持类型定義最佳实践1. 在失焦時驗證，而不是每次按鍵2. 显示清晰的反馈3. 不要阻止表單提交4. 處理网絡錯誤相关資源