SendGrid-Mock 镜像文档

概述

SendGrid-Mock是一个轻量级服务器镜像，用于模拟SendGrid API服务，主要面向开发环境。它允许开发者在不依赖真实SendGrid服务的情况下，测试邮件发送、接收和管理功能，有效降低开发过程中的测试成本和风险。

核心功能与特性

HTTP API

• 发送邮件
  支持通过POST /v3/mail/send端点模拟邮件发送请求，接收符合SendGrid API格式的请求数据。

• 检索已发送邮件
  通过GET /api/mails端点获取已发送邮件列表，支持多条件组合过滤：

  • 收件人过滤：GET /api/mails?to=***（精确匹配收件人***）
  • 主题过滤：
    • GET /api/mails?subject=The subject（精确匹配主题）
    • GET /api/mails?subject=%subject%（包含指定字符串，使用%作为通配符）
  • 时间过滤：GET /api/mails?dateTimeSince=2020-12-06T10:00:00Z（按ISO-8601格式筛选指定时间之后的邮件）

• 删除已发送邮件
  通过DELETE /api/mails端点删除已发送邮件，支持收件人过滤：

  • DELETE /api/mails?to=***（仅删除指定收件人的邮件）

管理界面（UI）

• 直观展示所有已发送邮件的详细信息
• 提供界面化操作删除已发送邮件

额外功能

• 基本认证支持
  通过环境变量AUTHENTICATION配置静态内容的基本认证，格式为user1:passwordForUser1;user2:passwordForUser2（多用户用;分隔）。

• API密钥认证
  通过环境变量API_KEY配置API端点的认证密钥，仅对API请求生效。

• 请求速率限制
  支持对API服务和SSL服务配置速率限制，通过以下环境变量控制：

  • RATE_LIMIT_ENABLED：是否启用速率限制，可选值true或false（默认false）
  • RATE_LIMIT_WINDOW_IN_MS：速率限制时间窗口（毫秒），默认60000
  • RATE_LIMIT_MAX_REQUESTS：时间窗口内允许的最大请求数，默认100
  • SSL_RATE_LIMIT_ENABLED：SSL服务速率限制开关，默认false
  • SSL_RATE_LIMIT_WINDOW_IN_MS：SSL服务时间窗口（毫秒），默认60000
  • SSL_RATE_LIMIT_MAX_REQUESTS：SSL服务时间窗口内最大请求数，默认100

• 邮件历史保留时间
  通过环境变量MAIL_HISTORY_DURATION配置已发送邮件的保留时间，使用ISO-8601时长格式（如PT24H表示24小时），默认保留24小时。

• 事件通知支持
  通过环境变量EVENT_DELIVERY_URL配置事件回调URL，当邮件发送时，会向该URL发送delivered事件通知（符合SendGrid事件跟踪格式）。

使用场景

适用于需要集成SendGrid邮件功能的应用开发与测试场景，可在不调用真实SendGrid服务的情况下，验证邮件发送逻辑、测试收件人处理、调试邮件内容格式等，避免开发环境中发送真实邮件造成的资源浪费或信息泄露。

使用方法与配置说明

基本部署

通过Docker命令直接启动容器：

shell
docker run -it -p 3000:3000 -e "API_KEY=sendgrid-api-key" ghashange/sendgrid-mock:1.13.0

启动后，可通过http://localhost:3000访问管理界面，API端点为http://localhost:3000/v3/mail/send。

SSL支持

如需启用SSL（基于Let's Encrypt），需配置域名和***：

shell
docker run -it -p 3000:3000 \
  -e "API_KEY=sendgrid-api-key" \
  -e "CERT_DOMAINNAMES=[你的域名]" \
  -e "CERT_EMAIL=[你的***地址]" \
  ghashange/sendgrid-mock:1.13.0

环境变量配置