​
Overview

The Mail System template provides an extendable, serverless mailing system built with Next.js, TypeScript, and React Mail. It allows you to quickly integrate email sending capabilities into your Next.js application using a zero-config API and customizable email templates.

​
Features

  • Serverless API endpoint for sending emails via /api/send.
  • Environment-based configuration using .env files.
  • Customizable React Mail templates located in the emails directory.
  • Built-in TypeScript types for strong typing and IntelliSense support.
  • Deploys seamlessly on Vercel and other serverless platforms.

​
Prerequisites

  • Node.js v120 or newer
  • pnpm, npm, or yarn
  • A mailing service provider (SMTP, SendGrid, Mailgun, etc.)

​
Installation

  1. Clone the repository
# via Git
git clone https://github.com/kanakkholwal/mail-system.git
cd mail-system
  1. Install dependencies
# using pnpm
pnpm install

# or npm
npm install

# or yarn
yarn install
  1. Copy environment file
cp .env.example .env
  1. Configure environment variables

Edit the .env file at the project root and set your mailing service credentials:

# .env
MAIL_EMAIL=<SMTP_EMAIL>
MAIL_PASSWORD=<SMTP_PASSWORD>
SERVER_IDENTITY=<SERVER_IDENTITY> # A authentication header to communicate with your backend securely

​
Project Structure

├── /.env.example          # Example environment variables
├── /app                   # Next.js App directory (Next 13+)
│   ├── /api               # API routes
│   │   └── send/route..ts # POST /api/send endpoint
│   └── /page.tsx          # Landing page example
├── /emails                # React Mail templates
│   ├── template_[:template].tsx   # Example email component
|   ├── templates.tsx      # All templated imported and mapped exported
│   └── helper.ts          # Helper function to fire email send
├── /types                 # Shared TypeScript types
│   └── schema.ts          # Zod schema for data validation
├── /public                # Static assets
├── next.config.ts         # Next.js configuration
├── project.config.ts      # Vercel project settings
├── tsconfig.json          # TypeScript configuration
└── package.json           # Project manifest

​
API Endpoint: /api/send

The /api/send endpoint accepts a POST request with the following JSON payload:

// 
export interface SendMailPayload {
  targets: string | string[];
  template_key:string;
  subject: string;
  payload?: Record<string, string | number | string[] | number[]>;
}

​
Example Request

curl -X POST http://localhost:3000/api/send \
  -H "Content-Type: application/json" \
  -H "X-IDENTITY-KEY:x-api-key" \
  -d '{
    "to": "user@example.com",
    "subject": "Welcome to Our App!",
    "template_key": "welcome_verify",
    "targets":"acme@acme.com",
    "payload": { "name": "Jane Doe",email:"johndoe@example.com",platform_name:"Acme" }
  }'

​
Response

  • 200 OK: Email sent successfully.
  • 4xx/5xx: Error sending email.

​
Creating Custom Email Templates

  1. Add a new file in emails/, e.g., template_order-confirmation.tsx.

  2. Export a React component that returns your email layout:

import {
    Button,
    Column,
    Heading,
    Hr,
    Img,
    Link,
    Preview,
    Row,
    Section,
    Text,
  } from "@react-email/components";
import type { EmailPayload } from "@/types/schema";


export function OrderConfirmation({ payload }: { payload: EmailPayload }) {
      const order = payload.order as string;
      const userName = payload.name as string;
  
    return (
      <>
      <Preview>Order Confirmation</Preview>
      <Text className="text-gray-800 text-lg">
        Hi {userName},{"\n"}
      </Text>
      <Text className="text-gray-800 mt-4">
        Your order #{order} has been confirmed and will reach you in X days.
      </Text>
      </>
    );
  }

  1. Update your .env if needed for new variables.

  2. Send using the API by setting template to your component filename (without extension).

  3. Other ** Setiing ** can be changed in project.config.ts file.

​
Environment Variables

NameDescriptionRequiredDefault
SMTP_HOSTSMTP server host (e.g., smtp.gmail.com)No”smtp-relay.sendinblue.com”
SMTP_PORTSMTP server port (e.g., 587)No587
MAIL_EMAILSMTP username/emailYes—
MAIL_PASSWORDSMTP passwordYes—
IDENTITY_KEY Auth KeyYes—

​
Deployment

Deploy to Vercel with zero configuration:

  1. Push your code to GitHub.
  2. Import the repository in Vercel.
  3. Set the same environment variables in Vercel Dashboard.
  4. Deploy! Emails will work out of the box.

​
Contributing

  1. Fork the repository.
  2. Create a new branch: git checkout -b feature/my-feature.
  3. Commit your changes: git commit -m 'Add my feature'.
  4. Push to the branch: git push origin feature/my-feature.
  5. Open a Pull Request.

​
License

This project is licensed under the MIT License.

​
Support

For issues and suggestions, please visit the GitHub issues page.