masonlet/contact-api
GitHub: masonlet/contact-api
一个可一键部署至 Vercel 的多服务商联系表单 API，为静态站点和个人项目提供开箱即用的邮件发送与反垃圾防护能力。
Stars: 0 | Forks: 0
# Contact API
可部署的**多服务商**联系表单 API
[](https://github.com/masonlet/contact-api/actions/workflows/ci.yml)
## 目录
- [功能特性](#features)
- [使用方法](#usage)
- [响应](#response)
- [部署与配置](#deployment--configuration)
- [前置条件](#prerequisites)
- [配置 `.env`](#2-configure-env)
- [部署](#deploying)
- [本地开发](#local-development)
- [许可证](#license)
## 功能特性
- 单个 `POST /api/contact` endpoint - 可直接应用于任何项目。
- 多服务商支持：Resend 和 Nodemailer (SMTP)。
- 通过 `ALLOWED_ORIGINS` 实现 CORS 支持。
- 输入验证并提供描述性的错误响应。
- 通过 Vercel WAF 实现速率限制，以防止垃圾邮件和滥用。
- 蜜罐保护。
## 使用方法
```
await fetch("https://your-deployment.vercel.app/api/contact", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
email: "sender@example.com", // required
message: "Your message here", // required
subject: "Hello", // optional
name: "Your name", // optional
fax_number: "" // optional; must be empty
})
});
```
## 响应
| Status | Body |
| ------ | ---- |
| 200 | { success: true, message: "Message sent successfully" } |
| 400 | { error: "Invalid or missing fields" } |
| 403 | { error: "Forbidden" } |
| 405 | { error: "Method not allowed" } |
| 415 | { error: "Unsupported Media Type" } |
| 429 | { error: "Too many requests. Please try again later" } |
| 500 | { error: "Message delivery failed. Please try again later" } |
| 503 | { error: "Service temporarily unavailable" } |
## 部署与配置
### 前置条件
- Node.js 20+
- Vercel
- 一个邮件服务商
- **Resend：** API key 和已验证的域名。
- **Nodemailer：** 有效的 SMTP 设置（需要时包括 `host`、`port`、`auth.user`、`auth.pass` 和 `secure`）。
### 1. 克隆并安装
```
git clone https://github.com/masonlet/contact-api.git
cd contact-api
npm install
```
### 2. 配置 `.env`
将 `.env.example` 复制到 `.env` 并填写环境变量。共享值为**必填项**；特定于服务商的值取决于 `EMAIL_PROVIDER`。
| Variable | Description |
| ----------------- | ----------- |
| `FROM_EMAIL` | 发件人地址 |
| `TO_EMAIL` | 收件人邮箱地址，以逗号分隔。 |
| `ALLOWED_ORIGINS` | 允许的 CORS 来源，以逗号分隔。留空则阻止所有跨域请求。 |
| `EMAIL_PROVIDER` | 要使用的邮件服务商：`resend` 或 `nodemailer`。 |
| `RESEND_API_KEY` | Resend API key，当 `EMAIL_PROVIDER=resend` 时必填。 |
| `SMTP_CONFIG` | Nodemailer SMTP 配置的 JSON 字符串，当 `EMAIL_PROVIDER=nodemailer` 时必填。 |
### 部署
#### 使用 Resend 部署
[](https://vercel.com/new/clone?repository-url=https://github.com/masonlet/contact-api&env=FROM_EMAIL,TO_EMAIL,ALLOWED_ORIGINS,EMAIL_PROVIDER,RESEND_API_KEY&envDescription[FROM_EMAIL]=Sender%20address%20(must%20be%20a%20verified%20Resend%20domain)&envDescription[TO_EMAIL]=Delivery%20address&envDescription[ALLOWED_ORIGINS]=Comma-separated%20list%20of%20allowed%20CORS%20origins&envDescription[EMAIL_PROVIDER]=resend&envDescription[RESEND_API_KEY]=Your%20Resend%20API%20key)
#### 使用 Nodemailer 部署
[](https://vercel.com/new/clone?repository-url=https://github.com/masonlet/contact-api&env=FROM_EMAIL,TO_EMAIL,ALLOWED_ORIGINS,EMAIL_PROVIDER,SMTP_CONFIG&envDescription[FROM_EMAIL]=Sender%20address%20accepted%20by%20your%20SMTP%20provider&envDescription[TO_EMAIL]=Delivery%20address&envDescription[ALLOWED_ORIGINS]=Comma-separated%20list%20of%20allowed%20CORS%20origins&envDescription[EMAIL_PROVIDER]=nodemailer&envDescription[SMTP_CONFIG]=JSON%20string%20of%20SMTP%20settings)
### 本地开发
```
npm run typecheck # TypeScript type check
npm run test # Run Vitest tests
npm run test:watch # Run Vitest in watch mode
npm run test:coverage # Run Vitest in coverage mode
```
## 许可证
MIT License - 详见 [LICENSE](./LICENSE)。
标签：API密钥检测, CISA项目, CORS, DNS解析, GNU通用公共许可证, MITM代理, Node.js, Nodemailer, OSV, Resend, RESTful API, Serverless, SMTP, Syscall, Vercel, WAF, Web开发, 前后端分离, 反垃圾邮件, 后端API, 多服务商, 开源项目, 提示词优化, 联系信息, 联系表单, 自动化攻击, 蜜罐保护, 表单API, 表单提交, 输入验证, 邮件发送