跳转至

ASP.NET Core

适用于 ASP.NET Core 8+（.NET）应用的集成指南。Mailexam 通过 MailKit 库作为 SMTP 接入。

前置条件

  • Mailexam 账户，以及已创建并具备 SMTP 凭据的项目。
  • .NET SDK 8 或更高版本。

从项目的欢迎邮件（或控制台）中复制：

  • YOUR_LOGIN — SMTP 登录名（例如 xxxxx）；
  • YOUR_PASSWORD — SMTP 密码（与登录名成对的唯一凭据）；
  • 主机 — YOUR_LOGIN.mailexam.cn（与登录名一致）。

1. 依赖

dotnet new web -n MailexamWeb
cd MailexamWeb
dotnet add package MailKit

MailexamWeb.csproj 片段：

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="MailKit" Version="4.8.0" />
  </ItemGroup>
</Project>

2. 环境变量

启动前设置变量（User Secrets、IDE 运行配置，或通过工具使用 .env）：

MAILEXAM_LOGIN=YOUR_LOGIN
MAILEXAM_PASSWORD=YOUR_PASSWORD
MAILEXAM_PORT=587
MAIL_FROM=noreply@example.test

SMTP 主机：YOUR_LOGIN.mailexam.cn。

发件人地址

MAIL_FROM 可以是任意测试地址——邮件进入 Mailexam，而非真实收件人。

备选端口

MAILEXAM_PORT=587

SecureSocketOptions.StartTls

MAILEXAM_PORT=2525

STARTTLS，与 587 相同。

MAILEXAM_PORT=465

SecureSocketOptions.SslOnConnect

MAILEXAM_PORT=25

SecureSocketOptions.None

3. 发送服务

Services/MailService.cs：

using MailKit.Net.Smtp;
using MailKit.Security;
using MimeKit;

namespace MailexamWeb.Services;

public class MailService
{
    public async Task SendTestAsync(string? to, string? subject, string? body, CancellationToken ct = default)
    {
        var login = Environment.GetEnvironmentVariable("MAILEXAM_LOGIN")
            ?? throw new InvalidOperationException("MAILEXAM_LOGIN is not set");
        var password = Environment.GetEnvironmentVariable("MAILEXAM_PASSWORD")
            ?? throw new InvalidOperationException("MAILEXAM_PASSWORD is not set");

        var port = int.Parse(Environment.GetEnvironmentVariable("MAILEXAM_PORT") ?? "587");
        var from = Environment.GetEnvironmentVariable("MAIL_FROM") ?? "noreply@example.test";

        to ??= "user@example.test";
        subject ??= "ASP.NET Core + Mailexam";
        body ??= "来自 ASP.NET Core 的 Mailexam 测试";

        var message = new MimeMessage();
        message.From.Add(MailboxAddress.Parse(from));
        message.To.Add(MailboxAddress.Parse(to));
        message.Subject = subject;
        message.Body = new TextPart("plain") { Text = body };

        using var client = new SmtpClient();
        await client.ConnectAsync($"{login}.mailexam.cn", port, GetSecureSocketOptions(port), ct);
        await client.AuthenticateAsync(login, password, ct);
        await client.SendAsync(message, ct);
        await client.DisconnectAsync(true, ct);
    }

    private static SecureSocketOptions GetSecureSocketOptions(int port) => port switch
    {
        465 => SecureSocketOptions.SslOnConnect,
        25 => SecureSocketOptions.None,
        _ => SecureSocketOptions.StartTls,
    };
}

4. Minimal API

Program.cs：

using MailexamWeb.Services;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<MailService>();

var app = builder.Build();

app.MapPost("/mail/test", async (SendRequest request, MailService mail, CancellationToken ct) =>
{
    await mail.SendTestAsync(request.To, request.Subject, request.Body, ct);
    return Results.Ok(new { status = "ok" });
});

app.Run("http://127.0.0.1:8080");

public record SendRequest(string? To, string? Subject, string? Body);

启动并验证：

export MAILEXAM_LOGIN=YOUR_LOGIN
export MAILEXAM_PASSWORD=YOUR_PASSWORD
export MAILEXAM_PORT=587
export MAIL_FROM=noreply@example.test

dotnet run

curl -X POST http://127.0.0.1:8080/mail/test \
  -H 'Content-Type: application/json' \
  -d '{"to":"user@example.test","subject":"测试","body":"你好"}'

邮件将出现在 Mailexam 控制台 → 您的项目 → 收件箱。

User Secrets（本地）

dotnet user-secrets init
dotnet user-secrets set MAILEXAM_LOGIN YOUR_LOGIN
dotnet user-secrets set MAILEXAM_PASSWORD YOUR_PASSWORD

要在开发环境将 secrets 作为环境变量读取，可添加 Microsoft.Extensions.Configuration.UserSecrets 包 — 上述示例中 export 或 CI 密钥已足够。

5. 本地开发与 CI

环境 建议
local User Secrets 或运行配置中的变量
CI GitLab CI/CD Variables 中的密钥 MAILEXAM_LOGIN、MAILEXAM_PASSWORD

.gitlab-ci.yml 示例：

variables:
  MAILEXAM_LOGIN: $MAILEXAM_LOGIN
  MAILEXAM_PASSWORD: $MAILEXAM_PASSWORD
  MAILEXAM_PORT: "587"
  MAIL_FROM: "noreply@example.test"

集成测试后，通过 Mailexam API 验证投递。

6. 常见问题

TLS 或认证失败

  • 连接主机 — {login}.mailexam.cn，AuthenticateAsync 中的登录名 — 来自邮件。
  • 登录名和密码为同一项目的邮件成对凭据。

587 端口

  • 使用 SecureSocketOptions.StartTls，而非 SslOnConnect。

控制台中看不到邮件

  • 查看同一 Mailexam 项目的收件箱。
  • 启用详细日志：在 appsettings.Development.json 中设置 "Logging:LogLevel:Default": "Debug"。

参见