如何在ASP.NET Core Web API中集成Stalwart JMAP？

1. 获取JMAP会话端点配置 #

首先必须通过/.well-known/jmap端点获取Stalwart JMAP服务器的核心配置（比如API端点、支持的能力集、认证方式等）。以下是ASP.NET Core中使用HttpClient实现的代码：

代码示例：获取会话信息 #

using System.Net.Http.Headers;
using System.Text.Json;

public class JmapSessionService
{
    private readonly HttpClient _httpClient;

    // 通过依赖注入注入HttpClient
    public JmapSessionService(HttpClient httpClient)
    {
        _httpClient = httpClient;
        _httpClient.BaseAddress = new Uri("https://your-stalwart-server-domain/");
    }

    public async Task<JmapSession> GetSessionAsync(string username, string password)
    {
        // 添加基本认证头（Stalwart默认支持Basic Auth，若用OAuth2需替换为Bearer Token）
        var credentials = Convert.ToBase64String(System.Text.Encoding.ASCII.GetBytes($"{username}:{password}"));
        _httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

        var response = await _httpClient.GetAsync("/.well-known/jmap");
        response.EnsureSuccessStatusCode();

        var jsonContent = await response.Content.ReadAsStringAsync();
        return JsonSerializer.Deserialize<JmapSession>(jsonContent, new JsonSerializerOptions { PropertyNameCaseInsensitive = true });
    }
}

// 会话响应模型类
public class JmapSession
{
    public string AccountId { get; set; }
    public Dictionary<string, string> Accounts { get; set; }
    public string ApiUrl { get; set; }
    public string UploadUrl { get; set; }
    public string DownloadUrl { get; set; }
    public List<string> Capabilities { get; set; }
}

2. 发送JMAP请求并处理响应 #

获取到会话的ApiUrl后，就可以向该端点发送POST请求执行JMAP操作（比如获取邮件、创建邮件等）。JMAP请求是一个JSON数组，每个元素代表一个方法调用。

代码示例：获取邮箱列表 #

public async Task<JmapResponse> GetMailboxesAsync(JmapSession session)
{
    // 构造JMAP请求体：获取邮箱列表
    var jmapRequest = new[]
    {
        new
        {
            methodName = "Mailbox/get",
            arguments = new { accountId = session.AccountId },
            methodCallId = "1"
        }
    };

    var jsonRequest = JsonSerializer.Serialize(jmapRequest);
    var content = new StringContent(jsonRequest, System.Text.Encoding.UTF8, "application/json");

    // 发送POST请求到JMAP API端点
    var response = await _httpClient.PostAsync(session.ApiUrl, content);
    response.EnsureSuccessStatusCode();

    var jsonResponse = await response.Content.ReadAsStringAsync();
    return JsonSerializer.Deserialize<JmapResponse>(jsonResponse, new JsonSerializerOptions { PropertyNameCaseInsensitive = true });
}

// JMAP响应模型类
public class JmapResponse
{
    public List<JmapMethodResponse> Responses { get; set; }
}

public class JmapMethodResponse
{
    public string MethodName { get; set; }
    public MailboxGetResult Arguments { get; set; }
    public string MethodCallId { get; set; }
}

public class MailboxGetResult
{
    public List<Mailbox> List { get; set; }
}

public class Mailbox
{
    public string Id { get; set; }
    public string Name { get; set; }
    public string ParentId { get; set; }
    public int TotalEmails { get; set; }
}

3. 关键注意事项 #

• 认证方式：Stalwart JMAP支持Basic Auth和OAuth2，生产环境建议使用OAuth2，需在Stalwart后台配置OAuth客户端后，通过授权码流程获取Bearer Token替换Basic Auth头。
• 能力集校验：发送请求前可通过会话的Capabilities字段确认服务器支持的操作（比如是否支持Mailbox/get、Email/get等）。
• 错误处理：实际代码中需添加异常捕获（比如HttpRequestException），并解析JMAP响应中的错误信息（若存在）。
• HttpClient复用：ASP.NET Core中建议通过IHttpClientFactory注入HttpClient，避免频繁创建实例导致的资源浪费。

内容的提问来源于stack exchange，提问作者Mudasir Rehman