MsClean.Framework.Mailing 1.10.2

MsClean.Framework.Mailing

.NET projelerinde SMTP üzerinden merkezi ve yapılandırılabilir mail gönderimi için MailKit/MimeKit tabanlı servis kütüphanesi.

Yazar: Yusuf Günay

İçindekiler

• Genel Bakış
• Proje Yapısı
• Bileşenler
• Kurulum ve Yapılandırma
• Kullanım
• Özellikler
• Mail Gönderim Akışı
• Sık Karşılaşılan Sorunlar
• Geliştirme Önerileri

Genel Bakış

MsClean.Framework.Mailing, mail gönderme sorumluluğunu uygulamanın geneline dağıtmak yerine tek bir servis katmanında toplamak amacıyla tasarlanmıştır.

Kütüphane; HTML mail, düz metin mail, CC/BCC desteği, ek dosya gönderimi, List-Unsubscribe header ve DKIM imzalama özelliklerini sağlar.

Kullanılan Kütüphaneler

Proje Yapısı

MsClean.Framework.Mailing
├── Abstraction
│   └── IMailService.cs
├── Models
│   ├── Mail.cs
│   ├── MailSettings.cs
│   └── ToEmail.cs
└── Providers
    └── MailKit
        └── MailKitMailService.cs

Bileşenler

IMailService

Mail gönderme servisinin sözleşmesidir. Uygulama katmanı doğrudan MailKitMailService yerine bu interface üzerinden çalışır. Bu yapı, ilerleyen süreçte farklı mail sağlayıcılarına geçişi kolaylaştırır.

public interface IMailService
{
    void SendMail(Mail mail);
    Task SendEmailAsync(Mail mail);
}

Web uygulamalarında SendEmailAsync tercih edilmelidir.

Mail

Gönderilecek mailin içeriğini taşıyan modeldir.

MailSettings

SMTP bağlantı ve DKIM imzalama ayarlarını taşır.

Yaygın Port Yapılandırmaları

ToEmail

Alıcı bilgisini taşıyan basit modeldir. Email ve FullName alanlarından oluşur.

Mevcut implementasyonda doğrudan ToEmail yerine MimeKit'in MailboxAddress tipi kullanılmaktadır.

MailKitMailService

IMailService interface'ini uygulayan gerçek gönderim servisidir. Constructor üzerinden MailSettings alır ve SMTP bağlantısını bu ayarlara göre kurar.

emailPrepare Metodu

Gönderim öncesi MimeMessage nesnesini ve SMTP client'ı hazırlar:

1. MimeMessage oluşturur.
2. From, To, CC ve BCC bilgilerini ekler.
3. Subject bilgisini atar.
4. Text ve HTML body oluşturur.
5. UnsubscribeLink doluysa List-Unsubscribe header ekler.
6. DKIM ayarları yapılandırılmışsa maili imzalar.
7. SMTP client oluşturur ve sunucuya bağlanır.
8. AuthenticationRequired aktifse kimlik doğrulama yapar.

Kurulum ve Yapılandırma

appsettings.json

{
  "MailSettings": {
    "Server": "smtp.example.com",
    "Port": 587,
    "SenderFullName": "MsClean System",
    "SenderEmail": "noreply@example.com",
    "UserName": "noreply@example.com",
    "Password": "smtp-password",
    "AuthenticationRequired": true
  }
}

⚠️ SMTP şifresi kaynak koda yazılmamalıdır. Geliştirme ortamında User Secrets, production ortamında güvenli bir secret yönetim sistemi kullanılmalıdır.

Program.cs — Servis Kaydı

var mailSettings = builder.Configuration.GetSection("MailSettings").Get<MailSettings>();
builder.Services.AddSingleton(mailSettings!);
builder.Services.AddScoped<IMailService, MailKitMailService>();

Bu kayıttan sonra IMailService, herhangi bir controller veya servis sınıfına inject edilebilir.

Kullanım

Temel Mail Gönderimi

var mail = new Mail
{
    Subject = "Test Mail",
    TextBody = "Bu bir test mailidir.",
    HtmlBody = "<p>Bu bir test mailidir.</p>",
    ToList = [new MailboxAddress("Yusuf", "yusuf@example.com")]
};

await _mailService.SendEmailAsync(mail);

CC, BCC ve Ek Dosya

var mail = new Mail
{
    Subject = "Rapor",
    HtmlBody = "<p>Ekteki raporu inceleyebilirsiniz.</p>",
    TextBody  = "Ekteki raporu inceleyebilirsiniz.",
    ToList    = [new MailboxAddress("Alıcı", "alici@example.com")],
    CcList    = [new MailboxAddress("Bilgi", "bilgi@example.com")],
    BccList   = [new MailboxAddress("Gizli", "gizli@example.com")],
    Attachments = [ /* MimePart nesneleri */ ]
};

await _mailService.SendEmailAsync(mail);

Unsubscribe ve DKIM

• UnsubscribeLink alanı dolu olduğunda mail header'ına List-Unsubscribe eklenir.
• DKIM imzalama için appsettings.json içinde DkimPrivateKey, DkimSelector ve DomainName alanlarının tanımlı olması gerekir.

Mail Gönderim Akışı

Mail nesnesi hazırlanır
        │
        ▼
IMailService.SendEmailAsync çağrılır
        │
        ▼
MimeMessage oluşturulur
        │
        ▼
From / To / CC / BCC bilgileri eklenir
        │
        ▼
Text ve HTML body eklenir
        │
        ├─► UnsubscribeLink varsa → List-Unsubscribe header eklenir
        │
        ├─► DKIM ayarları varsa → Mail imzalanır
        │
        ▼
SMTP client oluşturulur, sunucuya bağlanılır
        │
        ▼
AuthenticationRequired = true → Kimlik doğrulama yapılır
        │
        ▼
Mail gönderilir → Bağlantı kapatılır

Sık Karşılaşılan Sorunlar