Next.js

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

Implement email verification in Next.js applications with server-side validation, API routes, and React Server Components.

Installation

npm install @emailverify/node

yarn add @emailverify/node

pnpm add @emailverify/node

Environment Setup

Add your API key to .env.local:

EMAILVERIFY_API_KEY=bv_live_xxx

App Router (Next.js 13+)

Server Action

Create a server action for email verification:

// app/actions/verify-email.ts
'use server';

import { EmailVerify } from '@emailverify/node';

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

export async function verifyEmail(email: string) {
  try {
    const result = await client.verify(email);
    return {
      success: true,
      data: result,
    };
  } catch (error) {
    return {
      success: false,
      error: 'Verification failed',
    };
  }
}

Client Component with Server Action

// app/components/signup-form.tsx
'use client';

import { useState, useTransition } from 'react';
import { verifyEmail } from '../actions/verify-email';

export function SignupForm() {
  const [email, setEmail] = useState('');
  const [verification, setVerification] = useState<any>(null);
  const [isPending, startTransition] = useTransition();

  const handleEmailBlur = () => {
    if (!email) return;

    startTransition(async () => {
      const result = await verifyEmail(email);
      setVerification(result);
    });
  };

  return (
    <form className="space-y-4">
      <div>
        <label htmlFor="email" className="block text-sm font-medium">
          Email
        </label>
        <input
          id="email"
          type="email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          onBlur={handleEmailBlur}
          className="mt-1 block w-full rounded-md border-gray-300 shadow-sm"
        />

        {isPending && (
          <p className="text-sm text-gray-500 mt-1">Verifying...</p>
        )}

        {verification?.data?.status === 'valid' && (
          <p className="text-sm text-green-600 mt-1">✓ Email verified</p>
        )}

        {verification?.data?.status === 'invalid' && (
          <p className="text-sm text-red-600 mt-1">
            Please enter a valid email
          </p>
        )}

        {verification?.data?.result?.disposable && (
          <p className="text-sm text-yellow-600 mt-1">
            Please use a permanent email
          </p>
        )}
      </div>

      <button
        type="submit"
        disabled={isPending || verification?.data?.status !== 'valid'}
        className="w-full py-2 px-4 bg-blue-600 text-white rounded-md disabled:opacity-50"
      >
        Sign Up
      </button>
    </form>
  );
}

API Route Handler

// app/api/verify-email/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { EmailVerify } from '@emailverify/node';

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

export async function POST(request: NextRequest) {
  try {
    const body = await request.json();
    const { email } = body;

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

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

React Server Component

Verify emails server-side before rendering:

// app/user/[id]/page.tsx
import { EmailVerify } from '@emailverify/node';
import { notFound } from 'next/navigation';

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

async function getUser(id: string) {
  // Fetch user from your database
  const user = await db.users.findUnique({ where: { id } });
  return user;
}

export default async function UserPage({ params }: { params: { id: string } }) {
  const user = await getUser(params.id);

  if (!user) {
    notFound();
  }

  // Verify email if not already verified
  let emailVerification = null;
  if (!user.emailVerified) {
    emailVerification = await client.verify(user.email);
  }

  return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>

      {emailVerification && (
        <div className="mt-4">
          <h2>Email Status</h2>
          <p>Status: {emailVerification.status}</p>
          <p>Score: {emailVerification.score}</p>
        </div>
      )}
    </div>
  );
}

Pages Router (Next.js 12)

API Route

// pages/api/verify-email.ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { EmailVerify } from '@emailverify/node';

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

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  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' });
  }
}

getServerSideProps

Verify emails during SSR:

// pages/user/[id].tsx
import { GetServerSideProps } from 'next';
import { EmailVerify } from '@emailverify/node';

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

interface Props {
  user: User;
  emailVerification: VerificationResult | null;
}

export const getServerSideProps: GetServerSideProps<Props> = async (context) => {
  const { id } = context.params!;

  const user = await getUser(id as string);

  if (!user) {
    return { notFound: true };
  }

  let emailVerification = null;
  if (!user.emailVerified) {
    try {
      emailVerification = await client.verify(user.email);
    } catch (error) {
      console.error('Verification failed:', error);
    }
  }

  return {
    props: {
      user,
      emailVerification,
    },
  };
};

export default function UserPage({ user, emailVerification }: Props) {
  return (
    <div>
      <h1>{user.name}</h1>
      {emailVerification && (
        <p>Email status: {emailVerification.status}</p>
      )}
    </div>
  );
}

Form Handling Patterns

With useFormState (React 19)

// app/components/form-with-state.tsx
'use client';

import { useFormState, useFormStatus } from 'react-dom';
import { signupAction } from '../actions/signup';

function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button type="submit" disabled={pending}>
      {pending ? 'Submitting...' : 'Sign Up'}
    </button>
  );
}

export function SignupFormWithState() {
  const [state, formAction] = useFormState(signupAction, {
    success: false,
    errors: {},
  });

  return (
    <form action={formAction}>
      <div>
        <input type="email" name="email" required />
        {state.errors?.email && (
          <p className="text-red-600">{state.errors.email}</p>
        )}
      </div>

      <div>
        <input type="text" name="name" required />
        {state.errors?.name && (
          <p className="text-red-600">{state.errors.name}</p>
        )}
      </div>

      <SubmitButton />

      {state.success && (
        <p className="text-green-600">Account created successfully!</p>
      )}
    </form>
  );
}

// app/actions/signup.ts
'use server';

import { EmailVerify } from '@emailverify/node';
import { z } from 'zod';

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

const signupSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
});

export async function signupAction(
  prevState: any,
  formData: FormData
) {
  const rawData = {
    email: formData.get('email') as string,
    name: formData.get('name') as string,
  };

  // Validate schema
  const parsed = signupSchema.safeParse(rawData);
  if (!parsed.success) {
    return {
      success: false,
      errors: parsed.error.flatten().fieldErrors,
    };
  }

  // Verify email
  const verification = await client.verify(parsed.data.email);

  if (verification.status === 'invalid') {
    return {
      success: false,
      errors: { email: ['Please enter a valid email address'] },
    };
  }

  if (verification.result.disposable) {
    return {
      success: false,
      errors: { email: ['Disposable emails are not allowed'] },
    };
  }

  // Create user in database
  await createUser(parsed.data);

  return { success: true, errors: {} };
}

With React Hook Form

// app/components/react-hook-form-example.tsx
'use client';

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

const schema = z.object({
  email: z.string().email('Invalid email'),
  password: z.string().min(8, 'Password must be at least 8 characters'),
});

type FormData = z.infer<typeof schema>;

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

  const onSubmit = async (data: FormData) => {
    // Verify email
    const response = await fetch('/api/verify-email', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email: data.email }),
    });

    const verification = await response.json();

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

    // Continue with signup
    console.log('Submitting:', data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
      <div>
        <input
          type="email"
          {...register('email')}
          className="w-full p-2 border rounded"
        />
        {errors.email && (
          <p className="text-red-600 text-sm">{errors.email.message}</p>
        )}
      </div>

      <div>
        <input
          type="password"
          {...register('password')}
          className="w-full p-2 border rounded"
        />
        {errors.password && (
          <p className="text-red-600 text-sm">{errors.password.message}</p>
        )}
      </div>

      <button
        type="submit"
        disabled={isSubmitting}
        className="w-full py-2 bg-blue-600 text-white rounded disabled:opacity-50"
      >
        {isSubmitting ? 'Verifying...' : 'Sign Up'}
      </button>
    </form>
  );
}

Middleware Verification

Verify emails in Next.js middleware:

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export async function middleware(request: NextRequest) {
  // Only run on signup routes
  if (request.nextUrl.pathname !== '/api/signup') {
    return NextResponse.next();
  }

  const body = await request.json();
  const { email } = body;

  if (email) {
    // Verify email before processing signup
    const verifyResponse = await fetch(
      'https://api.emailverify.ai/v1/verify',
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.EMAILVERIFY_API_KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ email }),
      }
    );

    const verification = await verifyResponse.json();

    if (verification.status === 'invalid') {
      return NextResponse.json(
        { error: 'Invalid email address' },
        { status: 400 }
      );
    }
  }

  return NextResponse.next();
}

export const config = {
  matcher: '/api/signup',
};

Caching Strategies

Route Handler Caching

// app/api/verify-email/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { EmailVerify } from '@emailverify/node';

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

// In-memory cache (use Redis in production)
const cache = new Map<string, { result: any; timestamp: number }>();
const CACHE_DURATION = 3600000; // 1 hour

export async function POST(request: NextRequest) {
  const { email } = await request.json();

  // Check cache
  const cached = cache.get(email);
  if (cached && Date.now() - cached.timestamp < CACHE_DURATION) {
    return NextResponse.json(cached.result, {
      headers: { 'X-Cache': 'HIT' },
    });
  }

  // Verify email
  const result = await client.verify(email);

  // Cache result
  cache.set(email, { result, timestamp: Date.now() });

  return NextResponse.json(result, {
    headers: { 'X-Cache': 'MISS' },
  });
}

Redis Caching (Production)

// lib/verify-with-cache.ts
import { Redis } from '@upstash/redis';
import { EmailVerify } from '@emailverify/node';

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

export async function verifyEmailWithCache(email: string) {
  const cacheKey = `email-verify:${email}`;

  // Check cache
  const cached = await redis.get(cacheKey);
  if (cached) {
    return { ...cached, fromCache: true };
  }

  // Verify email
  const result = await client.verify(email);

  // Cache for 24 hours
  await redis.setex(cacheKey, 86400, result);

  return { ...result, fromCache: false };
}

Bulk Verification

Background Job with API Route

// app/api/verify-bulk/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { EmailVerify } from '@emailverify/node';

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

export async function POST(request: NextRequest) {
  const { emails, webhookUrl } = await request.json();

  // Submit bulk job
  const job = await client.verifyBulk(emails, {
    webhookUrl: webhookUrl || `${process.env.NEXT_PUBLIC_URL}/api/webhook/bulk-complete`,
  });

  return NextResponse.json(job);
}

// Webhook handler for completion
// app/api/webhook/bulk-complete/route.ts
export async function POST(request: NextRequest) {
  const event = await request.json();

  if (event.event === 'bulk.completed') {
    // Process completed job
    await processCompletedJob(event.data.job_id);
  }

  return NextResponse.json({ received: true });
}

Error Handling

Global Error Handler

// lib/emailverify.ts
import { EmailVerify } from '@emailverify/node';

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

export async function verifyEmailSafe(email: string) {
  try {
    const result = await client.verify(email);
    return { success: true, data: result };
  } catch (error: any) {
    // Log error for monitoring
    console.error('Email verification failed:', {
      email,
      error: error.message,
      code: error.code,
    });

    // Return graceful fallback
    if (error.code === 'RATE_LIMIT_EXCEEDED') {
      return {
        success: false,
        error: 'Rate limit exceeded',
        retryAfter: error.retryAfter,
      };
    }

    if (error.code === 'INSUFFICIENT_CREDITS') {
      return {
        success: false,
        error: 'Service temporarily unavailable',
      };
    }

    return {
      success: false,
      error: 'Verification failed',
    };
  }
}

TypeScript Configuration

For full type safety, extend your types:

// types/emailverify.ts
import type { VerificationResult } from '@emailverify/node';

export interface VerifyEmailResponse {
  success: boolean;
  data?: VerificationResult;
  error?: string;
  fromCache?: boolean;
}

export interface SignupFormState {
  success: boolean;
  errors: {
    email?: string[];
    name?: string[];
  };
}

Best Practices

1. Always Verify Server-Side

// ✅ Good - Server verification
export async function signupAction(data: FormData) {
  const email = data.get('email') as string;
  const verification = await verifyEmail(email);
  // ...
}

// ❌ Bad - Client-only verification can be bypassed

2. Handle All States

function EmailStatus({ verification }: { verification: any }) {
  if (verification.isLoading) return <Loading />;
  if (verification.error) return <ErrorMessage />;
  if (!verification.data) return null;

  switch (verification.data.status) {
    case 'valid':
      return <ValidBadge />;
    case 'invalid':
      return <InvalidMessage />;
    case 'unknown':
      return <UnknownWarning />;
    case 'accept_all':
      return <CatchAllWarning />;
    default:
      return null;
  }
}

3. Don't Block User Flow

// Allow submission but warn users
<button
  type="submit"
  disabled={isSubmitting}
>
  {verification?.status === 'invalid'
    ? 'Submit Anyway'
    : 'Submit'}
</button>

React Integration

Client-side React components

Node.js SDK

Backend SDK documentation

TypeScript SDK

Full type definitions

Next.js

React Integration

Node.js SDK

TypeScript SDK

On this page