Add MailerSend and template-based email verification

Introduced support for MailerSend as an email provider alongside SMTP, with configuration options in settings. Added Jinja2-based multi-language email templates for verification emails, and refactored the email sending logic to use these templates and support language selection based on user country code. Updated related services and API endpoints to pass country code and handle new response formats. Added dependencies for Jinja2 and MailerSend.

app/service/email_queue.py

@@ -30,7 +30,10 @@ class EmailQueue:
         self._executor = concurrent.futures.ThreadPoolExecutor(max_workers=2)
         self._retry_limit = 3  # 重试次数限制
 
-        # 邮件配置
+        # 邮件提供商配置
+        self.email_provider = settings.email_provider
+
+        # SMTP 邮件配置
         self.smtp_server = settings.smtp_server
         self.smtp_port = settings.smtp_port
         self.smtp_username = settings.smtp_username
@@ -38,6 +41,9 @@ class EmailQueue:
         self.from_email = settings.from_email
         self.from_name = settings.from_name
 
+        # MailerSend 服务（延迟初始化）
+        self._mailersend_service = None
+
     async def _run_in_executor(self, func, *args):
         """在线程池中运行同步操作"""
         loop = asyncio.get_event_loop()
@@ -212,6 +218,21 @@ class EmailQueue:
         """
         实际发送邮件
 
+        Args:
+            email_data: 邮件数据
+
+        Returns:
+            是否发送成功
+        """
+        if self.email_provider == "mailersend":
+            return await self._send_email_mailersend(email_data)
+        else:
+            return await self._send_email_smtp(email_data)
+
+    async def _send_email_smtp(self, email_data: dict[str, Any]) -> bool:
+        """
+        使用 SMTP 发送邮件
+
         Args:
             email_data: 邮件数据
 
@@ -248,7 +269,53 @@ class EmailQueue:
             return True
 
         except Exception as e:
-            logger.error(f"Failed to send email: {e}")
+            logger.error(f"Failed to send email via SMTP: {e}")
+            return False
+
+    async def _send_email_mailersend(self, email_data: dict[str, Any]) -> bool:
+        """
+        使用 MailerSend 发送邮件
+
+        Args:
+            email_data: 邮件数据
+
+        Returns:
+            是否发送成功
+        """
+        try:
+            # 延迟初始化 MailerSend 服务
+            if self._mailersend_service is None:
+                from app.service.mailersend_service import get_mailersend_service
+
+                self._mailersend_service = get_mailersend_service()
+
+            # 提取邮件数据
+            to_email = email_data.get("to_email", "")
+            subject = email_data.get("subject", "")
+            content = email_data.get("content", "")
+            html_content = email_data.get("html_content", "")
+            metadata_str = email_data.get("metadata", "{}")
+            metadata = json.loads(metadata_str) if metadata_str else {}
+
+            # 发送邮件
+            response = await self._mailersend_service.send_email(
+                to_email=to_email,
+                subject=subject,
+                content=content,
+                html_content=html_content if html_content else None,
+                metadata=metadata,
+            )
+
+            # 检查响应中是否有 id
+            if response and response.get("id"):
+                logger.info(f"Email sent via MailerSend, message_id: {response['id']}")
+                return True
+            else:
+                logger.error("MailerSend response missing 'id'")
+                return False
+
+        except Exception as e:
+            logger.error(f"Failed to send email via MailerSend: {e}")
             return False
 
 

app/service/email_template_service.py

@@ -0,0 +1,184 @@
+"""
+邮件模板服务
+使用 Jinja2 模板引擎，支持多语言邮件
+"""
+
+from datetime import datetime
+from pathlib import Path
+from typing import Any, ClassVar
+
+from app.config import settings
+from app.log import logger
+
+from jinja2 import Environment, FileSystemLoader, Template
+
+
+class EmailTemplateService:
+    """邮件模板服务，支持多语言"""
+
+    # 中文国家/地区代码列表
+    CHINESE_COUNTRIES: ClassVar[list[str]] = [
+        "CN",  # 中国大陆
+        "TW",  # 台湾
+        "HK",  # 香港
+        "MO",  # 澳门
+        "SG",  # 新加坡（有中文使用者）
+    ]
+
+    def __init__(self):
+        """初始化 Jinja2 模板引擎"""
+        # 模板目录路径
+        template_dir = Path(__file__).parent.parent / "templates" / "email"
+
+        # 创建 Jinja2 环境
+        self.env = Environment(
+            loader=FileSystemLoader(str(template_dir)),
+            autoescape=True,
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+
+        logger.info(f"Email template service initialized with template directory: {template_dir}")
+
+    def get_language(self, country_code: str | None) -> str:
+        """
+        根据国家代码获取语言
+
+        Args:
+            country_code: ISO 3166-1 alpha-2 国家代码（如 CN, US）
+
+        Returns:
+            语言代码（zh 或 en）
+        """
+        if not country_code:
+            return "en"
+
+        # 转换为大写
+        country_code = country_code.upper()
+
+        # 检查是否是中文国家/地区
+        if country_code in self.CHINESE_COUNTRIES:
+            return "zh"
+
+        return "en"
+
+    def render_template(
+        self,
+        template_name: str,
+        language: str,
+        context: dict[str, Any],
+    ) -> str:
+        """
+        渲染模板
+
+        Args:
+            template_name: 模板名称（不含语言后缀和扩展名）
+            language: 语言代码（zh 或 en）
+            context: 模板上下文数据
+
+        Returns:
+            渲染后的模板内容
+        """
+        try:
+            # 构建模板文件名
+            template_file = f"{template_name}_{language}.html"
+
+            # 加载并渲染模板
+            template: Template = self.env.get_template(template_file)
+            return template.render(**context)
+
+        except Exception as e:
+            logger.error(f"Failed to render template {template_name}_{language}: {e}")
+            # 如果渲染失败且不是英文，尝试使用英文模板
+            if language != "en":
+                logger.warning(f"Falling back to English template for {template_name}")
+                return self.render_template(template_name, "en", context)
+            raise
+
+    def render_text_template(
+        self,
+        template_name: str,
+        language: str,
+        context: dict[str, Any],
+    ) -> str:
+        """
+        渲染纯文本模板
+
+        Args:
+            template_name: 模板名称（不含语言后缀和扩展名）
+            language: 语言代码（zh 或 en）
+            context: 模板上下文数据
+
+        Returns:
+            渲染后的纯文本内容
+        """
+        try:
+            # 构建模板文件名
+            template_file = f"{template_name}_{language}.txt"
+
+            # 加载并渲染模板
+            template: Template = self.env.get_template(template_file)
+            return template.render(**context)
+
+        except Exception as e:
+            logger.error(f"Failed to render text template {template_name}_{language}: {e}")
+            # 如果渲染失败且不是英文，尝试使用英文模板
+            if language != "en":
+                logger.warning(f"Falling back to English text template for {template_name}")
+                return self.render_text_template(template_name, "en", context)
+            raise
+
+    def render_verification_email(
+        self,
+        username: str,
+        code: str,
+        country_code: str | None = None,
+        expiry_minutes: int = 10,
+    ) -> tuple[str, str, str]:
+        """
+        渲染验证邮件
+
+        Args:
+            username: 用户名
+            code: 验证码
+            country_code: 国家代码
+            expiry_minutes: 验证码过期时间（分钟）
+
+        Returns:
+            (主题, HTML内容, 纯文本内容)
+        """
+        # 获取语言
+        language = self.get_language(country_code)
+
+        # 准备模板上下文
+        context = {
+            "username": username,
+            "code": code,
+            "expiry_minutes": expiry_minutes,
+            "server_name": settings.from_name,
+            "year": datetime.now().year,
+        }
+
+        # 渲染 HTML 和纯文本模板
+        html_content = self.render_template("verification", language, context)
+        text_content = self.render_text_template("verification", language, context)
+
+        # 根据语言设置主题
+        if language == "zh":
+            subject = f"邮箱验证 - {settings.from_name}"
+        else:
+            subject = f"Email Verification - {settings.from_name}"
+
+        return subject, html_content, text_content
+
+
+# 全局邮件模板服务实例
+_email_template_service: EmailTemplateService | None = None
+
+
+def get_email_template_service() -> EmailTemplateService:
+    """获取或创建邮件模板服务实例"""
+    global _email_template_service
+    if _email_template_service is None:
+        _email_template_service = EmailTemplateService()
+    return _email_template_service

app/service/mailersend_service.py

@@ -0,0 +1,87 @@
+"""
+MailerSend 邮件发送服务
+使用 MailerSend API 发送邮件
+"""
+
+from typing import Any
+
+from app.config import settings
+from app.log import logger
+
+from mailersend import EmailBuilder, MailerSendClient
+
+
+class MailerSendService:
+    """MailerSend 邮件发送服务"""
+
+    def __init__(self):
+        if not settings.mailersend_api_key:
+            raise ValueError("MailerSend API Key is required when email_provider is 'mailersend'")
+        if not settings.mailersend_from_email:
+            raise ValueError("MailerSend from email is required when email_provider is 'mailersend'")
+
+        self.client = MailerSendClient(api_key=settings.mailersend_api_key)
+        self.from_email = settings.mailersend_from_email
+        self.from_name = settings.from_name
+
+    async def send_email(
+        self,
+        to_email: str,
+        subject: str,
+        content: str,
+        html_content: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, str]:
+        """
+        使用 MailerSend 发送邮件
+
+        Args:
+            to_email: 收件人邮箱地址
+            subject: 邮件主题
+            content: 邮件纯文本内容
+            html_content: 邮件HTML内容（如果有）
+            metadata: 额外元数据（未使用）
+
+        Returns:
+            返回格式为 {'id': 'message_id'} 的字典
+        """
+        try:
+            _ = metadata  # 避免未使用参数警告
+
+            # 构建邮件
+            email_builder = EmailBuilder()
+            email_builder.from_email(self.from_email, self.from_name)
+            email_builder.to_many([{"email": to_email}])
+            email_builder.subject(subject)
+
+            # 优先使用 HTML 内容，否则使用纯文本
+            if html_content:
+                email_builder.html(html_content)
+            else:
+                email_builder.text(content)
+
+            email = email_builder.build()
+
+            # 发送邮件
+            response = self.client.emails.send(email)
+
+            # 从 APIResponse 中提取 message_id
+            message_id = getattr(response, "id", "") if response else ""
+            logger.info(f"Successfully sent email via MailerSend to {to_email}, message_id: {message_id}")
+            return {"id": message_id}
+
+        except Exception as e:
+            logger.error(f"Failed to send email via MailerSend: {e}")
+            return {"id": ""}
+
+
+# 全局 MailerSend 服务实例
+_mailersend_service: MailerSendService | None = None
+
+
+def get_mailersend_service() -> MailerSendService:
+    """获取或创建 MailerSend 服务实例"""
+    global _mailersend_service
+    if _mailersend_service is None:
+        _mailersend_service = MailerSendService()
+    return _mailersend_service

app/service/verification_service.py

@@ -29,7 +29,9 @@ class EmailVerificationService:
         return "".join(secrets.choice(string.digits) for _ in range(8))
 
     @staticmethod
-    async def send_verification_email_via_queue(email: str, code: str, username: str, user_id: int) -> bool:
+    async def send_verification_email_via_queue(
+        email: str, code: str, username: str, user_id: int, country_code: str | None = None
+    ) -> dict[str, str]:
         """使用邮件队列发送验证邮件
 
         Args:
@@ -37,149 +39,52 @@ class EmailVerificationService:
             code: 验证码
             username: 用户名
             user_id: 用户ID
+            country_code: 国家代码（用于选择邮件语言）
 
         Returns:
-            是否成功将邮件加入队列
+            返回格式为 {'id': 'message_id'} 的字典，如果使用 SMTP 则返回 email_id
         """
         try:
-            # HTML 邮件内容
-            html_content = f"""
-<!DOCTYPE html>
-<html>
-<head>
-    <meta charset="utf-8">
-    <style>
-        .container {{
-            max-width: 600px;
-            margin: 0 auto;
-            font-family: Arial, sans-serif;
-            line-height: 1.6;
-        }}
-        .header {{
-            background: #ED8EA6;
-            color: white;
-            padding: 20px;
-            text-align: center;
-            border-radius: 10px 10px 0 0;
-        }}
-        .content {{
-            background: #f9f9f9;
-            padding: 30px;
-            border: 1px solid #ddd;
-        }}
-        .code {{
-            background: #fff;
-            border: 2px solid #ED8EA6;
-            border-radius: 8px;
-            padding: 15px;
-            text-align: center;
-            font-size: 24px;
-            font-weight: bold;
-            letter-spacing: 3px;
-            margin: 20px 0;
-            color: #333;
-        }}
-        .footer {{
-            background: #333;
-            color: #fff;
-            padding: 15px;
-            text-align: center;
-            border-radius: 0 0 10px 10px;
-            font-size: 12px;
-        }}
-        .warning {{
-            background: #fff3cd;
-            border: 1px solid #ffeaa7;
-            border-radius: 5px;
-            padding: 10px;
-            margin: 15px 0;
-            color: #856404;
-        }}
-    </style>
-</head>
-<body>
-    <div class="container">
-        <div class="header">
-            <h1>osu! 邮箱验证</h1>
-            <p>Email Verification</p>
-        </div>
+            from app.service.email_template_service import get_email_template_service
 
-        <div class="content">
-            <h2>你好 {username}！</h2>
-            <p>请使用以下验证码验证您的账户：</p>
-
-            <div class="code">{code}</div>
-
-            <p>验证码将在 <strong>10 分钟内有效</strong>。</p>
-
-            <div class="warning">
-                <p><strong>重要提示：</strong></p>
-                <ul>
-                    <li>请不要与任何人分享此验证码</li>
-                    <li>如果您没有请求验证码，请忽略此邮件</li>
-                    <li>为了账户安全，请勿在其他网站使用相同的密码</li>
-                </ul>
-            </div>
-
-            <hr style="border: none; border-top: 1px solid #ddd; margin: 20px 0;">
-
-            <h3>Hello {username}!</h3>
-            <p>Please use the following verification code to verify your account:</p>
-
-            <p>This verification code will be valid for <strong>10 minutes</strong>.</p>
-
-            <p><strong>Important:</strong> Do not share this verification code with anyone. If you did not request this code, please ignore this email.</p>
-        </div>
-
-        <div class="footer">
-            <p>© 2025 g0v0! Private Server. 此邮件由系统自动发送，请勿回复。</p>
-            <p>This email was sent automatically, please do not reply.</p>
-        </div>
-    </div>
-</body>
-</html>
-            """  # noqa: E501
-
-            # 纯文本备用内容
-            plain_content = f"""
-你好 {username}！
-
-请使用以下验证码验证您的账户：
-
-{code}
-
-验证码将在10分钟内有效。
-
-重要提示：
-- 请不要与任何人分享此验证码
-- 如果您没有请求验证码，请忽略此邮件
-- 为了账户安全，请勿在其他网站使用相同的密码
-
-Hello {username}!
-Please use the following verification code to verify your account.
-This verification code will be valid for 10 minutes.
-
-© 2025 g0v0! Private Server. 此邮件由系统自动发送，请勿回复。
-This email was sent automatically, please do not reply.
-"""
-
-            # 将邮件加入队列
-            subject = "邮箱验证 - Email Verification"
-            metadata = {"type": "email_verification", "user_id": user_id, "code": code}
-
-            await email_queue.enqueue_email(
-                to_email=email,
-                subject=subject,
-                content=plain_content,
-                html_content=html_content,
-                metadata=metadata,
+            # 使用模板服务生成邮件内容
+            template_service = get_email_template_service()
+            subject, html_content, plain_content = template_service.render_verification_email(
+                username=username,
+                code=code,
+                country_code=country_code,
+                expiry_minutes=10,
             )
+            # 准备元数据
+            metadata = {"type": "email_verification", "user_id": user_id, "code": code, "country": country_code}
 
-            return True
+            # 如果使用 MailerSend，直接发送并返回 message_id
+            if settings.email_provider == "mailersend":
+                from app.service.mailersend_service import get_mailersend_service
+
+                mailersend_service = get_mailersend_service()
+                response = await mailersend_service.send_email(
+                    to_email=email,
+                    subject=subject,
+                    content=plain_content,
+                    html_content=html_content,
+                    metadata=metadata,
+                )
+                return response
+            else:
+                # 使用 SMTP 队列发送
+                email_id = await email_queue.enqueue_email(
+                    to_email=email,
+                    subject=subject,
+                    content=plain_content,
+                    html_content=html_content,
+                    metadata=metadata,
+                )
+                return {"id": email_id}
 
         except Exception as e:
             logger.error(f"Failed to enqueue email: {e}")
-            return False
+            return {"id": ""}
 
     @staticmethod
     def generate_session_token() -> str:
@@ -247,13 +152,28 @@ This email was sent automatically, please do not reply.
         email: str,
         ip_address: str | None = None,
         user_agent: UserAgentInfo | None = None,
-    ) -> bool:
-        """发送验证邮件"""
+        country_code: str | None = None,
+    ) -> dict[str, str]:
+        """发送验证邮件
+
+        Args:
+            db: 数据库会话
+            redis: Redis 客户端
+            user_id: 用户ID
+            username: 用户名
+            email: 邮箱地址
+            ip_address: IP 地址
+            user_agent: 用户代理信息
+            country_code: 国家代码（用于选择邮件语言）
+
+        Returns:
+            返回格式为 {'id': 'message_id'} 的字典
+        """
         try:
             # 检查是否启用邮件验证功能
             if not settings.enable_email_verification:
                 logger.debug(f"Email verification is disabled, skipping for user {user_id}")
-                return True  # 返回成功，但不执行验证流程
+                return {"id": "disabled"}  # 返回特殊ID表示功能已禁用
 
             # 检测客户端信息
             logger.info(f"Detected client for user {user_id}: {user_agent}")
@@ -267,18 +187,22 @@ This email was sent automatically, please do not reply.
             )
 
             # 使用邮件队列发送验证邮件
-            success = await EmailVerificationService.send_verification_email_via_queue(email, code, username, user_id)
+            response = await EmailVerificationService.send_verification_email_via_queue(
+                email, code, username, user_id, country_code
+            )
 
-            if success:
-                logger.info(f"Successfully enqueued verification email to {email} (user: {username})")
-                return True
+            if response and response.get("id"):
+                logger.info(
+                    f"Successfully sent verification email to {email} (user: {username}), message_id: {response['id']}"
+                )
+                return response
             else:
-                logger.error(f"Failed to enqueue verification email: {email} (user: {username})")
-                return False
+                logger.error(f"Failed to send verification email: {email} (user: {username})")
+                return {"id": ""}
 
         except Exception as e:
             logger.error(f"Exception during sending verification email: {e}")
-            return False
+            return {"id": ""}
 
     @staticmethod
     async def verify_email_code(
@@ -339,37 +263,52 @@ This email was sent automatically, please do not reply.
         email: str,
         ip_address: str | None = None,
         user_agent: UserAgentInfo | None = None,
-    ) -> tuple[bool, str]:
-        """重新发送验证码"""
+        country_code: str | None = None,
+    ) -> tuple[bool, str, dict[str, str]]:
+        """重新发送验证码
+
+        Args:
+            db: 数据库会话
+            redis: Redis 客户端
+            user_id: 用户ID
+            username: 用户名
+            email: 邮箱地址
+            ip_address: IP 地址
+            user_agent: 用户代理信息
+            country_code: 国家代码（用于选择邮件语言）
+
+        Returns:
+            (是否成功, 消息, {'id': 'message_id'})
+        """
         try:
             # 避免未使用参数警告
             _ = user_agent
             # 检查是否启用邮件验证功能
             if not settings.enable_email_verification:
                 logger.debug(f"Email verification is disabled, skipping resend for user {user_id}")
-                return True, "验证码已发送（邮件验证功能已禁用）"
+                return True, "验证码已发送（邮件验证功能已禁用）", {"id": "disabled"}
 
             # 检查重发频率限制（60秒内只能发送一次）
             rate_limit_key = f"email_verification_rate_limit:{user_id}"
             if await redis.get(rate_limit_key):
-                return False, "请等待60秒后再重新发送"
+                return False, "请等待60秒后再重新发送", {"id": ""}
 
             # 设置频率限制
             await redis.setex(rate_limit_key, 60, "1")
 
             # 生成新的验证码
-            success = await EmailVerificationService.send_verification_email(
-                db, redis, user_id, username, email, ip_address, user_agent
+            response = await EmailVerificationService.send_verification_email(
+                db, redis, user_id, username, email, ip_address, user_agent, country_code
             )
 
-            if success:
-                return True, "验证码已重新发送"
+            if response and response.get("id"):
+                return True, "验证码已重新发送", response
             else:
-                return False, "重新发送失败，请稍后再试"
+                return False, "重新发送失败，请稍后再试", {"id": ""}
 
         except Exception as e:
             logger.error(f"Exception during resending verification code: {e}")
-            return False, "重新发送过程中发生错误"
+            return False, "重新发送过程中发生错误", {"id": ""}
 
 
 class LoginSessionService:
@@ -573,7 +512,7 @@ class LoginSessionService:
                 await db.exec(
                     select(exists()).where(
                         LoginSession.user_id == user_id,
-                        col(LoginSession.is_verified).is_(False),
+                        col(LoginSession.is_verified).is_(False),  # pyright: ignore[reportAttributeAccessIssue]
                         LoginSession.expires_at > utcnow(),
                         LoginSession.token_id == token_id,
                     )